Go filepath.Clean 后怎么避免把用户路径带出根目录

很多文件下载、解压和静态资源服务都会把用户传入的名称拼到一个固定目录下。只调用 filepath.Clean 并不能证明目标仍在这个目录里：它只是按词法整理路径，遇到以 .. 开头的相对路径时，filepath.Join 仍可能把结果带到根目录之外。

可靠的分工是：操作系统路径先用 filepath.IsLocal 判断，再做 Clean 和 Join；来自 io/fs 的斜杠路径先过 fs.ValidPath，再用 filepath.Localize 转成本地路径。符号链接攻击不属于这套词法检查的能力范围。

为什么 Clean 之后仍可能越过根目录

假设根目录是 /srv/uploads，输入是 ../../etc/passwd。filepath.Clean 会把多余部分整理成仍然带有父级含义的路径；随后直接 filepath.Join(root, cleaned)，得到的目标就可能不在 root 下。问题不在 Clean 做错了，而是“路径长得更规整”和“路径被授权留在某个目录内”是两件事。

因此不要用字符串前缀判断结果，例如 strings.HasPrefix(target, root) 会把 /srv/uploads-old 误认为位于 /srv/uploads 内。先判断输入是不是本地相对路径，再拼接，职责更清晰。

先 IsLocal，再 Clean 和 Join

filepath.IsLocal 是纯词法判断，要求路径非空、非绝对、不会从当前目录树逃逸；在 Windows 上还会拒绝类似 NUL 的保留名。通过后，官方文档保证把它交给 Join 不会越出 base，Clean 也不会保留 .. 路径元素。

package main

import (
    "errors"
    "path/filepath"
)

var errUnsafePath = errors.New("unsafe local path")

func joinLocal(root, name string) (string, error) {
    // 先拒绝绝对路径、空路径和词法上会越界的输入。
    if !filepath.IsLocal(name) {
        return "", errUnsafePath
    }

    cleaned := filepath.Clean(name)
    // 单独的 . 只代表根目录，按文件名输入场景拒绝它。
    if cleaned == "." {
        return "", errUnsafePath
    }

    // IsLocal 已经建立词法边界，这里只负责拼接并保持平台分隔符。
    return filepath.Join(root, cleaned), nil
}

这里的关键不是“再多调用一次 Clean”，而是把 IsLocal 放在输入边界。若业务允许用户明确选择任意绝对输出位置，就不要把它误当成受保护根目录场景；安全规则必须跟任务语义一致。

把 fs.ValidPath 交给跨平台本地路径

归档条目、嵌入式文件系统和 io/fs 接口使用的是统一的斜杠路径，即使运行在 Windows 上也一样。此时不要直接把名称当作 filepath 路径处理，而是先用 fs.ValidPath 判断格式，再用 filepath.Localize 转换。

package main

import (
    "errors"
    "io/fs"
    "path/filepath"
)

var errInvalidFSName = errors.New("invalid fs name")

func joinFSName(root, slashName string) (string, error) {
    // fs.ValidPath 约束的是斜杠分隔的虚拟名称，不是 Windows 路径。
    if slashName == "." || !fs.ValidPath(slashName) {
        return "", errInvalidFSName
    }

    // Localize 负责把 io/fs 名称转换为当前操作系统能表示的路径。
    localName, err := filepath.Localize(slashName)
    if err != nil || !filepath.IsLocal(localName) {
        return "", errInvalidFSName
    }

    // 根目录是可信配置，名称仍必须保持相对并落在根目录内。
    return filepath.Join(root, localName), nil
}

fs.ValidPath 接受的字符规则和操作系统路径不同：反斜杠、冒号在抽象 FS 名称中可以是普通字符，但实现不能擅自把它们当成分隔符。Localize 会在当前系统无法表达该名称时返回错误，这比手写 strings.ReplaceAll 更适合跨平台代码。

上线前检查三个边界

1. 输入边界：裸操作系统路径用 IsLocal；抽象文件名用 fs.ValidPath，不要把两种语义混在一个正则里。
2. 拼接边界：固定根目录和外部名称才适合 Join；不要先把外部名称变成绝对路径再拼接。
3. 文件系统边界：词法检查不解析符号链接，也不能阻止检查与打开之间的竞态。若攻击者能控制根目录内的文件系统，Go 1.24+ 应评估 os.OpenInRoot 或 os.Root。

记住一句话就够了：Clean 让路径更规整，IsLocal 让本地相对路径可控，ValidPath 和 Localize 让虚拟路径跨平台落地；真正的文件系统隔离还要使用具备相应语义的打开 API。

常见问题

为什么不用 filepath.IsAbs 判断就结束？

因为相对路径也可能以多个 .. 越出根目录，IsAbs 只能排除绝对路径。

fs.ValidPath 能阻止 Windows 的反斜杠穿越吗？

它只定义斜杠分隔的抽象名称。要落到本地文件系统，应让 Localize 按当前平台判断能否表示，再配合 IsLocal 和根目录策略。

filepath.Clean 会解析符号链接吗？

不会。它只做词法处理；涉及符号链接或竞态时，需要使用面向根目录的安全打开方案。