Python pathlib.Path.copy 怎样复制目录并保留元数据

如果你在 Python 里复制目录树，过去通常要在 shutil 和手写的符号链接处理之间做选择。Python 3.14 的 pathlib.Path.copy() 把“复制文件或目录树、是否跟随符号链接、是否尽量保留元数据”收进了一个 Path 方法里。实际使用时最重要的不是把参数全部填上，而是先分清复制对象和目标路径，再决定是否需要保留元数据。

官方地址：https://docs.python.org/3.14/library/pathlib.html

本文只讨论 Path.copy() 的复制范围、follow_symlinks、preserve_metadata 和平台边界，不把它当成完整备份工具，也不延伸到跨平台权限迁移。

Path.copy() 先解决“复制到哪里”

Path.copy(target) 可以复制一个文件，也可以复制一棵目录树，并返回一个新的 Path 对象指向目标。目标是已有文件时，文件复制会替换它；目录复制则要根据目标形态和操作系统规则处理。因此，调用前要把 source 与 target 写成两个清晰的路径对象。

from pathlib import Path

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

# copy 返回目标 Path，后续可以继续拼接或交给日志记录。
copied = source.copy(target)
print(copied)

这里的重点是返回值：它不是源路径的副本，而是目标路径对象。对需要把复制结果继续传给压缩、清单或日志模块的代码来说，这比复制后再手工拼接目标路径更稳。

两个参数要分别决定，不要混为一个“完整复制”开关

follow_symlinks 决定遇到符号链接时复制什么：默认值 True 会沿着链接复制它指向的目标；设置为 False 时，复制结果会在目标位置重建符号链接。它改变的是对象边界，不是权限和时间戳。

preserve_metadata 决定是否尽量复制权限、文件标志、访问与修改时间以及扩展属性。默认值是 False，只保证目录结构和文件数据这类基本内容；设置为 True 才表达“目标要尽可能保留源对象的元数据”。

from pathlib import Path

source = Path("workspace")
target = Path("backup/workspace")

# 不把链接目标展开，同时尽量保留可支持的元数据。
copied = source.copy(
    target,
    follow_symlinks=False,
    preserve_metadata=True,
)

# 复制结果仍然是 Path，便于明确记录最终目标。
print(f"复制目标：{copied}")

这两个参数可以独立组合：你可以跟随链接但不保留元数据，也可以保留元数据但把链接本身复制过去。写成组合前，先回答两个问题：目标需要的是链接指向的内容，还是链接对象本身？目标是否需要承接源文件的权限和时间信息？

符号链接和元数据都有平台边界

官方文档明确说明，preserve_metadata=True 的效果取决于操作系统和文件系统支持；在 Windows 上，这个参数对文件复制没有额外作用，因为相关元数据本来就会被保留。也就是说，它不是跨平台一致的权限迁移承诺。

另一个容易忽略的边界是轻量复制：如果操作系统和文件系统支持，Path.copy() 可能使用写时复制，只在数据发生变化时才复制数据块。这是实现层面的优化，不能写成“所有机器都会零拷贝”，也不应替代对目标空间和权限的检查。

如果源对象是软链接，备份目录需要可独立还原，通常优先考虑 follow_symlinks=False；如果只是为了获得链接指向的文件内容，默认行为更直接。至于权限、时间和扩展属性，只有目标平台的支持能力与业务要求都明确时，才打开 preserve_metadata=True。

把 Path.copy() 放进版本和迁移判断

Path.copy() 是 Python 3.14 新增的 API。项目仍需支持更低版本时，不能只把调用替换进公共代码就结束；应在兼容层里保留旧实现，或者把最低 Python 版本同步提升，并在发布说明中写清楚这一点。

我会用下面这张小表做迁移前的判断：

如果复制任务还要求校验哈希、增量清单、失败重试、跨主机传输或灾备恢复，应该把这些能力交给专门的备份流程。Path.copy() 的价值在于把一次本地文件系统复制表达得更清楚，而不是替整个备份系统背书。

常见问题

Path.copy() 会自动复制符号链接指向的文件吗？

默认会，因为 follow_symlinks=True。如果需要复制链接对象本身，显式传入 False。

preserve_metadata=True 能保证所有平台结果一样吗？

不能。它表示尽量保留文档列出的元数据，最终仍受操作系统和文件系统能力影响。

低版本 Python 能直接使用 Path.copy() 吗？

不能把它当作低版本通用 API。低版本项目应保留兼容实现，或在项目升级到 Python 3.14 后再使用。

总结一下：先用目标路径确定复制边界，再分别选择符号链接策略和元数据策略。只要把这三个判断拆开，Path.copy() 就能成为清晰的本地复制入口，而不会被误用成跨平台备份方案。