Python pathlib.Path.rename 跨文件系统为什么失败：EXDEV 排查与安全迁移写法

把上传目录里的文件归档到另一块磁盘时，Path.rename() 可能突然抛出 OSError: [Errno 18] Invalid cross-device link。这不是目标文件名写错，而是重命名依赖同一文件系统内的目录项调整；跨挂载点时，程序需要改成“复制到目标、校验完成、再处理源文件”的迁移流程。

异常现场：为什么本地目录能改名，归档目录却失败

很多新手写的移动文件代码往往只有一行：

from pathlib import Path

src = Path("/srv/upload/report.csv")
dst = Path("/mnt/archive/report.csv")
src.rename(dst)

如果 /srv 和 /mnt/archive 属于同一个文件系统，这段代码通常只是改目录项，速度很快；如果归档盘是单独挂载的卷，内核会拒绝用 rename 直接跨过去。Linux 上常见的错误号是 EXDEV，Python 将它包装成 OSError。

先把异常类型记下来，不要立刻扩大重试

排查时先记录源路径所在的挂载点、目标路径所在的挂载点和 exc.errno。同名文件、目标目录不存在、权限不足，都可能是不同的错误。把它们一律重试，会让真正的配置问题被掩盖。

import errno
from pathlib import Path

try:
    Path("/srv/upload/report.csv").rename("/mnt/archive/report.csv")
except OSError as exc:
    if exc.errno == errno.EXDEV:
        print("需要走跨文件系统迁移流程")
    else:
        raise

rename、replace 和 copy 的边界分别是什么

Path.rename() 适合同一文件系统内的改名或移动；os.replace() 适合在同一文件系统里，用新文件替换已有目标并尽量保持操作的原子性。它们都不是跨设备复制接口。遇到 EXDEV 后，应该明确切换到复制流程，而不是把 rename 包在无限重试里。

跨文件系统迁移的安全顺序

你真正要关注的从来不是“调用的复制函数能不能正常跑完”，而是如果中途进程被打断，目标文件夹里会不会留下一个看起来正常、实际只写入了一半的损坏文件。正确的做法是先往目标路径下写临时命名的文件，复制完成做完所有核对之后，再把临时文件改名成最终的正式文件名。

from pathlib import Path
import hashlib
import os
import shutil

def sha256(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as stream:
        for block in iter(lambda: stream.read(1024 * 1024), b""):
            digest.update(block)
    return digest.hexdigest()

def move_across_filesystems(src: Path, dst: Path) -> None:
    dst.parent.mkdir(parents=True, exist_ok=True)
    temp = dst.with_name(dst.name + ".part")
    try:
        shutil.copy2(src, temp)
        if src.stat().st_size != temp.stat().st_size:
            raise IOError("复制后文件大小不一致")
        if sha256(src) != sha256(temp):
            raise IOError("复制后 SHA-256 不一致")
        os.replace(temp, dst)
    except Exception:
        temp.unlink(missing_ok=True)
        raise

这段函数只负责把内容安全地落到目标位置，故意没有自动删除源文件。删除源文件是业务确认动作：只有目标文件已经可读、大小和哈希都匹配，且归档记录写入成功，才适合执行 src.unlink()。如果源文件还要作为重试依据，就保留它，把迁移状态放进数据库或任务表。

临时文件名要能被任务恢复识别

.part 只是示例。多进程任务里更适合加入任务 ID，并使用独占创建避免两个进程写同一个临时文件。清理逻辑也要允许临时文件不存在，不能因为第一次失败留下的残片让第二次重试再次失败。

三个容易漏掉的失败边界

目标已存在时不要悄悄覆盖

归档任务如果允许重复执行，应先定义幂等策略：同名且哈希一致可以记录“已完成”，同名但内容不同则换任务 ID 或进入人工处理。不要为了让脚本不报错，直接用覆盖操作抹掉已有归档。

复制成功不等于源文件可以删除

复制返回成功，只能说明目标字节已写出。还要确认目标能被重新打开，业务记录是否已经指向新路径，以及任务是否需要保留源文件一段时间。文件迁移和业务状态更新最好能通过状态字段串起来，而不是靠一个 try 块包办所有动作。

大文件校验要考虑时间和磁盘空间

哈希校验会再次读取整个文件，几百 GB 的归档任务不能把它当成零成本操作。可以先用大小和修改时间做快速筛选，再按重要程度启用 SHA-256；无论采用哪种策略，都要把核对方式写入任务记录，避免以后无法解释“为什么认为迁移完成”。

如何验证修复真的生效

测试时至少覆盖同一文件系统、跨文件系统、目标同名、复制中断和源文件不可读五个场景。不要只在开发机上把 /tmp/a 改成 /tmp/b，那只能验证 rename 的成功路径。

python -m pytest -q tests/test_file_migration.py
python -m compileall -q src

验收日志建议包含任务 ID、源路径、目标路径、是否跨设备、临时文件名、校验方式和最终状态。看到目标文件出现并不代表任务完成，状态应在最后一次校验通过后才写成 completed。

常见问题

Path.rename 报 Errno 18 一定是磁盘坏了吗？

不一定。Errno 18 通常对应跨设备链接，首先检查两个路径是否位于不同挂载点；它和磁盘损坏不是同一个结论。

可以捕获 EXDEV 后直接 shutil.move 吗？

你完全可以把这些封装好的高层工具当作开发的起点，但跑在线上生产环境的代码，最好还是明确定义临时文件命名规则、完整性校验逻辑、同名文件处理策略和失败后的自动清理流程。只直接调用一个封装好的高层移动函数，你很难在出问题的时候明确知道源文件到底是在哪一步被删掉的。

为什么复制完成后还要用 os.replace？

先写临时文件再替换最终文件，可以避免用户或下游任务读到半成品。这个替换操作依然要求临时文件和最终文件位于同一目标文件系统内。

把迁移状态设计成可复查的结果

处理 EXDEV 的关键不是换一个 API 名称，而是把“复制、校验、替换、删除源文件”拆成可观察的阶段。这样任务中断时能识别临时文件，重复运行时能判断同名目标，出问题时也能保留源文件作为恢复依据。对重要归档，宁可多留一份待确认文件，也不要把一次未核对的复制当成完成。