解决Python打开图片时的FileNotFoundError和格式错误

Mason
Mason
发布时间:2026-11-22| 6人浏览过
原创

深入解析在Python中使用Pillow或OpenCV打开图片时遇到的FileNotFoundError与格式错误(UnidentifiedImageError/NoneType),提供清晰的排查步骤、底层原理对比与健壮的代码修复方案。

在 Python 中使用 Pillow(PIL)或 OpenCV 读取图片时,初学者最常遇到的两类报错分别是 FileNotFoundError: [Errno 2] No such file or directory 和图片格式无法解析错误(例如 Pillow 的 UnidentifiedImageError 或 OpenCV cv2.imread 静默返回 None 后引发的 AttributeError)。要彻底解决这些报错,不能仅靠在代码中盲目更改相对路径或文件后缀,而必须理解 Python 进程的“当前工作目录”与底层图形解码库的工作机制。

一、FileNotFoundError 的成因:工作目录与脚本目录的脱节

许多开发者最困惑的问题是:“图片明明和 Python 脚本放在同一个文件夹里,为什么运行代码依然提示找不到文件?”

这里的关键认知盲区在于混淆了脚本所在的绝对路径与Python 进程的当前工作目录(Current Working Directory, CWD)。当我们在代码中书写相对路径(如 Image.open("photo.jpg"))时,操作系统并不是从 Python 脚本所在的位置开始寻找,而是从启动该 Python 进程的终端目录出发去解析。

常见场景:在项目根目录 /my_project 下打开终端,执行子目录脚本 python scripts/load_img.py,此时工作目录是 /my_project。如果脚本中写了 photo.jpg,Python 会在 /my_project/photo.jpg 寻找,而非 /my_project/scripts/photo.jpg,从而必然触发 FileNotFoundError。

解决Python打开图片时的FileNotFoundError和格式错误
图 1:Python 相对路径解析机制与基于 pathlib 的绝对锚定方案对比

其他导致文件找不到的典型细节

  • Windows 反斜杠转义:直接写字符串 "C:\test\new_image.png",其中的 \t 会被解析为制表符,\n 会被解析为换行符。必须使用原始字符串 r"C:\test\new_image.png" 或统一使用正斜杠 "C:/test/new_image.png"。
  • 操作系统隐藏已知扩展名:在 Windows 资源管理器中如果勾选了“隐藏已知文件类型的扩展名”,一个实际名为 photo.jpg.jpg 或 photo.png.txt 的文件在界面上只会显示为 photo.jpg,导致在代码中传入 photo.jpg 时抛出未找到异常。
  • 隐蔽的空白符或全角字符:文件名复制粘贴时夹带了首尾空格,或者中文字符串包含了全角句点等。

二、排查与修复 FileNotFoundError 的四步流程

当程序抛出 FileNotFoundError 时,不要盲目去网上搜索代码片段,建议严格按照以下四步顺序进行排查:

解决Python打开图片时的FileNotFoundError和格式错误
图 2:排查并彻底修复 FileNotFoundError 的标准四步操作步骤

标准修复代码:基于 pathlib 的安全定位

from pathlib import Path
from PIL import Image

# 1. 取得当前正在执行的脚本所在目录的绝对路径
SCRIPT_DIR = Path(__file__).resolve().parent

# 2. 通过路径操作符 / 拼接跨平台兼容的文件路径
image_path = SCRIPT_DIR / "assets" / "sample.jpg"

# 3. 前置防御性校验
if not image_path.is_file():
    raise FileNotFoundError(f"未找到指定的图像文件,解析后的绝对路径为: {image_path}")

# 4. 安全打开图像
with Image.open(image_path) as img:
    print(f"成功打开图像,尺寸: {img.size},格式: {img.format}")

三、图像格式解析错误的成因与修复方案

当路径已经正确解析,且文件确实存在时,程序有时会抛出格式错误。典型的表现有两种:

  1. Pillow 库报错:PIL.UnidentifiedImageError: cannot identify image file ...
  2. OpenCV 库报错:cv2.imread() 并未抛出异常,而是静默返回了 None。随后执行 img.shape 时出现 AttributeError: 'NoneType' object has no attribute 'shape'。
解决Python打开图片时的FileNotFoundError和格式错误
图 3:图像扩展名假象与底层二进制魔数校验机制对比

格式错误的三大核心根源与解决方案

报错场景与表现 根本原因 诊断与应对方案
Pillow 抛出 UnidentifiedImageError 文件内容并非真实图片格式(如网络爬虫下载到的是反爬拦截页、404 HTML 或 JSON 文本,但保存成了 .jpg)。 以文本方式或二进制方式读取前 16 字节,检查是否包含 <!DOCTYPE html 等文本标记;核对下载流程中的 HTTP 响应状态码。
cv2.imread 返回 None(带中文路径) 在 Windows 系统上,OpenCV 原生 C++ 底层实现默认使用系统代码页解析路径,当路径中包含中文字符或空格时无法识别。 禁止直接将中文路径传给 cv2.imread,改用 np.fromfile() 配合 cv2.imdecode()。
文件大小为 0 字节或下载被截断 网络请求尚未写入完成便过早读取,或者写盘过程异常退出导致空文件。 加载前加入 os.path.getsize(path) > 0 检查,并捕获 IO 异常。

OpenCV 中文路径与二进制防坑方案

以下是使用 OpenCV 在 Windows 或跨平台环境中支持中文路径的标准函数实现:

import cv2
import numpy as np
from pathlib import Path

def imread_unicode(file_path):
    """
    支持任意中文或特殊字符路径的安全图片读取函数
    """
    path_obj = Path(file_path).resolve()
    if not path_obj.is_file():
        raise FileNotFoundError(f"文件不存在: {path_obj}")
    
    # 检查文件大小是否异常
    if path_obj.stat().st_size == 0:
        raise ValueError(f"文件大小为 0 字节,属于无效文件: {path_obj}")

    # 读取全部二进制字节流至 numpy 数组,再使用 OpenCV 解码
    raw_bytes = np.fromfile(str(path_obj), dtype=np.uint8)
    image = cv2.imdecode(raw_bytes, cv2.IMREAD_COLOR)

    if image is None:
        raise ValueError(f"OpenCV 解码失败,文件内容可能损坏或不是合法的图像格式: {path_obj}")

    return image

四、健壮的工程化图片读取综合实现

在实际生产或批量数据处理工程中,不建议直接裸调 Image.open 或 cv2.imread。一个稳健的图像加载器应当同时集成路径规范化、真实文件类型探测、零字节拦截以及异常保护。

解决Python打开图片时的FileNotFoundError和格式错误
图 4:解决 Python 打开图片两大类报错的防护要点与实施清单

生产级综合加载示例代码

from pathlib import Path
from PIL import Image, UnidentifiedImageError

def load_image_safely(file_path):
    """
    具备完整异常捕获与路径防御的通用图片加载函数
    """
    path = Path(file_path).resolve()

    # 1. 基础物理路径排查
    if not path.exists():
        raise FileNotFoundError(f"[路径错误] 指定的文件不存在: {path}")
    if not path.is_file():
        raise IsADirectoryError(f"[目标类型错误] 目标是目录而非文件: {path}")

    # 2. 0 字节文件校验
    if path.stat().st_size == 0:
        raise ValueError(f"[文件损坏] 文件大小为 0 字节: {path}")

    # 3. 头部特征快速核验
    with open(path, "rb") as f:
        header = f.read(16)
        # 常见伪装拦截:下载到了 HTML 报错页面
        if b"<html" in header.lower() or b"<!doctype" in header.lower():
            raise ValueError(f"[格式伪装] 文件内容为 HTML 文本,非有效图像: {path}")

    # 4. 尝试利用 Pillow 载入并验证
    try:
        # 打开文件句柄并验证格式头
        image = Image.open(path)
        image.verify()  # 校验文件头部完整性
        
        # verify() 之后必须重新 open 才能继续进行处理/读取像素
        image = Image.open(path)
        image.load()    # 强制将图像数据解码进内存
        return image
    except UnidentifiedImageError:
        raise ValueError(f"[格式不支持或损坏] Pillow 无法识别图像格式: {path}")
    except Exception as e:
        raise RuntimeError(f"[读取异常] 打开图片时发生未知错误: {e}")

总结

解决 Python 打开图片时的报错,核心在于建立明确的排查边界:

  • 面对 FileNotFoundError:立即打印 os.getcwd() 和绝对路径,使用 pathlib.Path(__file__).resolve().parent 将路径牢牢锚定在脚本所在目录,消除对当前工作目录的被动依赖。
  • 面对格式与解析错误:牢记“扩展名仅是表面标签,二进制文件头才是格式本质”。通过校验文件体积、验证魔数特征,并在 OpenCV 中使用 np.fromfile 处理中文路径,即可彻底消除绝大多数解析异常。

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。