Pythonshutil.copytree复制文件夹教程

本文深入解析了Python中`shutil.copytree`全量复制文件夹的核心用法与常见陷阱：重点介绍了Python 3.8+新增的`dirs_exist_ok=True`参数如何安全绕过“目标目录已存在”的报错，同时强调其仅覆盖同名文件、不清理冗余内容的本质；对比了旧版本需手动`rmtree`的风险，并详解了`ignore`函数的正确写法、Windows长路径/权限问题的实战解决方案，以及在复杂需求下用`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 加参数就够了，后者就得自己搭骨架。

今天关于《Pythonshutil.copytree复制文件夹教程》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！