Pythonshutil.copytree使用方法与实例解析

本文深入解析了Python中shutil.copytree函数的核心行为与常见痛点，重点揭示其默认严格要求目标目录必须不存在的设计逻辑，以及由此引发的FileExistsError问题；同时详解Python 3.8+新增的dirs_exist_ok=True参数如何安全跳过目录存在检查、实现增量覆盖（仅覆盖同名文件，不清理多余内容），并对比手动删除与自定义逻辑等替代方案，帮助开发者避开坑、写出更健壮的目录复制代码。

copytree 会直接报错说目标目录已存在

这是最常遇到的问题：shutil.copytree 默认不允许目标路径存在，哪怕是个空文件夹也会抛出 FileExistsError。它设计上就要求目标目录必须不存在——不是“跳过”，而是“严格新建”。

解决方法只有两个：要么手动删掉目标目录，要么自己实现覆盖逻辑。Python 3.8+ 提供了 dirs_exist_ok 参数，但要注意它只跳过“目录已存在”错误，不处理同名文件冲突：

shutil.copytree("src", "dst", dirs_exist_ok=True)

这个参数在旧版本（TypeError。

想覆盖已有文件就得自己遍历 + copy2

copytree 本身不支持“强制覆盖文件”，即使开了 dirs_exist_ok=True，遇到同名文件仍会失败（比如 dst/a.txt 已存在，而 src/a.txt 也要拷过去）。这时候得退回到底层组合操作：

• 用 os.walk 遍历源目录树
• 对每个文件，用 os.path.relpath 算出相对路径，拼到目标根目录下
• 确保目标父目录存在（os.makedirs(..., exist_ok=True)）
• 调用 shutil.copy2（保留时间戳和权限）或 shutil.copy（仅内容）

注意别用 shutil.copyfile——它不支持目录创建，且不保留元数据。

忽略某些文件或目录要用 ignore 参数

copytree 的 ignore 参数接收一个函数，签名是 ignore(src_dir, names) → list_of_names_to_ignore。常见误用是直接返回布尔值或字符串，结果报错或无效。

正确写法示例（忽略 .git 和所有 .pyc 文件）：

def ignore_func(dir, contents):
    return [n for n in contents if n == ".git" or n.endswith(".pyc")]

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

注意：这个函数对每个子目录都会被调用一次，contents 是当前目录下的全部条目名（不含路径），不是全路径。

符号链接默认被展开，要保留得加 symlinks=True

默认情况下，copytree 遇到符号链接会把链接指向的真实文件/目录复制过去（即“解引用”）。如果源里有 ln -s ../data data_link，默认行为会把 ../data 的内容整个复制进 dst/data_link，而不是建个新链接。

要原样复制符号链接本身，必须显式传 symlinks=True：

shutil.copytree("src", "dst", symlinks=True)

这个选项和 dirs_exist_ok 可以共存，但要注意：如果目标系统不支持符号链接（如某些 FAT32 挂载点），会抛出 OSError。

真正麻烦的是混合需求：既要覆盖文件、又要保留链接、还要忽略部分路径、还得兼容老 Python 版本——这种时候别硬塞进 copytree，老老实实写个带条件分支的遍历循环更可控。

以上就是《Pythonshutil.copytree使用方法与实例解析》的详细内容，更多关于的资料请关注golang学习网公众号！