Go fs.Sub 如何控制资源根

如果一个 fs.FS 里同时放着模板、静态资源和迁移文件，调用方不应该到处拼接 assets/ 前缀。fs.Sub 的作用就是把某个目录映射成新的资源根：创建子 FS 后，调用 Open("css/app.css") 实际访问的是原 FS 的 assets/css/app.css。它改变的是调用方看到的路径命名空间，不是把文件复制到另一个目录。

先把目录映射成调用方的资源根

最小用法是传入一个实现 fs.FS 的文件系统和一个合法目录名。下面的示例使用内存 FS 表达一个真实项目常见的目录布局；代码本身是调用示意，重点在路径从 assets/css/app.css 变成 css/app.css。

package main

import (
    "fmt"
    "io/fs"
    "testing/fstest"
)

func main() {
    // 用内存文件系统表达应用资源，避免调用方依赖宿主机路径。
    all := fstest.MapFS{
        "assets/css/app.css": {Data: []byte("body { color: #234; }")},
        "assets/logo.svg":    {Data: []byte("")},
        "migrations/001.sql": {Data: []byte("create table demo(id integer);")},
    }

    // 把 assets 映射为新的资源根；子 FS 中不再携带 assets 前缀。
    assets, err := fs.Sub(all, "assets")
    if err != nil {
        panic(err) // 目录参数非法时在这里直接暴露配置错误。
    }

    data, err := fs.ReadFile(assets, "css/app.css")
    if err != nil {
        panic(err) // 文件不存在等问题要用子 FS 的相对路径排查。
    }
    fmt.Println(string(data))
}

这里的 assets 变量仍然只是一个 fs.FS。它不保证底层数据已经被读取，也不会提前检查 assets 是否存在；真正调用 ReadFile、Open 或 ReadDir 时，底层 FS 才会返回对应的错误。

资源根的路径必须遵守 fs.ValidPath

io/fs 使用跨平台的 slash-separated 路径。根目录用 . 表示，不能把操作系统绝对路径、反斜杠路径或包含 .. 的路径直接交给 fs.Sub。这些限制保证了不同 FS 实现对路径的理解一致。

排查错误时不要只比较字符串。fs.Sub 会把非法目录包装为 PathError{Op: "sub", Path: dir, Err: fs.ErrInvalid}，因此可以保留结构化判断：

func subAssets(fsys fs.FS, dir string) (fs.FS, error) {
    // 用 errors.Is 区分路径格式错误，避免依赖平台或版本的错误文本。
    child, err := fs.Sub(fsys, dir)
    if err != nil {
        if errors.Is(err, fs.ErrInvalid) {
            return nil, fmt.Errorf("资源根 %q 不是合法 fs 路径: %w", dir, err)
        }
        return nil, err
    }
    return child, nil
}

上面的片段需要在文件导入区加入 errors 和 fmt。示例的边界在于：路径格式由 fs.Sub 先判断，目录存在性由后续 FS 操作判断，两者不要混成一个结论。

底层 FS 是否实现 SubFS，会影响实现方式

如果底层实现了 fs.SubFS，标准库会调用它自己的 Sub(dir)；否则就返回一个包装层，把子 FS 的名称拼到原 FS 的目录前。对调用方来说，ReadDir、ReadFile、ReadLink、Lstat 和 Glob 都应当继续使用子 FS 的相对路径。

这也是 API 设计上的取舍：业务层只依赖最小的 fs.FS，底层可以根据存储介质提供专门实现或优化，而不会迫使业务层知道它来自 embed.FS、内存 FS 还是磁盘。若错误从底层返回，包装实现还会把路径缩短回子 FS 视角，日志中更容易定位调用方真正传入的名字。

fs.Sub 不是目录沙箱

最容易误用的地方是把“资源根”理解成“安全根”。官方文档明确说明，fs.Sub(os.DirFS("/"), "prefix") 与 os.DirFS("/prefix") 等价，但 os.DirFS 不会检查 prefix 内指向其他目录的符号链接，所以这两种写法都不是 chroot 式安全机制。

因此可以按目标选择：

• 只想让模板、静态文件或嵌入资源使用简短路径：用 fs.Sub。
• 需要把宿主目录包装成相对路径 FS：可以从 os.DirFS 开始，但要单独评估符号链接语义。
• 要求访问严格限制在某棵操作系统目录树内：使用文档建议的 os.Root 能力，不要用 fs.Sub 冒充隔离。

常见问题

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

不会。只要目录参数是合法的 FS 路径，就可以先得到子 FS；目录不存在通常在后续打开或读取时体现为 fs.ErrNotExist。

传入 . 会得到一个副本吗？

不会。标准实现直接返回原来的 fsys，因此它是“保持当前资源根”的快捷写法。

子 FS 能不能访问 ../？

不能把 .. 作为合法 FS 路径元素使用。Open 等操作应拒绝这类名称；如果需求是安全限制宿主目录，仍需使用专门的目录约束能力。

把 fs.Sub 当成命名空间适配器，边界就很清楚：它让调用方从某个目录开始工作，保持 FS 接口和相对路径语义；它不复制资源，也不承担操作系统级的目录隔离。