Go filepath.Clean 为什么不能代替路径权限检查

接收用户文件名时，先调用 filepath.Clean 是好习惯，但它不能回答“这个请求是否允许访问该目录”。Clean 只在字符串层面消除重复分隔符、. 和部分 ..；它不读取磁盘、不检查 Unix 权限，也不知道某个目录是不是符号链接。真正的根目录约束，至少还要做相对路径限制和边界比较。

filepath.Clean 做的是词法整理，不是权限判断

把 uploads/../config/app.yaml 规范化为 config/app.yaml，只是得到一个更短的等价路径名。Go 官方文档把 Clean 定义为 purely lexical processing：它处理的是字符和路径元素，不会因为路径看起来干净就授予调用者访问权限。

因此，下面两个问题要分开问：第一，输入是否是合法的相对路径；第二，拼接后的目标是否位于业务允许的根目录。前者是输入约束，后者才是目录边界判断。即使两者都通过，最后的 os.Open 仍可能因为文件不存在、进程权限不足或磁盘错误而失败。

先拒绝绝对路径，再检查根目录边界

用户输入应当被当作“根目录下面的相对名字”，而不是一个可以替换根目录的完整路径。较新的 Go 可以先使用 filepath.IsLocal；为了让边界判断更直观，再用 filepath.Rel 检查结果是否以父目录开头。

package filesafe

import (
    "errors"
    "path/filepath"
    "strings"
)

// ResolveUnder 只返回词法上位于 root 内的目标路径。
func ResolveUnder(root, userPath string) (string, error) {
    // 绝对路径会绕过业务根目录；空路径也不应默认为当前目录。
    if userPath == "" || filepath.IsAbs(userPath) {
        return "", errors.New("只接受非空相对路径")
    }
    // IsLocal 会拒绝词法上的 .. 越界；Windows 保留名也会被处理。
    if !filepath.IsLocal(userPath) {
        return "", errors.New("路径不是安全的本地相对路径")
    }

    cleanRoot, err := filepath.Abs(root)
    if err != nil {
        return "", err
    }
    target := filepath.Join(cleanRoot, userPath)
    rel, err := filepath.Rel(cleanRoot, target)
    if err != nil {
        return "", err
    }
    // Rel 以 .. 开头时，目标已经落在根目录之外。
    if rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
        return "", errors.New("路径超出允许根目录")
    }
    return target, nil
}

这里的 Rel 检查不是多余的装饰：它把“是否越过边界”变成了一个明确的相对路径问题。实际项目里还应把这个函数放在上传、下载、删除等入口之前，避免某个新接口忘记复用校验。

把安全路径解析封装成单一入口

常见错误是先 Join(root, Clean(userPath))，随后直接打开结果。这样做只完成了规范化和拼接，没有留下“目标必须在 root 内”的判断。更稳妥的调用方式是：解析函数返回错误就停止，返回成功的绝对路径后才交给文件 API。

func ReadUpload(root, name string) ([]byte, error) {
    path, err := ResolveUnder(root, name)
    if err != nil {
        return nil, err
    }
    // Open 仍会执行真实文件系统检查，词法校验不能替代它。
    return os.ReadFile(path)
}

上面的示例还需要导入 os。生产代码应继续设置文件大小上限、记录拒绝原因并区分“路径越界”和“文件不存在”，但不要把错误信息直接回显为服务器绝对路径。

符号链接会让词法检查仍然不够

词法上位于 /srv/uploads 的 reports/latest.txt，真实文件系统中可能通过符号链接指向另一个目录。IsLocal 和 Rel 都只看路径文本，不会替你解析这个链接；这正是“Clean 通过了”仍不能等价于“访问被限制”的原因。

当目标已存在、且业务确实需要核对真实位置时，可以分别对允许根目录和目标调用 filepath.EvalSymlinks，再对解析后的路径做 Rel 比较：

func ExistingUnder(root, name string) (string, error) {
    lexical, err := ResolveUnder(root, name)
    if err != nil {
        return "", err
    }
    realRoot, err := filepath.EvalSymlinks(root)
    if err != nil {
        return "", err
    }
    realTarget, err := filepath.EvalSymlinks(lexical)
    if err != nil {
        return "", err
    }
    rel, err := filepath.Rel(realRoot, realTarget)
    if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
        return "", errors.New("解析后的目标超出根目录")
    }
    // 返回解析后的路径，后续读取使用同一个目标。
    return realTarget, nil
}

这段方式适合检查已有文件；上传到新文件时，目标文件还不存在，应解析父目录并控制创建过程，不能简单地对不存在的最终路径调用 EvalSymlinks。如果目录可被其他进程同时改写，还要考虑检查与打开之间的竞态，必要时使用操作系统提供的目录句柄、禁止跟随链接的打开选项或更封闭的文件服务设计。

用检查清单选择正确的防护层

• 只想统一分隔符、去掉 .：使用 filepath.Clean。
• 只接受根目录下的用户相对路径：拒绝空值和绝对路径，再用 IsLocal 或 Rel 做词法边界检查。
• 目标可能是已有符号链接：解析根目录和目标，再比较真实路径。
• 目录可被不可信主体修改：不要把词法检查当成竞态防护，改用更严格的文件系统级打开策略。
• 操作系统权限与业务授权：分别处理；路径在 root 内不等于 Unix 用户、租户或角色拥有业务权限。

记住一句话就够了：Clean 让路径更规整，Rel 帮你判断词法边界，真正的文件系统和业务授权仍需要单独检查。把三层责任写在不同函数里，后续排查会比在一个字符串表达式里反复追加 Clean 更可靠。

相关问题

调用 filepath.Clean 后还需要 filepath.Join 吗？

需要先明确根目录和相对路径的关系。Join 会对结果做清理，但它不会自动替你完成业务根目录授权，所以仍要配合边界判断。

filepath.IsLocal 能完全防住符号链接吗？

不能。官方文档明确它是词法操作，不考虑文件系统中的符号链接；已有文件要按场景解析真实目标。

路径在允许目录内，为什么 os.ReadFile 仍会失败？

路径边界只说明目标位置符合业务规则，文件不存在、进程权限不足、挂载异常和 I/O 错误仍由实际打开操作返回。