Python pathlib 相对路径规范化与文件判断

Python 用 pathlib 处理相对路径时，稳妥顺序是：先选定不受当前工作目录影响的根目录，再用 Path.resolve() 得到规范路径，确认它仍位于根目录内，最后判断是否为普通文件。不要只做字符串前缀比较，也不要把 absolute()、exists() 或 is_file() 当成完整的规范化方案。

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

触发信号：哪些现象说明路径判断有问题

线上常见信号并不是 pathlib 抛出一个统一错误，而是同一段代码在不同启动方式下得到不同结果。开发环境能找到文件，容器、定时任务或进程管理器启动后却报告不存在，通常是相对路径绑定到了不同的当前工作目录。

还要关注下面几类信号：

• 日志里同时出现 ./data/a.csv、data/../data/a.csv 等多种写法，导致缓存键或去重失效。
• 输入包含 ..，拼接后从允许目录跳到了父目录。
• 路径文本看起来位于根目录内，但中间某个目录是指向外部的符号链接。
• is_file() 只返回 False，调用方无法区分文件缺失、路径不可访问还是目标本来就是目录。
• Windows 上把相对路径、盘符相对路径和绝对路径混在同一套规则中。

先记录原始输入、配置根目录和失败原因枚举，不要只记录一个最终布尔值。日志中的路径还应按业务敏感度脱敏，避免暴露租户目录或私有文件名。

快速判断：先分清词法路径与真实路径

PurePath 系列操作主要是词法运算，不访问文件系统。官方文档明确说明，is_relative_to() 本身基于路径字符串，不会特殊处理 ..。因此，Path("/srv/import/a/../../etc").is_relative_to("/srv/import") 这类判断不能直接代表真实文件仍在允许目录中。

几个容易混淆的方法职责不同：

Python 3.14 中，exists()、is_file() 等查询方法对操作系统查询产生的 OSError 返回 False；较早版本对部分权限错误仍可能抛异常。若运行手册要求区分原因，不论版本都优先调用 stat() 并捕获具体异常。

处理步骤：规范化、限界和文件类型判断

下面的函数把策略写死为“只接受相对输入，目标必须已经存在，解析后的真实位置必须位于允许根目录内，并且必须是普通文件”。这种明确契约比在各调用点零散地拼接和判断更容易维护。

from __future__ import annotations

import stat
from pathlib import Path


class PathCheckError(ValueError):
    def __init__(self, reason: str, submitted: str) -> None:
        # reason 使用低基数枚举，便于日志和指标聚合。
        super().__init__(f"{reason}: {submitted}")
        self.reason = reason
        self.submitted = submitted


def require_regular_file(root: Path, submitted: str) -> Path:
    raw = Path(submitted)
    if raw.is_absolute():
        # 入口只接受相对路径，避免绝对部分覆盖前面的根目录。
        raise PathCheckError("absolute_input", submitted)

    try:
        # 根目录必须存在；部署配置错误应立即暴露。
        root_real = root.resolve(strict=True)
        # strict=True 同时消除点段、解析链接并要求目标存在。
        candidate = (root_real / raw).resolve(strict=True)
    except FileNotFoundError as exc:
        raise PathCheckError("missing", submitted) from exc
    except PermissionError as exc:
        raise PathCheckError("permission_denied", submitted) from exc
    except OSError as exc:
        # 链接环、无效路径等其他系统错误保留独立原因。
        raise PathCheckError("resolve_error", submitted) from exc

    if not candidate.is_relative_to(root_real):
        # 两边都已 resolve，此处判断的是规范路径的包含关系。
        raise PathCheckError("outside_root", submitted)

    try:
        mode = candidate.stat().st_mode
    except PermissionError as exc:
        raise PathCheckError("permission_denied", submitted) from exc
    except OSError as exc:
        raise PathCheckError("stat_error", submitted) from exc

    if not stat.S_ISREG(mode):
        # 目录、套接字、设备等都不满足“普通文件”契约。
        raise PathCheckError("not_regular_file", submitted)

    return candidate

调用时不要写 Path.cwd() / input，除非“当前目录”本来就是业务协议的一部分。更稳定的根目录来自明确配置，或来自模块文件的固定位置：

from pathlib import Path

# 配置目录固定在当前模块旁边，不受启动命令所在目录影响。
IMPORT_ROOT = Path(__file__).resolve().parent / "imports"

try:
    source = require_regular_file(IMPORT_ROOT, "daily/orders.csv")
except PathCheckError as exc:
    # 对外返回受控错误，对内按 reason 聚合，不泄露完整服务器路径。
    logger.warning("input path rejected", extra={"reason": exc.reason})
    raise
else:
    # 后续业务使用已经规范化且通过边界检查的 Path。
    process_file(source)

如果业务允许“目标暂时不存在，稍后创建”，可把目标改为 resolve(strict=False)，但父目录和最终写入动作仍需单独确认。若路径来自不可信输入，检查与打开之间还可能发生文件被替换的竞态；安全要求高的场景应尽快打开文件并基于文件描述符继续处理，而不是长期保存已检查过的路径字符串。

回滚路径：新规则误拦截时怎么处理

上线严格路径判断后，最常见的误拦截是历史任务传入绝对路径、依赖旧工作目录，或通过根目录内的符号链接访问共享文件。不要通过删除边界检查来快速恢复，而应保留一个受控回滚路径：

1. 先把旧根目录作为显式配置加入允许根目录列表，不恢复对任意当前目录的依赖。
2. 为每个允许根目录执行 resolve(strict=True)，候选路径只需命中其中一个规范根目录。
3. 仅对已知任务开放绝对路径兼容开关，并记录 legacy_absolute_input，设置下线日期。
4. 如果历史流程依赖符号链接，把链接真实目标加入配置并记录所有权，不要默认放行任何外链。

回滚验证看的是任务恢复率与拒绝原因分布，而不是“错误日志变少”。如果 outside_root 突然归零但绝对路径兼容量暴涨，说明只是绕过了新规则。

告警确认：用原因枚举代替路径全文

告警建议按 reason、任务类型和部署实例聚合，避免把完整路径作为标签。以下指标足以形成第一轮判断：

• path_check_rejected_total{reason="outside_root"}：突然增加时检查上游输入格式和根目录配置。
• path_check_rejected_total{reason="missing"}：结合文件到达延迟，区分任务提前启动和文件确实缺失。
• path_check_rejected_total{reason="permission_denied"}：关联部署用户、挂载权限和目录所有者变化。
• path_check_legacy_total：兼容路径应持续下降，长期不降就不能关闭回滚开关。

确认修复后，抽取成功任务的相对输入、规范后相对路径和文件类型做采样日志即可。不要记录文件内容，也不要把服务器绝对路径返回给外部调用方。

复盘项：把路径语义写成接口契约

复盘时至少补齐四项：根目录从哪里获得、是否允许绝对路径、是否允许符号链接指向根目录外、目标必须存在还是允许待创建。测试矩阵应覆盖普通文件、目录、不存在文件、.、..、根目录外链接、断裂链接、无权限目录，以及 Windows 和 POSIX 的不同锚点语义。

为什么不能直接比较字符串前缀？

/srv/data-old 也以 /srv/data 开头，大小写和分隔符规则还会随平台变化。使用已规范化的 Path.is_relative_to() 才是在路径组件层面判断包含关系。

只想知道是不是文件，还需要 stat() 吗？

不需要。只要真假结果时，is_file() 更简洁；需要区分缺失、权限、链接环或读取元数据时再用 stat()。

expanduser() 应该默认调用吗？

不应该。~ 是否代表用户主目录必须是输入协议的一部分。服务端上传路径通常不应展开用户目录；命令行工具明确支持该语法时才调用 expanduser()。

relative_to() 能代替 resolve() 吗？

不能。relative_to() 负责计算相对表示，默认是词法操作；路径含符号链接或 .. 时，应先根据业务语义调用 resolve()。