Python zipfile.Path 如何安全读取压缩包内文件：路径遍历、目录判断与解压边界

处理用户上传的 ZIP 时，很多代码会先用 zipfile.Path 浏览压缩包，再决定要不要读取某个文件。这个 API 很顺手，但它只负责“在归档里走路径”，不会替你清理恶意成员名；如果把它得到的名字直接拼到本地目录，安全边界就断了。

先分清：Path 是归档里的路径，不是本地 Path

zipfile.Path 包装的是一个 ZipFile 和归档内的位置。斜杠运算符、iterdir()、is_dir()、is_file() 让它看起来像 pathlib.Path，但它没有把内容释放到磁盘。这个差异很适合做预览、筛选和单文件读取。

from zipfile import ZipFile, Path as ZipPath

with ZipFile("incoming/report.zip") as archive:
    root = ZipPath(archive)
    for item in root.iterdir():
        kind = "目录" if item.is_dir() else "文件" if item.is_file() else "其他"
        print(kind, item.at)

这里的 item.at 是归档内部位置，例如 docs/readme.txt。它不是已经经过本地文件系统规范化的安全路径。输出目录清单时可以展示它，但不要把它无条件交给 open() 或字符串拼接。

只读一个文件时，用 open 把边界留在 ZIP 内

确认目标是文件后，可以直接打开归档成员。这样不会先把整个 ZIP 解压出来，也不会因为一个无关成员名就创建本地文件。

from zipfile import ZipFile, Path as ZipPath

def read_text_member(zip_name: str, member: str) -> str:
    with ZipFile(zip_name) as archive:
        candidate = ZipPath(archive) / member
        if not candidate.is_file():
            raise FileNotFoundError(f"ZIP 文件不存在或不是普通文件: {member}")
        with candidate.open("r", encoding="utf-8", errors="strict") as stream:
            return stream.read()

print(read_text_member("incoming/report.zip", "docs/readme.txt"))

成功状态很明确：is_file() 返回真，并且读取过程只发生在 ZipFile 的上下文中。生产代码还应限制文件大小、编码和可接受的后缀，避免把“能读”误当成“值得信任”。

写到本地前，先拒绝绝对路径和 .. 路径

官方文档特别提醒，zipfile.Path 不会清理归档内文件名。比如成员名里出现 ../、以斜杠开头，或在 Windows 下带盘符，都不应直接参与落盘。下面的函数只允许把文件写在指定目标目录下。

from pathlib import Path
from zipfile import ZipFile
import os

def safe_target(root: Path, member_name: str) -> Path:
    # 统一分隔符后检查归档成员的逻辑路径
    logical = member_name.replace("\\", "/")
    parts = [part for part in logical.split("/") if part not in ("", ".")]
    if not parts or any(part == ".." for part in parts):
        raise ValueError(f"拒绝不安全的 ZIP 成员名: {member_name!r}")
    if logical.startswith("/") or (len(logical) >= 2 and logical[1] == ":"):
        raise ValueError(f"拒绝绝对 ZIP 成员名: {member_name!r}")

    base = root.resolve()
    target = (base / Path(*parts)).resolve()
    if os.path.commonpath((str(base), str(target))) != str(base):
        raise ValueError(f"拒绝越界目标: {member_name!r}")
    return target

def extract_one(zip_name: str, member_name: str, output: Path) -> Path:
    with ZipFile(zip_name) as archive:
        info = archive.getinfo(member_name)
        target = safe_target(output, info.filename)
        if info.is_dir():
            target.mkdir(parents=True, exist_ok=True)
            return target
        target.parent.mkdir(parents=True, exist_ok=True)
        with archive.open(info, "r") as source, target.open("wb") as dest:
            while chunk := source.read(1024 * 1024):
                dest.write(chunk)
        return target

安全校验的成功状态不是“文件已经写出来”，而是目标路径的公共前缀仍等于 output.resolve()，并且只有通过校验的成员才会创建目录或文件。对不可信归档，建议再增加成员数量、单文件大小和总解压大小限制。

Path、extractall 和逐个落盘怎么选

只浏览目录或读取少量内容时，zipfile.Path 更轻量；需要把归档完整展开时，可以使用 ZipFile.extractall()，但仍应先检查来源、成员数量和解压规模。extract() 与 extractall() 会对路径做一定的规范化，而 zipfile.Path 把清理责任留给调用者，不能混为一谈。

如果业务必须保留归档内原始层级，逐个成员调用上面的 safe_target() 更容易记录拒绝原因，也便于在失败时停止或回滚。若只是读取配置文件，不要为了方便把整个压缩包解到临时目录。

几个容易漏掉的检查

• 符号链接：is_symlink() 在较新的 Python 版本中可用于识别归档成员，不能把它当普通文件直接落盘。
• 目录标记：有些 ZIP 不显式存目录项，遍历时不能只依赖目录名是否以斜杠结尾，读取前仍要检查 is_file()。
• 版本兼容：Path.open() 的文本参数在旧版本上有过变化；要兼容 Python 3.10/3.11 时，编码等参数使用关键字传递。
• 异常收口：处理结束后立即退出 ZipFile 上下文，遇到 BadZipFile、KeyError 或写入失败时保留清晰的成员名。

常见问题

zipfile.Path 会自动防止路径遍历吗？

不会。它不会清理归档内的文件名；涉及本地写入时，调用者必须检查绝对路径、.. 组件和最终目标目录边界。

只读 ZIP 内文件也需要做路径校验吗？

仍建议限制成员名、大小和类型。只在 ZIP 内通过 Path.open() 读取，风险小于直接落盘，但不代表归档内容可信。

什么时候可以直接用 extractall？

仅在归档来源可信、目标目录是隔离的临时目录，并且你已经检查了成员数量与解压规模时考虑使用；不可信上传更适合逐个校验、逐个写入。

把判断顺序固定下来

实用顺序可以固定为：先用 ZipFile 打开并识别坏包，再用 zipfile.Path 浏览或读取，最后在任何本地写入前校验成员名和公共路径。这样既保留了标准库 API 的便利，也不会把归档内部的名字误当成本地安全路径。