Pythonshutil.copytree复制文件夹全教程

本文深入解析了Python中`shutil.copytree`全量复制文件夹的核心痛点与实战方案：针对目标目录已存在导致的`FileExistsError`，推荐使用Python 3.8+的`dirs_exist_ok=True`安全跳过（而非危险的手动删除），同时明确其“覆盖同名、保留多余”的行为边界；详解`ignore`参数的正确用法以精准过滤`.git`等无需复制的内容；直面Windows长路径、权限锁等系统级限制，并提供UNC路径、注册表配置等有效解法；最后指出当需求超出`copytree`能力时，如何通过`os.walk`+`shutil.copy2`手动构建高可控、可日志、可恢复的定制化复制流程——帮你从“复制失败就懵”进阶到“按需精确掌控每一字节”。

shutil.copytree 复制失败：目录已存在怎么办

shutil.copytree 默认拒绝覆盖目标路径，只要 dst 目录存在，就会直接抛出 FileExistsError: [Errno 17] File exists。这不是权限或路径错误，是设计如此——它只做“新建+递归复制”，不支持“覆盖”语义。

常见误操作是先手动删目标再调用，但竞态条件风险高（比如删完、另一进程创建了同名空目录，又会报错）。稳妥做法是用 dirs_exist_ok=True 参数（Python 3.8+）：

import shutil
shutil.copytree("src_folder", "dst_folder", dirs_exist_ok=True)

注意：dirs_exist_ok=True 只跳过“目录已存在”的报错，不会自动清理旧文件；若目标中已有同名文件，复制时会直接覆盖（无提示），但不会删除目标里源目录没有的文件。

• Python dirs_exist_ok，得自己先 shutil.rmtree(dst) 再调用 copytree
• 即使加了 dirs_exist_ok=True，如果目标路径是个**文件**（不是目录），依然会报错
• 符号链接默认被当作普通文件复制（内容被读取并写入），如需保留链接本身，要加 symlinks=True

复制时跳过某些文件或文件夹：用 ignore 参数过滤

shutil.copytree 的 ignore 参数接收一个函数，该函数返回要忽略的子项列表（即不复制的文件/目录名）。它不是路径匹配，而是对每个父目录下的直接子项做判断。

典型场景：跳过 .git、__pycache__、临时文件：

import shutil
def ignore_func(dir, contents):
    return [f for f in contents if f in (".git", "__pycache__") or f.endswith(".tmp")]

shutil.copytree("src", "dst", ignore=ignore_func)

• ignore 函数第一个参数是当前正在处理的父目录路径（字符串），第二个是该目录下所有子项名称列表（不含路径）
• 返回值必须是子项名称的列表（如 ["temp.log"]），不能是完整路径
• 这个过滤发生在遍历阶段，不影响已存在的目标目录结构；也不会阻止进入被忽略目录的子目录（除非该子目录名也被列入返回列表）

shutil.copytree 在 Windows 下遇到长路径或权限错误

Windows 默认路径长度限制为 260 字符，而 shutil.copytree 在递归创建深层嵌套目录时容易触发 OSError: [WinError 206] The filename or extension is too long。这不是 Python 编码问题，是系统级限制。

解决方法分两步：

• 启用 Windows 长路径支持（需管理员权限修改组策略或注册表）
• 在 Python 中强制使用 UNC 路径前缀：\\\\?\\C:\\full\\path —— 把源和目标路径都转成这种格式再传给 copytree
• 权限错误（如 PermissionError: [WinError 5] Access is denied）常因目标文件被其他程序占用，或源文件有只读属性；可加 copy_function=shutil.copy2（默认）确保元数据复制，但无法绕过系统锁

简单起见，若只是想“尽力复制”，建议先用 shutil.copytree，失败时捕获异常并打印具体路径，再针对性处理，而不是强行加各种兼容逻辑。

替代方案：用 shutil.copy 和 os.walk 手动控制复制流程

当 copytree 的固定行为无法满足需求时（比如需要日志、进度反馈、细粒度错误恢复、按文件类型分流复制），就得退回到底层组合方式。

核心思路：用 os.walk 遍历源目录，对每个文件调用 shutil.copy2（保留时间戳和权限），对每个目录用 os.makedirs(..., exist_ok=True) 创建：

import os, shutil
for root, dirs, files in os.walk("src"):
    dst_root = root.replace("src", "dst", 1)
    os.makedirs(dst_root, exist_ok=True)
    for f in files:
        shutil.copy2(os.path.join(root, f), os.path.join(dst_root, f))

• 这样能完全掌控每一步，比如在 shutil.copy2 前加 try/except 单独处理某个文件失败
• 注意 os.walk 返回的 dirs 是可修改列表，若想跳过某些子目录（如 .git），直接 dirs[:] = [d for d in dirs if d != ".git"]
• 性能上比 copytree 稍慢（多了 Python 层循环），但灵活性高得多

真正难的不是写几行代码，而是想清楚：你到底要“原样镜像”，还是“选择性搬运”——前者用 copytree 加参数就够了，后者就得自己搭骨架。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~