Python pathlib.Path.hardlink_to 创建硬链接的跨设备报错处理

用 pathlib.Path.hardlink_to() 创建硬链接时，最容易误判的不是 Python 语法，而是文件系统边界：新路径的父目录必须和源文件位于同一文件系统；如果跨挂载点，继续重试只会得到同样的 OSError。正确做法是先比较设备号，再决定创建硬链接，或明确降级为独立副本。

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

Path.hardlink_to 的参数方向和文件系统关系

调用方向可以按“新路径的方法 + 已存在的源路径”理解。下面的 target 是将要创建的目录项，source 是已经存在的文件；调用成功后，两条路径访问的是同一份文件内容和 inode，而不是复制出两份内容。

from pathlib import Path

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

# target 是新目录项，source 是已有文件；两者会共享同一个 inode
target.hardlink_to(source)

因此，目标父目录的权限、目标文件是否已经存在、源文件是否存在，都会影响结果。硬链接不等于快捷方式，也不等于复制：删除其中一个目录项，不会立即删除数据，只要仍有其他硬链接指向该 inode，文件内容仍然存在。

先比较 st_dev，再处理跨设备边界

硬链接属于文件系统能力，不是单纯的路径字符串操作。可以先比较源文件和目标父目录的 st_dev。目标路径本身可能还不存在，所以比较它的父目录更稳妥。

from pathlib import Path

def same_filesystem(source: Path, target: Path) -> bool:
    # 源文件必须存在；目标只检查父目录，因为目标文件准备新建
    source_device = source.stat().st_dev
    target_device = target.parent.stat().st_dev
    return source_device == target_device

source = Path("/data/inbox/report.csv")
target = Path("/backup/report.csv")

if not same_filesystem(source, target):
    # 跨设备时不要继续调用 hardlink_to，先交给上层选择降级策略
    raise OSError("source and target are on different file systems")

# 同设备才尝试建立硬链接
target.hardlink_to(source)

这个预检不是绝对的事务锁：检查之后目录挂载、权限或目标状态仍可能变化，所以正式调用仍要捕获异常。它的价值在于把最常见的跨设备错误提前变成可解释的分支，而不是把所有 OSError 都归因于权限。

不能建硬链接时，复制还是返回错误

跨设备时，shutil.copy2() 可以得到独立副本，但它改变了语义：后续修改源文件不会同步到副本。只有业务允许“发布一份当时的文件”时才适合降级；如果程序依赖两个路径始终看到同一份数据，就应该返回明确错误，让调用方换同一文件系统的目标目录。

from pathlib import Path
from shutil import copy2

def link_or_copy(source: Path, target: Path, allow_copy: bool = False) -> str:
    # 先确保父目录存在，避免把目录缺失误判成跨设备问题
    target.parent.mkdir(parents=True, exist_ok=True)
    try:
        target.hardlink_to(source)
        return "hardlink"
    except FileExistsError:
        # 不静默覆盖既有目录项，保持失败可见
        raise
    except OSError as exc:
        if not allow_copy:
            # 不允许改变共享 inode 语义时，向上层保留原始失败
            raise RuntimeError("hard link is unavailable") from exc
        # copy2 产生独立副本；调用方应记录这一语义变化
        copy2(source, target)
        return "copy"

生产代码还要考虑目标文件部分写入后的清理、源文件在操作期间被替换，以及复制完成后的大小或摘要核对。不要仅凭返回字符串判断“已同步”；hardlink 和 copy 是两种不同的生命周期约定。

上线前的检查清单

• 确认参数顺序是 target.hardlink_to(source)，不要把源和目标写反。
• 确认源文件存在，目标父目录存在且可写，目标目录项不存在或有明确替换规则。
• 比较源文件与目标父目录的 st_dev，但不要把预检当成最终成功保证。
• 把硬链接和复制分别记录，尤其是跨设备降级后的一致性与清理责任。

相关问题

Path.hardlink_to 会复制文件内容吗？

不会。它创建新的目录项并指向已有 inode，源路径和目标路径看到的是同一份文件内容。

为什么目标路径不存在也能调用 hardlink_to？

目标目录项正是要创建的对象，所以目标文件可以不存在；但目标父目录必须存在并可写。

跨设备时把 hardlink_to 重试几次有用吗？

通常没有用。跨设备是文件系统边界，不是瞬时网络错误；应改用同设备目标，或明确切换为独立副本。