Python用shutil.make_archive快速备份目录

本文深入剖析了Python中shutil.make_archive进行目录备份时极易踩坑的三大核心问题：一是root_dir与base_dir路径关系错误导致静默生成空压缩包，必须严格遵循“base_dir为相对子目录名、root_dir为其父目录”的约定；二是跨平台压缩格式选择陷阱，推荐优先使用format="zip"以确保兼容性，避免tar系格式在Windows上因缺少gzip等系统命令而失败；三是中文路径和文件名在ZIP中乱码的顽疾，需借助7-Zip重压或明确提示用户使用支持UTF-8的解压工具。文章还指出，如需排除特定子目录（如.git、__pycache__），必须通过shutil.copytree预处理而非依赖不存在的exclude参数——看似简单的函数调用背后，藏着大量隐性依赖与平台差异，一次跑通远不等于稳定可靠。

shutil.make_archive 打包目录时路径写错就静默失败

它不会报错，但生成的 zip 是空的或根本没文件——因为 root_dir 默认是当前工作目录，而 base_dir 是相对于它的子路径。你传了个绝对路径当 base_dir，它会去 root_dir 下找那个“子目录”，自然找不到。

• 正确做法：用 base_dir 指定要打包的目录名（不带路径），再用 root_dir 指定它的父目录
• 比如要打包 /home/user/project，就设 root_dir="/home/user"，base_dir="project"
• 如果 base_dir 是 "./project" 或 "/home/user/project"，大概率打空包
• 调试时加一句 print(os.path.join(root_dir, base_dir)) 确认拼出来的是不是你要的目录

压缩格式选 tar 还是 zip？Windows 和 Linux 行为不一致

shutil.make_archive 的 format 参数看着简单，实际背后调用的是不同模块："zip" 走 zipfile，"tar" 走 tarfile，而 "gztar" 会额外依赖系统 gzip 命令（Linux/macOS 可用，Windows 默认没有）。

• 跨平台备份首选 format="zip"：Python 自带支持，Windows 解压也最省心
• 要压缩率高且目标环境有 tar 工具，用 "gztar"，但得先确认 shutil.which("gzip") 返回非 None
• "bztar" 和 "xztar" 同理，别默认写上，容易在 CI 或 Docker 容器里挂掉

中文路径或特殊字符文件名在 zip 里乱码

这是 zipfile 模块的老问题：Python 3.6+ 默认用 UTF-8 写文件名，但 Windows 资源管理器老版本只认 CP437 或 GBK。结果就是解压后文件名变问号或方块。

• 临时解法：打包完用 7z a -tzip -encoding=utf8 backup.zip project/ 重压（需装 7-Zip）
• 纯 Python 方案目前无官方支持，别硬改 zipfile 源码
• 如果目标用户全是 macOS/Linux，可忽略；若含 Windows 用户，建议在备份脚本里加提示：“请用 Bandizip、7-Zip 或最新版 WinRAR 解压”

想排除某些子目录（如 __pycache__、.git）得自己遍历

shutil.make_archive 没有 exclude 参数，也不能传 ignore_patterns。它只会原样递归打包整个 base_dir 下所有内容。

• 安全做法：先用 shutil.copytree 复制一份干净目录（配合 ignore 函数过滤），再对副本打包
• 示例忽略逻辑：shutil.copytree(src, tmp_dir, ignore=shutil.ignore_patterns("__pycache__", ".git", "*.log"))
• 别图省事用 os.system("rm -rf") 删除，容易误删；也别用 shutil.rmtree 直接删原目录
• 临时目录记得用 tempfile.mkdtemp() 创建，避免路径冲突

真正麻烦的不是怎么调用函数，而是 root_dir 和 base_dir 的相对关系、中文编码的隐性依赖、还有那些看似能绕过实则埋雷的“快捷写法”。跑通一次不等于以后都稳。

今天关于《Python用shutil.make_archive快速备份目录》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！