Python 3.14 pathlib.Path.copy() 与 move() 怎么迁移文件树：元数据、符号链接和跨盘边界

做备份工具把一整棵目录树搬到归档盘的时候，以往代码里总要写 shutil.copytree()、shutil.move() 再加一堆符号链接判断逻辑。Python 3.14 的 pathlib.Path 终于补上了文件树复制移动的原生能力：copy()、copy_into()、move()、move_into() 都会返回新的 Path，整个迁移逻辑可以全程围绕路径对象来写，不用来回转字符串。上手之前只要先分清「复制到指定目标路径」和「放进已有的目标文件夹」两种场景，再按需配置要不要跟随符号链接、要不要保留元数据，跨存储分区的时候要清楚它会自动退化成复制后删除的逻辑，就能少踩很多坑。

先用一个最小目录样例理清四个方法的分工

假设你要处理的源目录是 workspace/report，目标文件夹是已经提前创建好的 archive/2026-08。如果你想把源目录整个生成一个指定名字的新路径，直接用 copy()；如果你只想把源目录整个放进已经存在的目标文件夹里，不需要改源目录的名字，就用 copy_into()。移动类的两个方法命名规则和复制完全对应。

from pathlib import Path

source = Path("workspace/report")
archive = Path("archive/2026-08")

# 目标路径是 archive/2026-08/report
copied = source.copy_into(archive)
print(copied)

# 目标路径是 archive/report-current
moved = source.move("archive/report-current")
print(moved)

copy_into() 要求传入的目标文件夹必须已经存在，返回的路径对象会指向新生成的子目录 archive/2026-08/report。copy() 是把传入的参数直接当成最终的目标路径来处理；源是单个文件的时候可以直接替换同名文件，源是整棵目录树的时候要提前检查目标路径是否存在，避免出现非预期的覆盖。生产环境的代码要把方法的返回值直接存到迁移记录里，不要自己拼接原路径去猜最终生成的路径是什么，很容易出问题。

copy() 的两个核心开关直接决定备份结果是否符合预期

默认 follow_symlinks=True 的时候，源目录里的所有符号链接都会顺着指向把实际内容复制过去。如果是做系统备份这类需要保留原链接关系的场景，必须显式传入 False；这不是显示效果的小区别，会直接影响最终目标文件树的实际语义。

from pathlib import Path

src = Path("workspace/report")
dst = Path("archive/report-copy")

result = src.copy(
    dst,
    follow_symlinks=False,
    preserve_metadata=True,
)
print(result)

preserve_metadata=True 开启后会尽可能保留文件权限、访问和修改时间、系统文件标志，还有当前文件系统支持的扩展属性。但这个能力不是跨平台完全通用的，官方文档也明确标注了元数据的保留程度受操作系统和挂载的文件系统限制，Windows 平台下的文件元数据还有单独的处理规则。上线验收的时候要专门检查你业务真正依赖的那些元数据字段是否正确，不能只看复制函数没抛异常就认为全量数据没问题。

move() 不能想当然认为永远是原子操作

源路径和目标路径在同一个文件系统内时，Path.move() 可以直接调用 os.replace() 完成移动，这个过程速度很快也适合做目录内的归档改名操作。跨文件系统的时候，Path 会先完整复制所有内容并按配置保留元数据和符号链接，全部完成之后才去删除源路径。碰到往归档盘、额外挂载卷或者容器存储卷迁移的场景，必须把它当成一个可能中途中断的长任务来处理。

from pathlib import Path

source = Path("incoming/report.csv")
target = Path("archive/report.csv")

if source.stat().st_dev == target.parent.stat().st_dev:
    moved = source.move(target)
else:
    copied = source.copy(target, preserve_metadata=True)
    # 业务确认校验和、大小和权限后，再删除 source
    print("cross-filesystem copy completed:", copied)

上面提到的通过设备号判断是否同盘的逻辑只能作为流程提示，不能替代完整的异常捕获处理：网络挂载的文件系统、权限突变、目标路径冲突、机器中途断电这些场景都可能改变最终结果。跨盘迁移的代码里要记录好源路径、目标路径、文件大小、校验结果和源文件清理状态，后续做断点恢复的时候优先查这张记录就可以快速补全。

Python 3.13 及更早版本的兼容方案

这四个新方法是 Python 3.14 才新增的能力。如果项目还需要支持更低版本的解释器，可以把所有文件树操作封装到一个很小的适配层里，内部使用 shutil.copytree()、shutil.copy2() 和 shutil.move() 来实现相同逻辑，并且让适配层统一返回 Path。等后续全量升级到 Python 3.14 的时候只要替换适配层的实现就好，不用在业务代码的各个角落写版本判断。

import shutil
from pathlib import Path

def copy_tree(source: Path, target: Path) -> Path:
    shutil.copytree(source, target, symlinks=True, copy_function=shutil.copy2)
    return target

def move_tree(source: Path, target: Path) -> Path:
    return Path(shutil.move(source, target))

写兼容层的时候，传入的参数规则要和新 API 的业务约定完全对齐，尤其是要不要跟随链接、目标路径已存在的时候怎么处理、元数据保留到什么程度这些细节，不能只是把函数名改了，实际逻辑悄悄改变导致备份出来的结果不符合预期。

上线前用验收清单核对文件树迁移效果

• 目标路径定义是否清晰：是要生成一个全新的指定路径，还是要把源内容放进已经存在的目标文件夹。
• 符号链接是否需要保留为链接本身，有没有指向源目录之外的风险链接。
• 权限、时间戳、扩展属性是不是属于业务必须保留的核心数据，目标文件系统是否支持存储这些字段。
• 跨文件系统迁移的时候有没有配套的完整性校验、断点进度记录和失败后的清理补偿逻辑。
• 目标路径已经存在或者目标目录非空的冲突场景，有没有先暂停逻辑，交由上层调用方决定是否覆盖。

常见问题

Path.copy() 会自动创建目标的父目录吗？

不要依赖隐式的自动创建逻辑。目标路径的父目录和 copy_into() 传入的目标文件夹都要提前准备好，调用方法之前专门做存在性检查更稳妥。

怎么复制符号链接本身而不是它指向的内容？

传入 follow_symlinks=False 即可。这个参数默认值是 True，默认行为就是直接复制链接指向的实际内容。

Path.move() 和 shutil.move() 该怎么选？

新项目已经确定只使用 Python 3.14 版本的话，用 Path 自带的 API 可以全程保持路径对象传递的链路统一；需要兼容旧版本解释器或者已经有基于 shutil 的成熟封装的话，继续用之前的适配层方案更稳妥。

跨盘移动失败之后源文件还会完整保留吗？

没法用一句话绝对保证结果。跨文件系统的移动过程天然分成「复制全量内容」和「删除源文件」两个阶段，出问题之后要先读迁移记录，分别核对目标文件的完整性和源文件的清理状态再做后续处理。