Python pathlib.Path.relative_to 的 walk_up 边界：如何判断路径是否真的在目录内

处理用户上传目录时，最容易误判的一件事是：Path.relative_to() 能算出相对路径，就以为目标文件一定在目录里面。Python 3.12 的 walk_up=True 反而把这个边界暴露得更清楚——它可以返回带 .. 的路径，但不负责替你做目录权限判断。

walk_up=False 适合确认“目标是否以目录为前缀”；walk_up=True 适合计算跨目录的相对地址。要判断用户路径是否真的落在根目录内，应先 resolve()，再使用默认模式检查结果，并单独考虑符号链接。

先把“相对路径”和“目录内”分成两个问题

假设服务把文件放在 /srv/app/uploads，用户传入的是一个已经拼好的目标路径。下面这段代码只是在比较两个路径的组成部分：

from pathlib import Path

root = Path("/srv/app/uploads")
target = Path("/srv/app/cache/report.csv")

print(target.relative_to(root, walk_up=True))
# ../cache/report.csv

结果是一个合法的相对路径，但它明确包含了 ..。这说明目标和根目录不在同一棵子树里，不说明目标“可以被安全读取”。如果把 walk_up 省略，默认值是 False，会直接抛出 ValueError。

用 walk_up=True 看清 .. 是怎样产生的

walk_up=True 的用途更接近 os.path.relpath()：当目标不在 other 的子路径中时，允许先向上走，再向下走。它对跨盘符、绝对路径与相对路径混用等情况仍可能抛出 ValueError。

from pathlib import PurePosixPath

target = PurePosixPath("/srv/app/cache/report.csv")
root = PurePosixPath("/srv/app/uploads")

try:
    inside = target.relative_to(root)
except ValueError:
    inside = None

outside = target.relative_to(root, walk_up=True)
print(inside)   # None
print(outside)  # ../cache/report.csv

这两个调用的结果分别服务于不同目的：第一个回答“是否是子路径”，第二个回答“怎样从根目录走到目标”。上传目录校验应采用前者的失败分支，而不是把后者的字符串继续交给文件打开函数。

resolve 之后再做目录内判断

路径中还可能出现符号链接。比如 /srv/app/uploads/current 指向了目录树外，单看字符串前缀很容易放行。更稳妥的做法是先解析根目录和目标，再用默认的 relative_to 判断解析后的目标是否仍在根目录下：

from pathlib import Path

def is_inside(root: Path, target: Path) -> bool:
    root_real = root.resolve()
    target_real = target.resolve()
    try:
        target_real.relative_to(root_real)
    except ValueError:
        return False
    return True

root = Path("/srv/app/uploads")
candidate = root / "current" / "report.csv"
if not is_inside(root, candidate):
    raise ValueError("target is outside uploads")

这里的关键不是函数名，而是顺序：resolve() 先把 .. 和可解析的符号链接折叠，再由默认 relative_to() 把越界路径送进异常分支。函数只返回一个路径关系判断，真正读取文件时仍需要权限控制、文件类型检查和并发场景下的安全设计。

三个常见写法为什么不等价

尤其不要用字符串的 startswith() 代替路径比较。/srv/app/uploads-old 以 /srv/app/uploads 开头，却不是它的子目录；Windows 下盘符和大小写规则也让这种比较更不可靠。

测试越界、符号链接和版本边界

回归测试至少要覆盖同目录、子目录、显式 ..、符号链接和不同根路径。测试断言应验证“是否放行”，不要只断言 walk_up=True 返回了什么字符串：

def test_outside_is_rejected(tmp_path):
    root = tmp_path / "uploads"
    root.mkdir()
    outside = tmp_path / "secret.txt"
    outside.write_text("private", encoding="utf-8")

    assert not is_inside(root, outside)
    assert not is_inside(root, root / ".." / "secret.txt")

walk_up 是 Python 3.12 加入的参数；如果项目仍支持更早版本，不能直接把这个关键字参数下发到旧解释器。可以在兼容层中保留默认 relative_to(root) 的判断逻辑，把跨目录相对地址计算放到版本明确的代码路径中。

相关问题

relative_to() 会检查文件是否存在吗？

不会。它属于 PurePath 的路径计算能力，不会访问底层文件系统；是否存在应由 exists() 等单独检查。

walk_up=True 能防止路径穿越吗？

不能。它只是允许结果包含 ..，安全判断应在 resolve() 后使用默认 relative_to()。

为什么要同时 resolve 根目录和目标？

只解析目标或只解析根目录，都可能让符号链接关系比较失真。两者使用同一解析规则后，再比较路径关系更容易得到一致结论。

把判断留在路径层，把读取留在权限层

relative_to() 最有价值的地方，是把“子路径”和“跨目录相对地址”这两个常被混用的动作拆开。需要目录内约束时，使用 resolve() 加默认模式的 relative_to()；需要展示或计算跨目录地址时，再考虑 walk_up=True。最后的文件读取仍应配合最小权限、符号链接策略和实际部署平台做验收。