Python pathlib 组织跨平台文件复制

用 pathlib 组织跨平台复制，关键是把源文件、目标目录和目标文件分开，用 Path 的路径拼接代替手工拼斜杠，再交给复制接口。兼容较早 Python 环境时可使用 shutil.copy2；Python 3.14 起也提供 Path.copy 和 Path.copy_into，不能把新方法直接套到所有旧解释器上。

我更偏向先确定最低 Python 版本与覆盖规则，再选择写法。方法调用少一行，不值得让部署环境悄悄改变语义。下面用“把一份 CSV 放入输出目录”的自拟例子说明，不声称已在 Windows、macOS 与 Linux 分别运行过。

官方文档入口：https://docs.python.org/3.14/library/pathlib.html。

为什么不再手工拼目录字符串

把目录与文件名写成字符串加法，很容易漏掉分隔符，也容易把某个系统的路径形式混入其他环境。Path(root) / "exports" 表达的是路径组件关系，不是数学除法，也不会执行复制。Path 对象负责组织路径，文件复制是另一个动作。

跨平台不表示同一个绝对路径能到处使用。Windows 盘符、文件名限制、大小写与权限仍由目标平台决定。相对路径依赖当前工作目录，因此脚本从任务调度器启动时，不能默认它位于源码目录。下面的 root 参数应由调用端提供可信配置。

把源文件、目标目录和文件名分开

示例中的 src 是源文件，target_dir 是目标目录，dst 是完整目标文件。src.name 只取末尾文件名，再与目标目录组合；不会把源目录整棵复制过去。mkdir(parents=True, exist_ok=True) 用于准备目录，不是复制成功证明。

from pathlib import Path
import shutil


def copy_report(root: Path) -> Path:
    # root由调用方提供，避免依赖任务启动时的当前工作目录。
    base = Path(root)
    src = base / "input" / "summary.csv"
    target_dir = base / "output"

    # 先准备目录；同名路径若不是目录，这里仍会失败。
    target_dir.mkdir(parents=True, exist_ok=True)
    dst = target_dir / src.name

    # 该写法允许覆盖同名目标文件，仅适合明确接受覆盖的任务。
    copied = shutil.copy2(src, dst)
    return Path(copied)

示例限于受控目录中的普通文件。copy2 可以接收 Path，因此无须为了调用它而全部转换成字符串。返回值统一包装成 Path，便于调用端继续取 name 或 parent。调用端必须知道：这段代码并没有实现“禁止覆盖”。

3.14 的复制方法改变了什么

3.14 新增的 Path.copy(target) 把复制操作放到 Path 上，返回指向目标的 Path；Path.copy_into(target_dir) 则表达放入一个已有目录。两者还能处理目录树，但本文不展开递归复制。

from pathlib import Path


def copy_report_314(root: Path) -> Path:
    # 仅用于Python 3.14及以上，目标目录仍须预先准备。
    src = Path(root) / "input" / "summary.csv"
    target_dir = Path(root) / "output"
    target_dir.mkdir(parents=True, exist_ok=True)

    # copy_into保留源名称；不把目录参数误写成完整目标文件。
    return src.copy_into(target_dir, preserve_metadata=True)

如果需要改名，则把完整目标文件交给 copy，例如 src.copy(target_dir / "summary-backup.csv")。不要认为新增接口天然禁止重名覆盖。preserve_metadata=True 也不意味着所有平台的每一种元数据都能完全一致；平台支持范围仍然重要。

我的选择是：最低版本尚未统一时保留 copy2；已经明确采用 3.14 及以上时，可以考虑 Path 复制方法。不要用捕获所有异常后自动换方法的方式兼容，否则权限问题也可能被误判为版本问题。

异常要保留，失败不能返回目标路径

路径拼接正确，仍可能遇到源文件不存在、目标目录无写权限、源与目标实际是同一文件。文件系统状态还会在检查后变化。exists() 或 is_file() 可以帮助交互提示，但不替代复制时的异常处理。

from pathlib import Path
import shutil


def copy_with_context(src: Path, target_dir: Path) -> Path:
    # 输入由可信配置给出；本函数不承担任意用户路径隔离。
    src = Path(src)
    target_dir = Path(target_dir)
    try:
        target_dir.mkdir(parents=True, exist_ok=True)
        result = shutil.copy2(src, target_dir / src.name)
    except shutil.SameFileError:
        # 同一文件是调用参数问题，保留原始异常给调用端处理。
        raise
    except OSError as exc:
        # 保留cause，日志展示时再按应用规则脱敏路径。
        raise RuntimeError("复制失败，请检查源文件、目标目录与访问权限") from exc
    return Path(result)

成功路径只出现在复制调用正常返回之后。失败时不要先返回 dst，再要求下游靠文件是否存在猜测成功；目标可能是旧文件，也可能是不完整的新文件。本文示例不提供事务式替换，也不会自动删除失败目标，避免误删用户已有数据。

跨平台采用前明确三项约定

若任务要求绝不覆盖，不能只在复制前执行一次 exists()：检查与写入之间存在竞态。应另行设计排他创建或受控任务目录方案，不把当前配方宣称为无覆盖复制。符号链接、跨用户共享目录与完整备份语义也不在这份普通文件配方范围内。

在自己的工程中可覆盖正常复制、源不存在、目标被普通文件占据、权限不足、同一文件与同名覆盖等用例。这里是建议用例清单，不是已执行记录。

常见问题

创建 Path 会创建文件吗？不会，构造路径对象与执行 mkdir、复制等操作要区分。

copy2 等于完整备份吗？不等于。它尝试保留元数据，但官方明确提醒，所有者、ACL等并不能在所有平台完整复制。

为什么换启动方式就找不到文件？优先确认相对路径基准。我的建议是让入口配置根目录，再由函数组合组件，而不是在函数内部猜测工作目录。

参考：Python pathlib 官方说明；Python shutil 官方说明。路径组织、函数封装与异常提示为本文原创示例。