tarfile.open() 正确 gzip 压缩模式为 'w:gz'，非 'w' 或 'w:z'；add() 需显式设 recursive=True 才递归添加子目录，arcname 可控解压路径，filter 可过滤文件，打包前应校验路径可读性。
tarfile.open() 的 mode 参数必须是 'w:gz' 才能生成 tar.gz
很多人用 tarfile.open() 时误写成 'w' 或 'w:z'，结果得到的是未压缩的 .tar，或者直接报错 OSError: invalid compression type 'z'。真正支持 gzip 压缩的 mode 是 'w:gz' —— 冒号后跟 gz，不是 gzip，也不是 z。
常见错误场景：想打包当前目录下所有 .py 文件，但压缩包里空空如也，其实是因为没调用 add()；或者用了 'w' 模式却指望自动压缩，结果解压时发现根本不需要 gzip 解压。
-
tarfile.open('archive.tar.gz', 'w:gz')✅ 正确写法 -
tarfile.open('archive.tar.gz', 'w')❌ 生成无压缩 tar 包 -
tarfile.open('archive.tar.gz', 'w:z')❌ 报错：invalid compression type -
tarfile.open('archive.tar.gz', 'w:bz2')⚠️ 可用，但那是 bzip2，不是 gzip
add() 方法默认不递归，子目录要显式设置 recursive=True
如果你执行 t.add('/path/to/folder') 却只看到空目录进包，大概率是没传 recursive=True。tarfile 默认只添加顶层路径本身（即目录元信息），不会自动遍历子文件和子目录。
另外注意：add() 的 arcname 参数控制归档内路径名。如果不设，会保留源路径的绝对结构（比如 /home/user/project/），解压时可能覆盖系统路径。建议统一用相对路径或重命名。
立即学习“Python免费学习笔记（深入）”；
- 加整个文件夹（含子目录）：
t.add('/tmp/myproj', recursive=True) - 避免绝对路径污染：
t.add('/tmp/myproj', arcname='myproj', recursive=True) - 跳过某些文件（如
.git）：t.add('/tmp/myproj', filter=lambda x: None if '.git' in x.name else x, recursive=True)
打包前最好先检查目标路径是否存在且可读
脚本运行在不同环境（CI、定时任务、他人机器）时，源目录可能不存在、权限不足，或路径含中文/空格导致 OSError: No such file or directory。tarfile 不会主动提示“找不到源”，而是在 add() 时报错，堆栈还容易掩盖真实原因。
更稳妥的做法是提前验证：用 os.path.isdir() 和 os.access(..., os.R_OK) 判断；对每个待加文件，用 os.path.isfile() 过滤掉 broken symlink 或 dangling path。
- 检查并跳过不可读项：
if os.path.isdir(src) and os.access(src, os.R_OK): t.add(src, ...) - 避免因路径含空格失败：
tarfile本身支持，但 shell 调用时要注意，Python 内部无需额外转义 - 时间戳问题：默认保留原文件 mtime，若需统一归档时间，可用
filter函数修改tarinfo.mtime
大文件打包时别让 tarfile 吃光内存
tarfile 默认把整个归档缓存在内存里，直到 close() 才写入磁盘。如果打包几百 MB 以上的文件夹，可能触发 MemoryError，尤其在低配容器或 CI 环境中。
解决办法是确保使用流式写入模式（'w:gz' 本身已支持），并避免一次性 add() 太多大文件。更关键的是：不要用 io.BytesIO 构造内存 buffer 再写入 tarfile —— 那才是真吃内存。
- 正确流式操作：
with tarfile.open('out.tar.gz', 'w:gz') as t:→ 自动分块写入磁盘 - 错误示范：
buf = io.BytesIO(); t = tarfile.open(fileobj=buf, mode='w:gz')→ 全部存内存 - 超大单文件（如日志）建议先用
subprocess.run(['tar', 'czf', ...])委托系统 tar，更省内存
实际自动化脚本里最容易被忽略的是 arcname 和 filter 的组合使用——它决定了解压后目录结构是否干净、是否包含临时文件。别只盯着能不能打上包，得看解出来是不是你想要的样子。
