Go io/fs.Sub 如何裁剪嵌入目录：fs.ValidPath 与路径错误的排查

把模板和静态资源放进 embed.FS 后，常见的下一步不是把整个文件树暴露出去，而是先用 io/fs.Sub 裁出 web 子目录。问题通常出在路径写成了 /index.html、web/../secret，或者把 Sub 的目录不存在误认为创建失败。正确做法是让 Sub 负责缩小视野，让每次 Open 只接收符合 fs.ValidPath 的相对路径，再根据 *fs.PathError 区分输入错误和文件不存在。

fs.Sub 只裁剪一个文件系统视图，不会替你创建目录或提供 chroot 隔离；目录参数与后续 Open 名称都必须遵守 io/fs 的相对路径规则。

把嵌入资源缩小成一个可控子树

假设项目里有 assets/web/index.html 和 assets/web/app.js。完整文件系统可以读取这两个文件，但业务层只需要看到 web 下面的内容：

package main

import (
    "embed"
    "fmt"
    "io/fs"
)

//go:embed assets/web/*
var siteFS embed.FS

func main() {
    webFS, err := fs.Sub(siteFS, "assets/web")
    if err != nil {
        panic(err)
    }

    f, err := webFS.Open("index.html")
    if err != nil {
        panic(err)
    }
    defer f.Close()
    fmt.Println(f.Name())
}

这里的调用链是 fs.Sub 先把 assets/web 变成新视图，随后 Open("index.html") 才在这个视图内查找文件。不要写成 webFS.Open("assets/web/index.html")，那会把前缀重复一遍。

先搞清楚 Sub 的目录边界

fs.Sub 的第二个参数是原文件系统里的目录名，不是操作系统绝对路径。传入 "." 时，函数直接返回原来的文件系统；传入 "assets/web" 时，新的 webFS 把它视为根。

还有一个容易被忽略的点：Sub 不保证目录当前存在。也就是说，目录名格式合法并不等于里面已经有文件，真正访问时仍可能收到 ErrNotExist。因此初始化阶段可以创建视图，业务第一次读取时再做存在性检查。

用 fs.ValidPath 拦住错误路径

io/fs 的路径是统一的斜杠分隔格式，即使程序运行在 Windows 上也一样。根目录用 . 表示；index.html 和 css/site.css 合法，而 /index.html、css//site.css、css/../secret 都不应作为 Open 名称。

func openAsset(webFS fs.FS, name string) (fs.File, error) {
    if !fs.ValidPath(name) {
        return nil, fmt.Errorf("invalid asset path %q", name)
    }
    return webFS.Open(name)
}

这层校验的价值不只是让报错更早：它把用户输入与文件系统实现之间的边界固定下来。对于来自 URL 的路径，还应先完成 URL 解码、去掉查询参数，再把最终相对路径交给 fs.ValidPath；不要用 filepath.Clean 代替这条规则，因为 io/fs 的路径语义与操作系统路径不是一回事。

从 PathError 判断到底坏在哪里

读取失败时，优先保留原始错误，不要只打印一条“资源不存在”。标准实现通常会返回 *fs.PathError，它包含操作名、出错路径和底层原因：

f, err := openAsset(webFS, requested)
if err != nil {
    var pathErr *fs.PathError
    if errors.As(err, &pathErr) {
        switch {
        case errors.Is(pathErr.Err, fs.ErrInvalid):
            return fmt.Errorf("bad asset name %q", pathErr.Path)
        case errors.Is(pathErr.Err, fs.ErrNotExist):
            return fmt.Errorf("asset missing: %q", pathErr.Path)
        }
    }
    return err
}
defer f.Close()

ErrInvalid 更像调用方把路径格式传错了，应该修正输入；ErrNotExist 则表示路径格式可能没问题，但对应文件或目录不在当前视图中。两者混成 404 会让定位变慢，尤其是部署后资源前缀写重复时。

上线前的最小验收清单

• 用 fs.Sub(siteFS, "assets/web") 创建视图后，测试 Open("index.html")，不要再次拼接 assets/web/。
• 分别测试 "."、"index.html"、"/index.html"、"css/../secret"，确认 fs.ValidPath 的边界符合预期。
• 人为删除一个嵌入资源，观察 *fs.PathError 的 Op、Path 和 Err，确保日志能区分 ErrInvalid 与 ErrNotExist。
• 如果底层是 os.DirFS，不要把 Sub 当成 chroot；官方文档明确提醒符号链接仍可能指向根目录之外。

相关问题

fs.Sub 会检查子目录是否存在吗？

不会。它先返回一个子树视图，访问具体文件时才暴露不存在或不可读的问题。

为什么 Open 不能使用绝对路径？

fs.FS 的接口约定使用无根、斜杠分隔的路径名，这样不同文件系统实现才能共享同一套边界。

fs.Sub 能替代目录沙箱吗？

不能。对 os.DirFS 来说，符号链接安全边界仍需单独设计；如果目标是限制操作系统目录树，应使用更合适的目录约束机制。

小结

把 fs.Sub、fs.ValidPath 和 fs.PathError 分成三个职责，路径问题就不会全挤在一次 Open 失败里：Sub 负责裁剪视图，ValidPath 负责输入边界，PathError 负责告诉你是格式错还是资源缺失。这个拆分足够小，也适合直接写成单元测试。