Python zipfile 批量打包实战：保留目录结构、过滤临时文件和写入校验

项目上线、资料归档、离线交付时，经常要把一个目录批量打成 zip 包。手动压缩看起来快，但一旦目录里混进缓存、日志、临时文件，或者压缩包里路径层级错了，后面解包就会很麻烦。本文用 Python 标准库 zipfile 写一个可复用的打包脚本。

摘要

这篇文章会完成一个实用脚本：从源目录递归收集文件，按规则跳过缓存和日志，写入 zip 时保留相对路径，最后读取压缩包做数量、路径和 CRC 校验。整个过程只依赖 Python 标准库，适合放进构建脚本或日常自动化任务。

适合人群

适合需要用 Python 做文件自动化、项目交付打包、静态资源归档、批量资料压缩的同学。你只需要熟悉基础函数、循环和 pathlib 的简单用法。

目录

• 打包流程先理清
• 最小可用脚本
• 过滤缓存、日志和临时文件
• 写入后做校验
• 常见坑和优化建议

打包流程先理清

一个可靠的批量打包流程通常不是“遍历到文件就写入”这么简单。更稳的顺序是：先确定源目录，再判断文件是否应该进入压缩包，写入时使用相对路径，最后打开压缩包检查结果。

这里最容易忽略的是“相对路径”。如果直接把绝对路径写入压缩包，别人解压后可能看到很长的本机目录层级；正确做法是以源目录为根，只把根目录下面的相对路径写进去。

最小可用脚本

先写一个能跑通的版本。它会遍历 source_dir 下所有文件，并把它们写入 target_zip。

from pathlib import Path
from zipfile import ZipFile, ZIP_DEFLATED


def package_dir(source_dir: str, target_zip: str) -> int:
    source = Path(source_dir).resolve()
    target = Path(target_zip).resolve()
    total = 0

    with ZipFile(target, "w", ZIP_DEFLATED, compresslevel=6) as zf:
        for path in sorted(source.rglob("*")):
            if not path.is_file():
                continue

            arcname = path.relative_to(source).as_posix()
            zf.write(path, arcname)
            total += 1

    return total


if __name__ == "__main__":
    count = package_dir("web_dist", "release-web.zip")
    print(f"packed files: {count}")

这段代码有三个关键点：

• source.rglob("*") 用来递归遍历目录。
• path.relative_to(source).as_posix() 保留相对路径，并统一成 zip 常见的斜杠路径。
• ZIP_DEFLATED 开启常用压缩方式，适合文本、配置、静态资源等文件。

过滤缓存、日志和临时文件

真实项目里，目录里可能有 __pycache__、.git、日志文件、临时文件。它们通常不应该进入交付包。我们可以把过滤规则单独拆出来，让后续维护更清楚。

SKIP_DIR_NAMES = {"__pycache__", ".git", ".idea"}
SKIP_FILE_NAMES = {".DS_Store"}
SKIP_SUFFIXES = {".pyc", ".pyo", ".log", ".tmp"}


def should_keep(path: Path, source: Path, target: Path) -> bool:
    if not path.is_file():
        return False

    if path.resolve() == target:
        return False

    relative_parts = path.relative_to(source).parts
    if any(part in SKIP_DIR_NAMES for part in relative_parts):
        return False

    if path.name in SKIP_FILE_NAMES:
        return False

    if path.suffix.lower() in SKIP_SUFFIXES:
        return False

    return True

然后把 package_dir 改成使用这个判断函数：

def package_dir(source_dir: str, target_zip: str) -> int:
    source = Path(source_dir).resolve()
    target = Path(target_zip).resolve()
    target.parent.mkdir(parents=True, exist_ok=True)
    total = 0

    with ZipFile(target, "w", ZIP_DEFLATED, compresslevel=6) as zf:
        for path in sorted(source.rglob("*")):
            if not should_keep(path, source, target):
                continue

            arcname = path.relative_to(source).as_posix()
            zf.write(path, arcname)
            total += 1

    return total

注意 path.resolve() == target 这一行：如果你把压缩包输出到源目录里面，不加这条判断，脚本可能把刚生成的 zip 也写进 zip 包，造成结果越来越乱。

写入后做校验

打包结束后，不要只看文件存在就结束。至少应该重新打开压缩包，检查文件数量、部分路径，以及 testzip() 的 CRC 检查结果。

def inspect_zip(target_zip: str) -> dict:
    target = Path(target_zip)

    with ZipFile(target, "r") as zf:
        bad_file = zf.testzip()
        names = zf.namelist()

    return {
        "file_count": len(names),
        "bad_file": bad_file,
        "first_names": names[:5],
        "size_bytes": target.stat().st_size,
    }


if __name__ == "__main__":
    zip_path = "release-web.zip"
    count = package_dir("web_dist", zip_path)
    info = inspect_zip(zip_path)

    print(f"packed files: {count}")
    print(f"zip files: {info['file_count']}")
    print(f"bad file: {info['bad_file']}")
    print(f"size bytes: {info['size_bytes']}")
    print("first names:", info["first_names"])

如果 bad_file 不是 None，说明压缩包里有文件校验失败，需要重新生成或检查磁盘读写问题。如果 file_count 和脚本写入数量不一致，也要检查过滤规则或写入路径。

常见坑和优化建议

• 路径写成绝对路径：解压后会出现本机目录结构，应该使用 relative_to(source)。
• 输出包放在源目录里：一定要跳过目标 zip 自身，避免把压缩包写入压缩包。
• 过滤规则散落在循环里：建议集中到 should_keep()，后续新增规则更容易。
• 没有写后校验：至少检查 testzip()、数量和关键路径，别等交付后才发现包不完整。
• 超大目录一次性处理：可以先打印预计写入数量，或者按目录拆包，方便定位异常文件。

总结

用 Python zipfile 做批量打包，核心不是压缩这一行代码，而是把流程做完整：明确源目录，保留相对路径，过滤不该进包的文件，写完再校验。这样脚本既能用于临时打包，也能稳定放到日常构建和交付流程里。