Python pathlib 怎样安全拼接用户提供的相对路径

我在做文件下载接口时，最容易写错的不是 Path 的拼接，而是把“看起来像相对路径”的字符串直接交给文件系统。用户提交 ../config.ini，或者提交一个以斜杠开头的绝对路径，都可能让目标离开预期目录。

比较稳妥的写法是：先把固定根目录解析成绝对路径，再把用户输入拼到根目录下并解析，最后用 is_relative_to() 判断解析后的候选路径是否仍在根目录内。通过判断后，才进入读取或写入阶段。

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

先把“拼接”和“安全”分开理解

root / user_path 只是 pathlib 的路径组合表达式，它不会替你判断用户输入是否越界。如果 user_path 是绝对路径，路径组合还可能切换到另一条锚点；如果输入包含 ..，组合结果也只是保留了这层语义。

因此本文只采用一个明确边界：所有允许访问的目标必须位于固定的 root 目录中。边界判断针对解析后的候选路径，而不是原始字符串。

先解析受控根目录，再解析候选路径

根目录最好来自服务端配置，而不是来自请求参数。调用 resolve() 后，根目录本身拥有稳定的绝对表示；候选路径也要从这个根目录出发解析。下面的辅助函数把越界情况统一转换成 ValueError，调用方可以在接口层把它映射为普通的拒绝响应。

from pathlib import Path

def safe_join(root: str | Path, user_value: str) -> Path:
    # 根目录由服务端决定，先解析它以消除相对路径歧义。
    root_path = Path(root).expanduser().resolve()

    # 用户输入只作为根目录下的候选片段，不直接作为最终文件名。
    candidate = (root_path / user_value).resolve()

    # 解析后再判断，才能把 .. 和已存在的符号链接纳入边界判断。
    if not candidate.is_relative_to(root_path):
        raise ValueError("path escapes the configured root")

    # 返回受控目录内的路径，读写动作由上层按业务权限执行。
    return candidate

这里的关键不是函数名，而是顺序：固定根目录、组合输入、解析候选、判断归属。resolve() 默认使用非严格模式，目标文件尚不存在时也能得到一个可比较的路径；但它仍然不代表文件已经打开，更不代表后续写入具备原子性。

为什么不能只判断原始字符串

最直观的错误是检查字符串是否以 root 开头。这种判断既会受到路径分隔符影响，也没有处理 ..、不同锚点和符号链接。另一个容易混淆的点是 PurePath.is_relative_to()：官方文档明确说明它是基于字符串的判断，不访问文件系统，也不会把 .. 当成特殊跳转处理。

所以，如果你还没有解析候选路径，直接对 PurePath 做边界判断，得到的只是词法关系，不是最终文件系统位置的判断。对需要访问实际文件的接口，应优先使用 Path.resolve() 后再判断。

再补上业务层的输入限制

通过根目录边界检查，只能回答“路径是否越界”。下载、解压或上传接口通常还需要回答“它是不是一个合适的目标”。例如可以拒绝空输入、拒绝目录、限制后缀，或者只允许一个文件名而不是任意多级目录。

from pathlib import Path

ALLOWED_SUFFIXES = {".pdf", ".txt", ".csv"}

def safe_download_path(root: str | Path, user_value: str) -> Path:
    # 空字符串没有明确的下载目标，避免把根目录当成文件返回。
    if not user_value.strip():
        raise ValueError("empty path is not allowed")

    target = safe_join(root, user_value)

    # 目录不是本接口的下载对象；后缀限制是业务规则，不是 pathlib 的职责。
    if target.is_dir():
        raise ValueError("directory is not a downloadable file")
    if target.suffix.lower() not in ALLOWED_SUFFIXES:
        raise ValueError("file type is not allowed")

    # 只有边界和业务规则都通过，才把路径交给后续读取逻辑。
    return target

后缀检查不能代替内容类型判断，is_dir() 也不能代替权限控制。它们只是让接口的意图更窄，减少把任意路径交给后续代码的机会。

pathlib 检查的安全边界在哪里

resolve() 加 is_relative_to() 适合解决“候选路径是否落在固定目录内”这个问题，但它不是一个完整的文件系统沙箱。检查和打开之间如果存在可被攻击者改变的符号链接，仍然要考虑竞态；不同操作系统对权限、链接和特殊文件的处理也不完全相同。

低风险的内部工具可以把上面的辅助函数作为清晰的边界层。对公开上传、解压和写文件接口，我会继续做三件事：服务端生成最终文件名，使用最小权限目录，并在真正打开文件时采用平台适合的防符号链接和原子创建策略。不要把用户输入拼接后直接传给任意文件操作，也不要把“检查通过”写成“绝对安全”。

一个可复用的判断清单

常见追问

relative_to() 能代替 is_relative_to() 吗？

可以用异常来表达“不在子路径内”，但如果只是判断归属，is_relative_to() 更直接。需要得到相对路径结果时再调用 relative_to()，并保留对 ValueError 的处理。

为什么不先删除用户输入里的 ..？

手工删除路径片段容易遗漏不同平台的分隔符、绝对路径锚点和符号链接语义。让 pathlib 解析候选路径，再对解析结果做边界判断，更容易把规则集中在一个地方。

检查到路径不存在时怎么办？

非严格的 resolve() 可以为尚不存在的目标生成可比较路径；随后是否允许创建，要由业务权限、父目录权限和原子创建策略决定。

我的结论是：root / user_value 负责组合，resolve() 负责把候选路径化为可比较的真实位置，is_relative_to() 负责判断是否仍在受控根目录。把三者放在一个边界函数里，再把文件打开和权限控制留在更低层，代码既清楚，也不容易把路径检查夸大成完整安全方案。