Python pathlib.Path.resolve 如何阻止目录穿越：根目录校验、符号链接与拒绝路径

文件预览接口如果直接把用户传来的 filename 拼到上传目录后面，../ 和指向站外的符号链接就可能让读取范围越过预期目录。Python 的 pathlib.Path.resolve() 能先把路径绝对化、消除 .. 并解析符号链接，随后再用根目录边界判断决定允许还是拒绝。

安全边界不是“字符串里没有 ..”，而是解析后的目标路径必须仍位于固定根目录之内；对不存在的目标，还要按业务选择 strict=True 或 strict=False。

先把“用户文件名”变成可核对的路径

目录穿越的第一个误区，是在原始字符串上做黑名单判断。例如只拦截 ../，仍然可能漏掉不同分隔符、重复分隔符和符号链接。更稳妥的顺序是：固定根目录，拼接相对名称，调用 resolve()，最后比较解析结果。

from pathlib import Path

UPLOAD_ROOT = Path("/srv/uploads").resolve()

def resolve_upload(filename: str) -> Path:
    candidate = (UPLOAD_ROOT / filename).resolve(strict=True)
    try:
        candidate.relative_to(UPLOAD_ROOT)
    except ValueError as exc:
        raise PermissionError("path is outside upload root") from exc
    return candidate

print(resolve_upload("reports/2026-08.csv"))

这里的 UPLOAD_ROOT 在服务启动时确定，filename 只能作为它下面的相对部分。比如输入 reports/2026-08.csv 后，解析结果可以是 /srv/uploads/report.csv 这样的根目录内路径。relative_to() 成功说明候选路径可以表示成根目录下的相对路径；抛出 ValueError 则进入拒绝分支。

Path.resolve 如何处理 .. 与符号链接

假设 /srv/uploads 下有 preview 目录，用户输入 preview/../reports/2026-08.csv。解析后会得到规范化的绝对路径。更值得警惕的是：如果 preview 是指向 /etc 的符号链接，那么解析结果会直接落到根目录之外，边界判断就会拒绝它。

root = Path("/srv/uploads").resolve()

for raw_name in ("preview/../reports/2026-08.csv", "preview/passwd"):
    try:
        resolved = (root / raw_name).resolve(strict=True)
        resolved.relative_to(root)
    except (OSError, ValueError):
        print(raw_name, "-> 拒绝")
    else:
        print(raw_name, "-> 允许", resolved)

不要先判断字符串、再去打开文件；打开动作应使用已经通过边界校验的 resolved。这样“检查的路径”和“实际读取的路径”保持一致。对于需要创建的新文件，目标可能暂时不存在，可把 strict=False 作为解析策略，但仍要完成根目录比较。

现有文件与新文件，strict 参数怎么选

读取或下载已有文件

下载接口通常只接受已经存在的文件。此时使用 strict=True，文件不存在、权限不足或符号链接异常都会在解析阶段暴露，调用方可以统一返回 404 或拒绝响应。

准备保存一个还不存在的目标

上传场景可能先做路径规划再创建文件，strict=False 会尽可能解析已有部分，并保留不存在的尾部。它不是“放弃安全检查”，而是把“目标是否存在”和“目标是否越界”拆成两个判断：先做根目录边界检查，真正写入时再使用安全打开方式和独占创建。

三类容易漏掉的实现细节

• 不要动态改变根目录。根目录应来自服务配置或部署环境，不能由请求参数拼出来。
• 不要用 commonprefix 代替路径比较。/srv/uploads-old 可能与 /srv/uploads 共享字符串前缀，却不在同一目录树；需要使用路径语义比较。
• 不要把校验后的路径重新拼接。校验后直接使用 resolved，避免在中间环节再次混入未校验的字符串。

用最小测试覆盖允许与拒绝分支

def test_path_boundary(tmp_path):
    root = tmp_path / "uploads"
    root.mkdir()
    (root / "ok.txt").write_text("ok", encoding="utf-8")

    assert resolve_upload("ok.txt") == (root / "ok.txt").resolve()

    try:
        resolve_upload("../outside.txt")
    except (PermissionError, FileNotFoundError):
        pass
    else:
        raise AssertionError("outside path must be rejected")

测试至少要覆盖根目录内的正常文件、使用 .. 的越界输入、指向根目录外的符号链接，以及不存在目标的上传路径。只测一个正常文件，无法证明拒绝分支真的生效。

常见问题

只过滤 ../ 可以吗？

不建议。路径表达形式和符号链接会让字符串黑名单变得脆弱，应解析后按目录边界判断。

resolve(strict=False) 会不会失去安全性？

不会自动失去安全性，但它允许不存在的尾部保留；调用方仍必须比较解析路径与固定根目录，并在写入时做独占创建和权限控制。

为什么不用 os.path.commonprefix()？

commonprefix() 比较的是字符，不理解目录边界。使用 Path.relative_to() 或 os.path.commonpath() 更符合路径语义。

把边界判断留在文件打开之前

一个可靠的实现应把“固定根目录—解析路径—边界判断—实际读写”连成一条短链路。日志里可以记录拒绝原因和请求标识，但不要把用户输入直接回显到错误页面。只要根目录不由请求控制，解析后的路径不越界，且后续操作始终使用同一个已核验对象，目录穿越的主要入口就被压在文件打开之前。