Python shutil.copytree 怎样合并已有目标目录

在部署静态资源、整理数据目录或同步构建产物时，目标目录经常已经存在。shutil.copytree() 的关键不是把目标目录先删掉，而是显式传入 dirs_exist_ok=True：

from pathlib import Path
from shutil import copytree

# 源目录的新文件会写入已有目标目录，同名文件按源目录内容覆盖
source = Path("build/assets")
destination = Path("release/assets")
copytree(source, destination, dirs_exist_ok=True)

这个参数的语义是“允许目标目录已存在并继续复制”，不是事务合并，也不是冲突保留。目标树中与源树对应的同名文件仍可能被覆盖，所以调用前要先确认覆盖范围。

先看清默认行为为什么会失败

copytree(source, destination) 的默认值是 dirs_exist_ok=False。当 destination 已经存在时，函数会抛出 FileExistsError，这是为了避免调用方在不知情的情况下把一个目录树写进旧目录。

把它改成 True 后，目标目录本身可以存在，缺少的中间目录会创建；源目录里的新文件会被复制进去，目标树中对应的同名文件会由源文件覆盖。可以把两种行为放在一张静态说明图里理解：

用 dirs_exist_ok=True 合并已有目录

最小写法只有一个关键参数：

from pathlib import Path
from shutil import copytree

def merge_directory(source_dir: str, target_dir: str) -> Path:
    # Path 让调用方可以传入字符串，同时保留跨平台路径拼接能力
    source = Path(source_dir)
    target = Path(target_dir)

    # True 只放宽“目标目录已存在”的限制，不会取消文件覆盖语义
    return copytree(source, target, dirs_exist_ok=True)


result = merge_directory("build/assets", "release/assets")
# 返回值是目标目录路径，便于后续记录本次复制的落点
print(result)

这段写法适合重复部署：第一次复制时创建目标树，后续复制时复用同一目标目录。它不会删除目标目录里源目录没有的旧文件，因此“合并”更接近“把源树写入目标树”，而不是让两棵树自动达到完全一致。

实际任务可以先列出覆盖约定：

别把目录合并当成事务

copytree() 会递归处理目录和文件；默认文件复制函数是 copy2，会尽量复制文件元数据，但这不代表所有平台上的所有元数据都能完整保留。复制过程中如果遇到权限、特殊文件或符号链接问题，结果也不应被当成“要么全部成功、要么完全没写入”的事务。

需要过滤缓存、临时文件时，可以把 ignore 一起传入：

from pathlib import Path
from shutil import copytree, ignore_patterns

source = Path("project")
target = Path("release/project")

# 过滤规则只负责跳过匹配项，不会替目标目录清理历史文件
ignore_cache = ignore_patterns("__pycache__", "*.pyc", ".pytest_cache")

copytree(
    source,
    target,
    dirs_exist_ok=True,
    ignore=ignore_cache,
)

copy_function、符号链接和异常怎么取舍

如果业务要改用 copy 或自定义复制函数，可以通过 copy_function 传入一个接收源路径和目标路径的可调用对象。默认的 copy2 会尽量保留元数据，改用更简单的复制函数可能牺牲部分元数据能力。

symlinks 决定源目录中的符号链接是作为链接写入，还是复制链接指向的内容；ignore_dangling_symlinks 只影响某些悬空链接错误的处理。它们与 dirs_exist_ok 是不同维度的策略，不要用一个参数代替另一个参数。

发生多个文件错误时，copytree() 可能抛出 shutil.Error，其中包含源路径、目标路径和具体异常。调用方可以记录这些项，再决定是人工修复权限后重跑，还是把复制任务标记为失败；不要仅凭函数返回了目标路径就推断每个文件都已符合预期。

一份可重复使用的判断清单

1. 确认运行环境至少支持 dirs_exist_ok，它是在 Python 3.8 中加入的参数。
2. 明确同名文件是否允许由源文件覆盖目标文件。
3. 确认目标目录及其父目录有写权限，并考虑磁盘空间和只读文件。
4. 决定是否用 ignore 排除缓存、测试产物或本地配置。
5. 如果依赖符号链接或文件元数据，单独确认 symlinks、copy_function 和平台差异。
6. 把 shutil.Error 等复制异常记录下来，失败后不要把部分写入当作完整发布结果。

因此，Python 用 shutil.copytree 合并已有目标目录的核心写法就是 dirs_exist_ok=True；真正需要做决定的是覆盖、过滤、链接、元数据和失败处理，而不是先删除目标目录。

相关问题

• dirs_exist_ok=True 会删除目标目录多余文件吗？不会，源目录没有的目标旧文件会保留。
• 同名文件会怎么处理？源目录中的对应文件会覆盖目标文件，调用前应确认这符合发布策略。
• 怎么跳过缓存目录？把 ignore_patterns() 生成的过滤函数传给 ignore。
• copytree 失败后能否直接认为没有变化？不能，递归复制可能已经写入一部分内容，应按异常记录处理。