Python如何递归拷贝目录下所有文件？

Question

在使用Python递归拷贝目录时，一个常见问题是：如何确保源目录中的所有文件和子目录被完整复制到目标路径，同时保留原有的目录结构？开发者常误用`os.listdir()`配合手动递归遍历，导致代码冗长且易出错。此外，遇到符号链接、权限不足或同名文件夹存在时，程序可能抛出异常。理想的解决方案应能自动处理嵌套层级，并跳过无法访问的文件，同时避免覆盖已有文件。如何利用Python标准库高效、安全地实现这一功能？

Answer 1

1. 问题背景与常见误区

在Python中实现目录的递归拷贝是系统管理、备份工具和自动化脚本中的基础需求。许多开发者倾向于使用os.listdir()配合手动递归遍历来遍历文件树，例如：

import os

def copy_directory(src, dst):
    if not os.path.exists(dst):
        os.makedirs(dst)
    for item in os.listdir(src):
        src_path = os.path.join(src, item)
        dst_path = os.path.join(dst, item)
        if os.path.isdir(src_path):
            copy_directory(src_path, dst_path)
        else:
            shutil.copy2(src_path, dst_path)

这种实现方式虽然直观，但存在多个问题：

• 未处理符号链接（symlink），可能导致无限递归或数据丢失
• 遇到权限不足的文件时会抛出PermissionError
• 若目标路径已存在同名目录，os.makedirs()将引发异常
• 缺乏错误容忍机制，无法跳过不可访问的文件
• 代码冗长且需自行维护递归逻辑

2. 标准库的演进：从shutil.copytree到高级参数支持

自Python 2以来，shutil模块提供了copytree()函数用于递归复制目录树。其基本用法如下：

import shutil

shutil.copytree(src='/path/to/source', dst='/path/to/destination')

该函数自动处理嵌套层级，并保留目录结构。然而，默认行为在以下情况会失败：

场景	默认行为	是否抛出异常
目标目录已存在	拒绝复制	是
遇到符号链接	复制链接本身（非目标）	否
权限不足	中断执行	是
文件只读	尝试复制	可能失败

3. 安全健壮的解决方案设计

为应对上述挑战，应结合shutil.copytree()的高级参数与异常处理机制。Python 3.8+引入了dirs_exist_ok参数，极大提升了实用性。

import shutil
import os

def safe_copy_directory(src, dst, ignore_errors=True):
    def ignore_permissions_error(func, path, excinfo):
        if isinstance(excinfo[1], (PermissionError, FileNotFoundError)):
            print(f"跳过无法访问的路径: {path}")
            return
        raise

    try:
        shutil.copytree(
            src=src,
            dst=dst,
            symlinks=False,                # 复制链接指向的内容
            ignore_dangling_symlinks=True, # 忽略悬空链接
            dirs_exist_ok=True,            # 允许目标目录存在
            onerror=ignore_permissions_error if ignore_errors else None
        )
    except Exception as e:
        print(f"复制失败: {e}")

此方案具备以下特性：

1. 利用dirs_exist_ok=True避免因目标存在而报错
2. 通过onerror回调处理权限异常
3. 设置symlinks=False确保符号链接内容被复制而非链接本身
4. 支持Python 3.8+，符合现代开发标准

4. 深层优化：自定义忽略策略与进度反馈

对于大型目录，可进一步集成shutil.ignore_patterns()实现智能过滤：

ignored = shutil.ignore_patterns('*.tmp', '*.log', '__pycache__')

shutil.copytree(src, dst, ignore=ignored, dirs_exist_ok=True)

此外，可通过封装实现进度追踪：

graph TD
    A[开始复制] --> B{源目录是否存在}
    B -- 否 --> C[抛出错误]
    B -- 是 --> D[检查目标目录]
    D --> E[调用copytree]
    E --> F[处理符号链接]
    F --> G[逐文件复制]
    G --> H{发生异常?}
    H -- 是 --> I[调用onerror回调]
    H -- 否 --> J[继续]
    J --> K[完成复制]

5. 实际应用场景与企业级考量

在生产环境中，目录拷贝常用于：

• 部署自动化：将构建产物复制到服务器
• 数据迁移：跨存储设备转移用户资料
• 版本快照：创建配置目录的历史副本
• 容器镜像构建：准备上下文目录

建议在企业级应用中增加如下增强：

增强项	技术实现	价值
日志记录	集成logging模块	便于审计与故障排查
校验和验证	复制后比对hash值	确保完整性
资源限制	监控内存与IO	防止系统阻塞
并发复制	异步+线程池	提升大目录性能