Python zipfile 解包的路径安全处理

我处理 ZIP 上传包时，最容易被低估的不是“能不能解压”，而是“解压出来的每一个路径和字节，是否都仍在我允许的范围内”。Python 的 zipfile 已经会对 ZipFile.extract() 和 extractall() 做一部分成员名规范化，但这不等于可以无条件信任压缩包，更不能把 zipfile.Path 当成安全解包器。

这篇只解决三个问题：成员名不能跳出目标目录，输出目录要由程序明确控制，以及解压数量和大小要有预算。示例使用 Python 标准库，代码是可改造的骨架；其中的目录和数值只是示例配置，不代表已经在某台机器上执行过。

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

先把 extractall、extract 和 zipfile.Path 分开看

官方文档提醒，来自不可信来源的归档文件在解包前需要检查。extract() 和 extractall() 会尝试移除绝对路径前缀和成员名中的 .. 组件，但它们仍然可能覆盖目标目录中已有文件，也不能替你决定压缩包最多允许多少成员、多少解压字节。

更容易被忽略的是 zipfile.Path。它适合把压缩包内容当作可遍历的资源，但官方文档明确说明，它不会替调用方清理文件名；如果随后把成员名拼接到本地目录，路径校验仍由应用负责。

因此，实际项目里我会把“读取归档”和“决定本地写到哪里”拆成两个动作：先读取 ZipInfo 元数据，再由应用生成唯一目标目录，并对每个成员计算最终路径。

成员路径检查的关键是比较规范化后的绝对路径

不要只用字符串判断 name.startswith("../")。成员名可能混用斜杠、包含多层父目录，或者在规范化后才显露出越界结果。一个更稳妥的思路是：拒绝明显的绝对路径；把 ZIP 内部的正斜杠转换为当前平台的路径分隔符；用 Path.resolve() 得到目标文件的绝对路径；最后用 os.path.commonpath() 确认它仍然位于目标根目录下。

from pathlib import Path
import os

def safe_member_path(root: Path, member_name: str) -> Path:
    # ZIP 规范通常使用正斜杠，先映射到当前系统的路径语义。
    name = member_name.replace("/", os.sep)
    candidate = Path(root, name)
    root_abs = root.resolve()
    candidate_abs = candidate.resolve()

    # commonpath 比 startswith 更适合判断目录边界，避免 /out2 被误认成 /out。
    try:
        inside = os.path.commonpath((str(root_abs), str(candidate_abs))) == str(root_abs)
    except ValueError:
        # Windows 不同盘符等情况无法求共同路径，直接拒绝该成员。
        inside = False
    if not inside:
        raise ValueError(f"成员路径越出目标目录: {member_name!r}")
    return candidate_abs

这个函数只负责路径边界，不负责创建文件。目录成员可以在后面的写出逻辑中单独处理；如果成员名为空、以斜杠结尾，或目标路径已经存在为目录，也应该按业务需要做明确决策，而不是静默覆盖。

不要只检查路径，还要限制解压预算

路径安全解决的是“写到哪里”，并没有解决“写多少”。ZipInfo.file_size 是成员的未压缩大小，compress_size 是压缩数据大小。面对不可信归档时，至少要同时设置成员数量上限、单个成员的未压缩大小上限和整个压缩包的累计未压缩大小上限。只检查压缩包文件本身的大小是不够的，因为高压缩比内容可能在解压后膨胀很多。

我更倾向于先用 infolist() 做元数据筛选，再用 open() 分块读取。这样可以在开始写出前拒绝明显超限的归档，并且不会为了读取一个成员把全部内容一次性载入内存。

from pathlib import Path
from zipfile import ZipFile

def extract_zip_safely(archive: Path, output_root: Path,
                       max_members: int = 1000,
                       max_member_bytes: int = 50 * 1024 * 1024,
                       max_total_bytes: int = 200 * 1024 * 1024) -> int:
    # 使用独立目录承接本次任务，调用方可在成功后再把它移动到业务位置。
    output_root = output_root.resolve()
    output_root.mkdir(parents=True, exist_ok=True)
    used_bytes = 0
    written = 0
    seen = set()

    with ZipFile(archive) as zf:
        members = zf.infolist()
        # 成员数量先于创建文件检查，避免超大目录列表拖垮后续逻辑。
        if len(members) > max_members:
            raise ValueError("ZIP 成员数量超过限制")

        for info in members:
            if info.filename in seen:
                raise ValueError(f"重复成员名不接受覆盖: {info.filename!r}")
            seen.add(info.filename)
            if info.file_size > max_member_bytes:
                raise ValueError(f"单个成员超过限制: {info.filename!r}")
            if used_bytes + info.file_size > max_total_bytes:
                raise ValueError("ZIP 总解压大小超过限制")

            destination = safe_member_path(output_root, info.filename)
            if info.is_dir():
                # 目录只负责建立层级，不增加解压字节预算。
                destination.mkdir(parents=True, exist_ok=True)
                continue

            destination.parent.mkdir(parents=True, exist_ok=True)
            with zf.open(info) as source, destination.open("xb") as target:
                # 分块写出可以控制内存；每次写入后累计真实预算。
                copied = 0
                while True:
                    chunk = source.read(1024 * 1024)
                    if not chunk:
                        break
                    copied += len(chunk)
                    if copied > max_member_bytes or used_bytes + copied > max_total_bytes:
                        raise ValueError("读取过程中发现解压大小超限")
                    target.write(chunk)
            used_bytes += copied
            written += 1
    return written

这里的第二次大小判断并不是多余的防御：归档元数据不应被当作唯一依据，流式读取时仍要让实际写入量受预算约束。示例用 xb 创建新文件，遇到重复目标名会失败；如果业务允许覆盖，应该先设计清晰的覆盖策略，而不是默认继承压缩包中的顺序。

输出目录要隔离，异常时不要留下半成品

即使每个成员都在目标根目录内，直接解压到共享目录仍有两个问题：同名文件可能相互覆盖，失败任务可能留下部分文件供后续请求误用。我的做法是给一次解包任务分配一个临时子目录，完整成功后再交给业务层登记；异常时删除这个临时目录，或者把它标记为不可用。

删除半成品属于业务清理动作，需要结合权限、并发和审计策略实现。至少要保证 ZipFile、成员流和输出文件句柄都通过上下文管理器关闭；不要在循环外复用已经关闭的成员流，也不要在还没完成预算检查时把临时目录暴露给下游。

什么时候可以直接使用 extractall

如果压缩包来自可信的内部构建流程，输入边界已经由上游控制，且业务只需要解压到一个新建的隔离目录，extractall() 可以减少样板代码。但即便如此，我仍会保留成员数量和总大小的预检查，并把输出目录设为任务专属目录。

只要 ZIP 来自用户上传、外部接口、邮件附件或跨团队传递，就不建议把“标准库会清理路径”理解成完整安全策略。路径规范化、目标目录比较、大小预算、重复名策略和异常清理，应该一起出现在解包边界上。

最后用一张表复查边界

相关问题

只用 Path.resolve 就能保证安全吗？

不能。它只把路径转换成规范形式，仍然需要把规范化后的结果与明确的目标根目录比较；同时还要考虑大小、重复名和任务目录生命周期。

为什么要在流式读取时再检查一次大小？

因为最终约束是实际写出的字节数。元数据预检适合快速拒绝明显超限的成员，流式计数则把读取过程也锁在预算内。

zipfile.Path 适合直接写到磁盘吗？

它适合遍历和读取压缩包内部资源，但不会替你清理成员名。只要要落盘，就应重新建立目标路径并执行目录边界检查。

把 ZIP 解包当成一个有输入、有边界、有提交点的资源处理过程，通常比把它当成一行工具调用更可靠。对外部输入而言，路径安全和大小预算是同一层的设计问题。