Python zipfile 怎样区分坏压缩包和读取错误

处理上传文件或离线归档时，最容易误判的是：zipfile 抛出异常，就把它统一写成“压缩包坏了”。更稳妥的判断是看异常发生在哪一层：文件还没有被识别成 ZIP，归档目录无法解析，还是某个成员真正读取时出现 CRC、密码、压缩算法或底层 I/O 问题。

官方地址：https://docs.python.org/3/library/zipfile.html

先看错误发生在哪一层

我在处理归档入口时，会先把问题拆成三层，而不是先写一个很宽的 except Exception。第一层是文件字节流是否像 ZIP；第二层是 ZIP 的目录、文件头等结构能否被 ZipFile 解析；第三层是具体成员能否解压并通过完整性检查。三层都失败时，异常类型和可记录的信息并不相同。

用 is_zipfile 与 ZipFile 判断归档入口

zipfile.is_zipfile() 根据 ZIP 的特征标识判断文件或文件对象是否是有效 ZIP。它适合做入口分流，但它不是“所有成员都能解压”的保证。通过入口判断后仍要用 ZipFile 打开归档，并把 BadZipFile 单独记录。

from pathlib import Path
import zipfile


def classify_archive_entry(path: str) -> str:
    # 先判断文件是否存在，避免把普通文件系统错误误报成坏 ZIP。
    archive = Path(path)
    if not archive.is_file():
        return "input-not-file"

    # 入口判断只回答“像不像 ZIP”，不代替成员完整性检查。
    if not zipfile.is_zipfile(archive):
        return "not-a-zip"

    try:
        # 这里只打开并解析归档结构，暂时不读取所有成员内容。
        with zipfile.ZipFile(archive, "r") as zf:
            zf.infolist()
    except zipfile.BadZipFile:
        # 能识别出特征但目录或文件头无法解析时，保留结构损坏分类。
        return "bad-zip-structure"
    except OSError:
        # 权限、路径、设备或网络文件系统问题属于底层 I/O。
        return "archive-io-error"
    return "archive-opened"

这里故意没有把所有异常都映射为 bad-zip-structure：文件不存在、权限不足和归档结构损坏是不同的处理方向。若需要把异常详情写入日志，可以在返回分类的同时保存异常类名和原始消息，但不要只保存一条“压缩包损坏”。

用 testzip 定位 CRC 或文件头损坏

归档能够打开，并不代表每个成员都完整。官方文档对 ZipFile.testzip() 的定义很明确：它读取归档中的文件并检查 CRC 和文件头；返回第一个坏文件的名字，全部通过时返回 None。这正好适合区分“目录可以读”和“成员内容可靠”这两个结论。

import zipfile


def find_bad_member(path: str) -> dict:
    try:
        with zipfile.ZipFile(path, "r") as zf:
            # testzip 会扫描成员并做 CRC、文件头检查，返回首个异常成员。
            bad_name = zf.testzip()
            if bad_name is None:
                return {"status": "members-ok", "member": None}
            return {"status": "member-corrupt", "member": bad_name}
    except zipfile.BadZipFile as exc:
        # 归档级结构失败时没有可靠的成员名可返回。
        return {"status": "bad-zip-structure", "member": None, "error": str(exc)}
    except OSError as exc:
        # 打开文件或扫描过程中出现系统 I/O 问题时保留原异常。
        return {"status": "archive-io-error", "member": None, "error": str(exc)}

testzip() 返回成员名时，结论应写成“第一个发现完整性问题的成员是 X”，而不是宣称只有 X 一个成员坏了。它返回第一个坏成员，后续成员是否也有问题，需要在业务允许的情况下进一步处理。对超大归档，完整扫描还意味着额外的读取成本，入口服务可以把它放到异步检查或导入前的专门队列里。

成员读取错误不一定等于坏压缩包

当 ZipFile 已经成功打开，具体成员在 read() 或 open() 阶段失败时，要继续看异常语义。官方文档列出的解压失败原因包括密码不正确、CRC 校验、ZIP 格式、未支持的压缩方法和解密问题；此外，缺少对应的可选压缩模块也会影响读取。

import zipfile


def read_member(path: str, member: str, password: bytes | None = None) -> bytes:
    try:
        with zipfile.ZipFile(path, "r") as zf:
            # read 会把目标成员解压到内存，适合小文件或已知大小的内容。
            return zf.read(member, pwd=password)
    except KeyError:
        # 归档存在，但请求的成员名不在目录中。
        raise RuntimeError(f"archive-member-missing: {member}")
    except RuntimeError as exc:
        # 密码错误、缺少解压模块或不支持的压缩方法常在此层暴露。
        raise RuntimeError(f"member-decompression-error: {exc}") from exc
    except (zipfile.BadZipFile, zipfile.LargeZipFile) as exc:
        # 归档格式或 ZIP64 相关问题仍保留原异常类型。
        raise RuntimeError(f"archive-format-error: {exc}") from exc
    except OSError as exc:
        # 文件句柄、权限或底层存储错误不能归因于 CRC 损坏。
        raise RuntimeError(f"member-io-error: {exc}") from exc

实际项目里还要注意两类边界：一是 read() 默认会返回完整字节，超大成员可能带来内存压力；二是已经关闭的 ZipFile 再调用读取方法会得到 ValueError，这属于对象生命周期错误，不是 ZIP 内容损坏。若用 open() 返回成员流，读取流本身的异常也应记录为“成员读取阶段”，不要回写成“入口文件不是 ZIP”。

把判断封装成可记录的诊断结果

推荐返回稳定的状态、成员名和原始异常，而不是让上层依赖异常文本。下面的封装只负责分类，不自动删除文件、重试下载或解压到目标目录；这些动作应该由调用方依据状态决定。

from dataclasses import dataclass
import zipfile


@dataclass
class ZipDiagnosis:
    # status 用于程序分支，member 用于定位具体归档成员。
    status: str
    member: str | None = None
    error_type: str | None = None
    message: str | None = None


def diagnose_zip(path: str) -> ZipDiagnosis:
    try:
        with zipfile.ZipFile(path, "r") as zf:
            # 先做归档级和成员级检查，再决定是否进入业务读取。
            bad_member = zf.testzip()
            if bad_member is not None:
                return ZipDiagnosis("member-corrupt", member=bad_member)
            return ZipDiagnosis("valid-zip")
    except zipfile.BadZipFile as exc:
        # 目录、文件头等归档结构无法解析。
        return ZipDiagnosis("bad-zip-structure", error_type=type(exc).__name__, message=str(exc))
    except (OSError, ValueError) as exc:
        # OSError 是底层 I/O，ValueError 常见于文件对象生命周期不正确。
        return ZipDiagnosis("read-environment-error", error_type=type(exc).__name__, message=str(exc))

这段分类的重点是把 member-corrupt 和 bad-zip-structure 分开：前者已经拿到归档成员名，后者连可靠的成员目录都没有。若业务还要读取加密成员或特定压缩算法，可以在实际读取函数周围另加 RuntimeError 分类，并记录所请求的成员名。

速查表与常见追问

is_zipfile 返回 True 后还需要 testzip 吗？

如果后续要依赖成员内容，建议需要。is_zipfile 解决的是入口识别，testzip 才会把成员读取和 CRC、文件头检查纳入判断。

testzip 返回 None 能否保证解压到目标目录一定成功？

不能。它主要检查成员读取过程中的文件头和 CRC；目标目录权限、路径长度、磁盘空间、密码和资源限制仍可能让后续解压失败。

为什么不直接捕获 Exception 返回“坏包”？

因为文件不存在、权限错误、成员不存在、密码错误和对象已关闭都需要不同处理。捕获具体异常并保留原始类型，才能让日志、重试和人工处理有依据。