Go fs.Sub 怎样把嵌入目录映射成独立的 fs.FS

需要把 embed.FS 里的 assets 或 web 目录交给模板渲染器、静态文件服务或其他只接受 fs.FS 的组件时，直接传整个文件树往往会让调用方暴露多余路径。fs.Sub 的做法是生成一个以指定目录为根的子文件系统：子 FS 里的 css/app.css，实际读取的是原 FS 的 assets/css/app.css。

它只改变访问视图，不复制文件，也不会把宿主机目录变成安全沙箱。下面按路径映射、HTTP 接入和错误边界把这个用法拆开。

fs.Sub 的路径映射规则

fs.Sub 接收原始文件系统和一个符合 fs.ValidPath 的目录名，返回新的 fs.FS。目录参数使用斜杠分隔，不能写成操作系统路径里的 ../assets，也不应该把 filepath.Join 的结果直接当作 FS 路径。

最小读取示例可以把“前缀拼接”从业务代码中移走：

package main

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

//go:embed assets
var content embed.FS

func main() {
    // 让调用方只看到 assets 目录下的相对路径。
    assets, err := fs.Sub(content, "assets")
    if err != nil {
        panic(err)
    }

    // 这里的路径相对于子 FS，而不是相对于项目根目录。
    data, err := fs.ReadFile(assets, "config/app.yaml")
    if err != nil {
        panic(err)
    }
    fmt.Println(len(data))
}

把嵌入目录接入 HTTP 静态服务

当 URL 使用 /static/，而嵌入树内部使用 web/ 时，先用 fs.Sub 缩小文件视图，再用 http.FS 转成 HTTP 文件系统。StripPrefix 要和外部 URL 前缀保持一致，否则文件服务器会拿着 static/app.js 去子 FS 中查找，结果自然是 404。

package main

import (
    "embed"
    "io/fs"
    "net/http"
)

//go:embed web
var site embed.FS

func staticHandler() (http.Handler, error) {
    // 先把 web 设为子 FS 根，避免把 embed 前缀泄漏给 HTTP 层。
    webFS, err := fs.Sub(site, "web")
    if err != nil {
        return nil, err
    }
    // URL 的 /static/ 前缀剥掉后，剩余路径交给 webFS 查找。
    files := http.FileServer(http.FS(webFS))
    return http.StripPrefix("/static/", files), nil
}

这段组合的边界很清楚：浏览器请求 /static/app.js，处理器去子 FS 查找 app.js，最终落到嵌入树中的 web/app.js。如果项目还要提供模板，可以把同一个 webFS 传给模板加载逻辑，不必再次拼接 web/。

目录不存在与安全边界

fs.Sub 本身不会检查目标目录当前是否存在，因此构造返回成功不能证明目录可读。把它交给 fs.ReadDir、fs.ReadFile 或 FileServer 后，访问阶段才会出现 fs.ErrNotExist 或带路径信息的 *fs.PathError。启动阶段若必须快速失败，可以主动读取子根目录。

因此，资源打包场景可以把 fs.Sub 当成“路径视图适配器”；涉及不可信文件和强隔离时，要改用具备明确约束能力的目录 API，并单独评估符号链接、权限和部署目录。

常见问题

目录参数写成空字符串可以吗？

不能把空字符串当作通用根目录。需要原 FS 根时使用 "."；其他目录名应使用 slash 分隔的相对 FS 路径。

为什么 fs.Sub 成功但第一次读取失败？

因为它不检查目录是否存在。把启动自检写成 fs.ReadDir(sub, ".") 或读取一个必需文件即可把错误提前暴露。

StripPrefix 是 fs.Sub 的替代品吗？

不是。StripPrefix 只处理 HTTP URL，fs.Sub 处理文件树视图；静态服务通常需要两者配合。