Go fs.Sub 暴露子目录并保持路径安全

fs.Sub 的价值不是简单拼接目录名，而是把一个 fs.FS 的指定子目录重新定义为调用方看到的根。这样业务代码只接触子树内的相对路径，底层目录前缀被集中封装。需要注意：它能维护 io/fs 的逻辑路径边界，却不是 chroot；底层是本地磁盘且存在不可信符号链接时，应使用 os.Root。

官方文档：https://pkg.go.dev/io/fs#Sub；路径规则：https://pkg.go.dev/io/fs#ValidPath。

背景：为什么要给文件系统重新定根

我第一次把嵌入资源交给多个模块时，调用点到处都是 static/css/app.css、static/templates/index.html。这能运行，却让每个调用方都知道资源在包里的内部布局。目录一改，读取代码、测试和 HTTP 层一起修改。

更麻烦的是，调用方很容易把操作系统路径习惯带进 io/fs：有人传入 /static/app.css，有人用反斜杠，还有人先 path.Clean 再访问。结果是“路径整理”与“访问授权”混在了一起。

旧写法的问题：前缀拼接不是清晰边界

func loadAsset(fsys fs.FS, name string) ([]byte, error) {
    // 每个调用点都知道 static 前缀，目录结构被泄露到业务层。
    return fs.ReadFile(fsys, path.Join("static", name))
}

这类代码有两个隐患。第一，path.Join 会规范化输入，调用方传入的点元素或父目录元素可能被折叠，原本应该拒绝的路径变成另一个合法名字。第二，多个模块各自拼接前缀，无法保证大家采用同一套检查规则。

问题的核心不是 path.Join 本身不安全，而是它不应该承担访问控制。授权边界应在创建文件系统视图时确定，外部名字则按 io/fs 规则直接校验。

新规则：子目录成为调用方的新根

fs.Sub(fsys, "static") 返回一个新的 fs.FS。在这个视图里，底层的 static/css/app.css 变成 css/app.css。如果底层实现了 fs.SubFS，标准库会调用它的 Sub；否则会创建包装实现，把子树内路径映射回原文件系统。

package assets

import (
    "embed"
    "io/fs"
)

//go:embed static
var embedded embed.FS

func Public() (fs.FS, error) {
    // 把 static 映射为新根，调用方不再感知内部目录前缀。
    return fs.Sub(embedded, "static")
}

fs.Sub 不要求目录在调用时一定存在，但实际打开文件时仍会返回底层错误。创建子树视图的错误也不能忽略，因为 dir 必须符合 fs.ValidPath；"." 是特殊根路径，传入它会原样返回底层文件系统。

代码对比：外部路径要拒绝，不要清洗后继续

io/fs 的路径在所有平台都使用斜杠，必须是 UTF-8、非绝对路径，不能以斜杠开头或结尾，也不能包含空元素、. 或 .. 元素。根目录只有一个特殊名字 "."。

package assets

import (
    "fmt"
    "io/fs"
)

func ReadPublic(public fs.FS, name string) ([]byte, error) {
    // 对外部名字采用拒绝式校验，不先 Clean，也不接受绝对路径。
    if name == "." || !fs.ValidPath(name) {
        return nil, fmt.Errorf("invalid public asset path: %w", fs.ErrInvalid)
    }

    // name 相对于 fs.Sub 返回的新根，例如 css/app.css。
    return fs.ReadFile(public, name)
}

这里显式调用 fs.ValidPath 是为了在入口给出稳定的业务错误；合规的 fs.FS 实现本来也应拒绝无效路径。不要把 ../secret.txt 清洗为 secret.txt 后继续读取，因为这会把恶意或错误输入悄悄变成另一项授权请求。

兼容注意：fs.Sub 不是 chroot

对 embed.FS，内容在构建时固定，fs.Sub 很适合收窄公开视图。对 os.DirFS，情况不同：fs.Sub(os.DirFS("/srv/app"), "public") 在逻辑上等价于以 /srv/app/public 为根，但不能阻止该目录里的符号链接指向外部位置。

因此要把两个威胁模型分开：

• 调用方可能传入恶意路径字符串：使用 fs.ValidPath，并在预先建立的子树视图中访问。
• 攻击者还能修改本地目录或符号链接：fs.Sub 不够，应使用 Go 1.24 引入的 os.Root 或 os.OpenInRoot，让访问不能通过相对元素或符号链接逃出根目录。
• 只是构建期嵌入资源：embed.FS + fs.Sub 通常已经提供清晰、可测试的逻辑边界。

采用建议：按真实文件来源选择工具

我更愿意把 fs.Sub 看成“能力收窄器”：它让调用方只能以子树为根描述资源，也让测试可以替换任何兼容的 fs.FS。但它不承诺操作系统级隔离。只要记住“逻辑路径边界归 fs.Sub，磁盘遍历边界归 os.Root”，这套 API 的职责就不会混淆。

相关问题

fs.Sub 会立即检查目录存在吗？

不会。官方文档明确说明它不检查目录当前是否存在，实际打开、读取或遍历时才会从底层文件系统得到对应错误。

Windows 下能给 io/fs 传反斜杠吗？

io/fs 在所有平台都以斜杠分隔。反斜杠和冒号可以作为普通字符出现在合法名字中，但文件系统实现不能把它们解释为路径分隔符。

可以用 path.Clean 代替 fs.ValidPath 吗？

不建议。path.Clean 会改写输入，而 fs.ValidPath 用于判断原始名字能否交给 FS.Open。安全入口更应该拒绝越界意图，而不是把它转换成另一个路径。