將指定目錄下的所有文件(包含子目錄)遞歸打包為單個 ZIP 歸檔,保留相對目錄結構,適用於備份、分發、部署打包等場景。
import os
import zipfile
def zip_directory(source_dir, output_zip, compression=zipfile.ZIP_DEFLATED):
"""
遞歸壓縮目錄
:param source_dir: 要壓縮的源目錄絕對路徑
:param output_zip: 輸出 ZIP 文件路徑
:param compression: 壓縮算法,ZIP_DEFLATED 需 zlib 支持
"""
# 確保源目錄存在且為目錄
if not os.path.isdir(source_dir):
raise ValueError(f"源路徑不是目錄: {source_dir}")
# 統一路徑分隔符,移除末尾分隔符
source_dir = os.path.normpath(source_dir)
base_len = len(source_dir) + 1 # +1 for separator
with zipfile.ZipFile(output_zip, 'w', compression) as zf:
for root, dirs, files in os.walk(source_dir):
for file in files:
file_path = os.path.join(root, file)
# 存儲在 ZIP 內的相對路徑 (保留目錄結構)
arcname = file_path[base_len:]
zf.write(file_path, arcname)
print(f"壓縮完成: {output_zip} ({os.path.getsize(output_zip)} bytes)")
# 使用示例
if __name__ == "__main__":
zip_directory(r"/home/johnf", r"/home/johnf/my-archive.zip")
(root, dirs, files) 三元組,順序為深度優先。file_path[base_len:] 切片獲取相對路徑,確保 ZIP 內結構不包含源目錄父路徑。with zipfile.ZipFile(...) as zf: 保證異常時也能正確關閉文件、刷新緩衝區。ZIP_STORED (0):僅存儲,無壓縮,速度最快。ZIP_DEFLATED (8):標準 Deflate 壓縮,需 zlib 模塊 (標準庫內置)。ZIP_BZIP2 (12):Bzip2 壓縮率更高但慢 (Python 3.3+)。ZIP_LZMA (14):LZMA 壓縮率最高但最慢 (Python 3.3+)。allowZip64=True,支持 >4GB 文件/歸檔。def zip_directory_ex(source_dir, output_zip, exclude_patterns=None, **kwargs):
import fnmatch
if exclude_patterns is None:
exclude_patterns = ['*.pyc', '__pycache__', '.git', '.svn', '*.log', '*.tmp']
def should_exclude(path):
rel = os.path.relpath(path, source_dir)
for pattern in exclude_patterns:
if fnmatch.fnmatch(rel, pattern) or fnmatch.fnmatch(os.path.basename(rel), pattern):
return True
return False
with zipfile.ZipFile(output_zip, 'w', **kwargs) as zf:
for root, dirs, files in os.walk(source_dir):
# 就地修改 dirs 列表以跳過排除目錄 (os.walk 會遞歸修改後的 dirs)
dirs[:] = [d for d in dirs if not should_exclude(os.path.join(root, d))]
for file in files:
file_path = os.path.join(root, file)
if should_exclude(file_path):
continue
arcname = os.path.relpath(file_path, source_dir)
zf.write(file_path, arcname)
def zip_with_progress(source_dir, output_zip, **kwargs):
# 先統計總文件數
total_files = sum(len(files) for _, _, files in os.walk(source_dir))
processed = 0
with zipfile.ZipFile(output_zip, 'w', **kwargs) as zf:
for root, _, files in os.walk(source_dir):
for file in files:
file_path = os.path.join(root, file)
arcname = os.path.relpath(file_path, source_dir)
zf.write(file_path, arcname)
processed += 1
if processed % 100 == 0:
print(f"\r已處理 {processed}/{total_files} 文件 ({processed/total_files*100:.1f}%)", end="")
print()
import stat, time
with zipfile.ZipFile(...) as zf:
for ...:
zi = zipfile.ZipInfo(arcname)
st = os.stat(file_path)
zi.date_time = time.localtime(st.st_mtime)[:6]
zi.external_attr = (stat.S_IMODE(st.st_mode) | stat.S_IFREG) << 16 # Unix 權限存高16位
zi.compress_type = compression
with open(file_path, 'rb') as f:
zf.writestr(zi, f.read())
| 坑點 | 現象 | 解決 |
|---|---|---|
| 空目錄不被打包 | ZIP 標準不存儲空目錄 | 手動添加目錄項: zf.writestr(zipfile.ZipInfo(dirname + '/'), b'') |
| 符號鏈接被跟隨/忽略 | 默認跟隨鏈接打包目標文件 | 用 os.lstat 判斷 stat.S_ISLNK,決定是否存鏈接 |
| 中文路徑編碼亂碼 | Python 3.11+ 自動 UTF-8;舊版本需設置 ZipInfo.flag_bits |= 0x800 | 升級 Python 或手動設置標誌位 |
| 權限錯誤導致中斷 | 無讀取權限文件拋出 PermissionError | try/except 捕獲並記錄跳過 |
簡單場景優先考慮系統命令,性能更高、參數更豐富:
# Linux/macOS
zip -r output.zip /source/dir -x "*.pyc" -x "__pycache__/*"
# Windows (PowerShell)
Compress-Archive -Path "C:\source\dir\*" -DestinationPath "C:\output.zip" -CompressionLevel Optimal
zipfile + os.walk 是 Python 標準庫實現目錄壓縮的標準模式。掌握相對路徑計算、上下文管理、壓縮算法選擇、異常處理與進度反饋,即可構建健壯的打包工具。生產環境大規模打包建議調用系統 zip/tar 或使用專用備份工具 (restic, borg, duplicati)。