Python shutil 模块目录文件处理实战

一、模块核心定位

shutil（Shell Utilities）是 Python 标准库中专门处理高级文件操作的模块，提供比 os 模块更便捷的目录/文件管理功能，主要解决以下场景：

• 跨平台的目录树复制与删除
• 保留元数据的文件操作
• 自动化压缩/解压处理
• 大文件高效传输

---

二、目录操作函数集

1. copytree(src, dst, symlinks=False, ignore=None)

• ​功能：递归复制完整目录树结构

• ​参数说明：

  参数	类型	说明
  src	字符串	源目录路径（必须存在且可读）
  dst	字符串	目标目录路径（必须不存在且父目录可写）
  symlinks	布尔值	符号链接处理模式：True复制链接本身，False复制链接指向内容（默认）
  ignore	回调函数	过滤规则函数，接收参数 (dir, contents) 返回需忽略的文件名列表

• ​典型场景：

  # 备份项目代码时忽略.git文件和缓存
  shutil.copytree('/projects/core', '/backup/core',
                  ignore=shutil.ignore_patterns('.git', '__pycache__'))
  

2. rmtree(path, ignore_errors=False, οnerrοr=None)

​

• 功能：递归删除目录树及所有子内容

• 参数说明：

  参数	类型	说明
  path	字符串	待删除目录路径（需存在）
  ignore_errors	布尔值	True时忽略删除错误（默认False抛出异常）
  onerror	函数	错误处理函数，接收参数 (func, path, exc_info) 处理具体错误

• 典型场景：

  # 安全删除临时工作区
  def log_remove_error(func, path, exc_info):
      print(f"删除失败：路径 {path}，错误 {exc_info[1]}")
  
  shutil.rmtree('/tmp/work_area', onerror=log_remove_error)
  

三、文件操作函数集

1. copy2(src, dst, follow_symlinks=True)

• 功能：复制文件内容及完整元数据（包括时间戳、权限等）

• 参数说明：

  参数	类型	说明
  src	字符串	源文件路径（必须存在且可读）
  dst	字符串	目标路径（文件路径或可写目录路径）
  follow_symlinks	布尔值	True时复制符号链接指向内容，False复制链接本身（默认True）

• ​典型场景：

  # 保留原始信息的配置文件备份
  shutil.copy2('/etc/nginx.conf', '/backup/nginx/nginx.conf.bak')
  

2. move(src, dst, copy_function=copy2)

• ​功能：原子性移动文件/目录（同设备立即移动，跨设备复制后删除）

• 参数说明：

  参数	类型	说明
  src	字符串	源路径（文件或目录需存在）
  dst	字符串	目标路径（目录需存在，文件路径需可写）
  copy_function	函数	跨设备移动时使用的复制函数（默认保留元数据的copy2）

• 典型场景：

  # 归档过期日志文件
  shutil.move('/var/log/app.log', '/archive/2023/logs/app.log')
  

四、压缩归档函数集

1. make_archive(base_name, format, root_dir=None, base_dir=None)

• ​功能：创建包含目录结构的压缩归档文件

• ​参数说明：

参数	类型	说明
base_name	字符串	输出文件基础名（不含扩展名）
format	字符串	压缩格式：zip（跨平台）、tar（Unix）、gztar（gzip）、bztar（bzip2）
root_dir	字符串	要压缩的根目录（默认当前目录）
base_dir	字符串	压缩包内相对根目录的路径（默认压缩整个目录）

• ​典型场景：

# 创建带时间戳的压缩备份
timestamp = datetime.now().strftime("%Y%m%d_%H%M")
shutil.make_archive(f'backup_{timestamp}', 'zip', '/data/reports')

2. unpack_archive(filename, extract_dir=None, format=None)

​

• 功能：解压多种格式的压缩文件

• 参数说明：

  参数	类型	说明
  filename	字符串	压缩文件路径（需存在且可读）
  extract_dir	字符串	解压目标目录（默认当前目录）
  format	字符串	显式指定格式（默认根据扩展名自动检测）

• ​典型场景：

  # 解压用户上传的部署包
  shutil.unpack_archive('/uploads/deploy.tar.gz', '/opt/app')
  

五、高级工具函数

1. disk_usage(path)

• ​功能：获取磁盘空间使用统计

• 参数说明：

  参数	类型	说明
  path	字符串	需要检查的挂载点路径

• 返回值：命名元组(total, used, free) 单位：字节

• 典型场景：

usage = shutil.disk_usage('/')
print(f"可用空间：{usage.free / 1024**3:.2f}GB")

六、特殊场景处理方案

1. ignore_patterns(*patterns)

• 功能：生成过滤规则函数（配合copytree使用）

• ​参数说明：

参数	类型	说明
patterns	可变参数	通配符模式（如’*.tmp’）

• 典型场景：

# 忽略所有临时文件和隐藏文件
ignore = shutil.ignore_patterns('*.tmp', '.*')
shutil.copytree('src', 'dst', ignore=ignore)

操作安全提示：

1. 执行删除前使用os.path.exists()验证路径
2. 跨设备移动时确认目标设备空间充足
3. 压缩大文件时优先选用bztar格式节省空间
4. 处理符号链接时明确设置symlinks参数避免意外覆盖