Go url.JoinPath 怎么避免路径穿越：斜杠归一化与用户输入边界

下载接口通常会把固定入口、租户标识和文件名拼成一个 URL。问题往往不在“斜杠少写了一个”，而在于把用户输入误当成了已经分好段的路径：reports/2026 可能变成两级目录，../ 也可能把请求带出原本的业务范围。url.JoinPath 能把 URL 拼得规整，却不能替应用判断这个文件是否属于当前租户。

JoinPath 解决的是 URL 路径连接和清理；用户输入要先明确“一个 segment 还是多个 segment”，再做业务根目录校验，不能只靠清理 ../ 当安全检查。

先分清：输入是一个 URL 段，还是一条路径

这是最容易被忽略的判断。若参数代表“一个文件名”，reports/2026.csv 里的斜杠就是数据，不应被解释成路径分隔符；若参数代表用户选择的目录层级，那它才是多个 segment，应用必须逐段校验，而不是把整串字符串直接交给拼接函数。

官方文档要求 JoinPath 的 path elements 已经是 escaped 形式。对应的最小写法如下：

package main

import (
    "fmt"
    "net/url"
)

func main() {
    base := "https://download.example.test/tenant/acme/files"
    name := "reports/2026.csv"

    u, err := url.JoinPath(base, url.PathEscape(name))
    if err != nil {
        panic(err)
    }
    fmt.Println(u)
    // https://download.example.test/tenant/acme/files/reports%2F2026.csv
}

这里的重点不是输出看起来更“安全”，而是保住了数据的单段语义。不要对已经拼好的整条 URL 再随意 PathEscape，那会把协议、冒号和斜杠一起当成数据。

攻击路径不在清理动作，而在业务根边界

假设业务允许的根是 /tenant/acme/files，调用 url.JoinPath(base, "../other-tenant/secret.csv") 后，结果会被清理成根目录上层的路径。它是一个规范的 URL，却不代表它是当前租户可访问的资源。把“规范化成功”当成“授权成功”，就是这里的误判。

更稳妥的做法是把输入分成两种入口：单段文件名走 PathEscape；多段相对路径则逐段拒绝空段、.、.. 和编码后仍会产生分隔含义的输入。最终生成 URL 前，再对业务相对路径做根边界判断。

import "strings"

func safeFileURL(base, fileName string) (string, error) {
    if fileName == "" || fileName == "." || fileName == ".." {
        return "", fmt.Errorf("invalid file name")
    }
    if strings.ContainsAny(fileName, "/\\") {
        return "", fmt.Errorf("file name must be one segment")
    }

    escaped := url.PathEscape(fileName)
    return url.JoinPath(base, escaped)
}

如果产品确实需要目录层级，不要把上面的单段函数改成“放宽所有字符”。应先按 / 分段，逐段做白名单和点段检查，再用已转义的 segment 重新连接。文件系统访问还要使用对应的文件系统根目录校验；URL 校验和磁盘路径校验是两道不同的边界。

把风险分成三档，测试才不会漏掉关键输入

测试时不要只断言字符串里没有 ..。更有价值的断言是：生成的资源仍属于当前租户、单段文件名不会变成目录、拒绝结果不会继续触发存储层读取。HTTP 服务还应核对路由层是否已经解码过一次，避免应用层和网关层各做一套不同的判断。

上线前的验证清单

• 确认每个参数的语义：文件名单段、目录多段，还是完整 URL。
• 确认 PathEscape 只作用于单个 path segment，未对整条 URL 误编码。
• 用 ../、重复斜杠、编码斜杠、反斜杠、空值和跨租户 ID 做回归测试。
• 把 URL 路径边界、文件系统根边界和权限检查分别记录，任何一层失败都停止读取。

常见问题

url.JoinPath 会自动阻止路径穿越吗？

不会。它会清理点段并连接 URL，但不了解你的租户根、资源权限和存储系统，业务边界仍需单独判断。

文件名里允许斜杠时还能用 PathEscape 吗？

可以，但要先确认斜杠是文件名数据还是目录语义。作为单个文件名时应转义；作为目录层级时应分段校验后逐段转义。

为什么不能只检查最终 URL 是否以 base 开头？

简单字符串前缀容易把相似目录误判为同一根，例如允许根和允许根的同名前缀。应按解析后的路径段比较边界，并结合权限与文件系统根检查。

PathEscape 和 QueryEscape 能互换吗？

不能。PathEscape 面向 URL 路径段，QueryEscape 面向查询参数；两者对斜杠、加号和空格的处理语义不同。

把拼接函数放回它该负责的位置

处理用户输入时，先决定数据模型，再选择转义方式；生成 URL 后，仍要检查它是否落在允许的业务范围。这样既能避免文件名斜杠改变层级，也不会把一个格式化函数误当成完整的安全策略。