Go fs.Sub 怎么把嵌入目录作为独立根目录

如果 embed.FS 里同时放了模板、静态资源和迁移文件，业务代码往往不想一直写 assets/web/templates/index.html 这样的前缀。fs.Sub 可以从一个已有的 fs.FS 中截取子树，返回一个新的文件系统视图；对这个视图打开 index.html，实际读取的就是原始嵌入目录下的 assets/web/index.html。

最直接的方案是先用 //go:embed 得到 embed.FS，再调用 fs.Sub(content, "assets/web")。成功后把返回值交给 template.ParseFS、http.FS 或自己的读取函数；调用方只面对新的根目录，不再拼接 assets/web/ 前缀。

先把嵌入目录设计成清晰的文件树

假设项目把前端资源放在 assets/web，模板和其他资源并列保存。//go:embed 的模式相对于声明它的 Go 源文件所在目录解析，因此目录布局和声明位置要一起考虑。

package main

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

// content 保存程序发布时需要的只读资源树。
//go:embed assets
var content embed.FS

func main() {
    // 这里的根仍包含 assets/web，而不是 web。
    web, err := fs.Sub(content, "assets/web")
    if err != nil {
        // Sub 的目录参数必须是 io/fs 认可的相对路径。
        panic(err)
    }

    data, err := fs.ReadFile(web, "index.html")
    if err != nil {
        // 读取失败时保留原始错误，便于区分路径和资源问题。
        panic(err)
    }
    fmt.Println(len(data))
}

调用方看到的 web 已经以 assets/web 为根。此时再写 assets/web/index.html 会多拼一层目录，通常会得到 fs.ErrNotExist 对应的路径错误。

用 fs.Sub 把前缀从业务代码中移走

fs.Sub(fsys, dir) 返回以 dir 为根的文件系统视图。dir 为 . 时直接返回原文件系统；其他情况下，标准库会把子视图中的打开、读取目录、读取文件和 Glob 操作映射回原始文件系统。

func embeddedWebFS() (fs.FS, error) {
    // 业务层只关心 web 目录，不需要知道 embed.FS 的完整布局。
    web, err := fs.Sub(content, "assets/web")
    if err != nil {
        return nil, fmt.Errorf("创建 web 子文件系统: %w", err)
    }
    return web, nil
}

func readHome(fsys fs.FS) ([]byte, error) {
    // 子根目录下直接读取 index.html，避免重复拼接 assets/web。
    return fs.ReadFile(fsys, "index.html")
}

这里没有把 fs.Sub 当成复制或打包操作，它只是改变了寻址视角。对于实现了 fs.SubFS 的底层文件系统，标准库可以调用它自己的 Sub；否则会提供一个包装视图来完成路径映射。

接入模板和 HTTP 文件服务

子文件系统最有价值的地方，是能直接交给已经理解 fs.FS 的 API。模板解析时，模板文件名从新根开始；提供静态文件时，http.FS 负责把 URL 路径转换成 fs.FS 路径。

func buildHandler() (http.Handler, error) {
    web, err := fs.Sub(content, "assets/web")
    if err != nil {
        return nil, fmt.Errorf("准备静态资源: %w", err)
    }

    // StripPrefix 只处理 URL 外层前缀，http.FS 处理子根内部路径。
    handler := http.StripPrefix("/static/", http.FileServer(http.FS(web)))
    return handler, nil
}

func parsePage(web fs.FS) (*template.Template, error) {
    // 模板路径从 web 子根开始，不再写 assets/web/page.html。
    return template.ParseFS(web, "templates/*.html")
}

要注意 URL 前缀和文件树前缀是两件事：/static/ 是 HTTP 路由设计，assets/web 是嵌入布局。把两者分开后，未来更换资源来源时，模板与处理器的调用契约仍然稳定。

路径与安全边界：最容易误判的四件事

• 路径不是操作系统路径。io/fs 使用 UTF-8、无根、斜杠分隔的路径；/index.html、web/ 和包含 .. 的路径都不符合常规有效路径规则。
• 目录不存在不会被提前检查。fs.Sub 不保证 dir 当前存在，初始化阶段若要尽早暴露配置错误，可以随后调用 fs.Stat(sub, ".") 或打开一个约定文件。
• 错误要在边界处包装。用 errors.Is(err, fs.ErrNotExist) 判断资源缺失，用 *fs.PathError 保留具体操作和路径，不要只比较错误字符串。
• Sub 不是 chroot。如果底层是 os.DirFS，目录中的符号链接仍可能指向根目录之外；需要更强的操作系统访问约束时，应使用适合当前 Go 版本的目录句柄/根目录能力，而不是把 fs.Sub 当成安全沙箱。

用 fstest.MapFS 把根目录契约固定下来

测试重点不是检查磁盘上有没有某个前缀，而是确认“子根里能读到什么”。fstest.MapFS 可以用内存中的文件树复现这条契约，避免测试依赖本机目录。

func TestWebRoot(t *testing.T) {
    source := fstest.MapFS{
        "assets/web/index.html": &fstest.MapFile{Data: []byte("home")},
        "assets/web/css/site.css": &fstest.MapFile{Data: []byte("body{}")},
    }

    // 截取后，测试对象应只从 web 子根解析路径。
    web, err := fs.Sub(source, "assets/web")
    if err != nil {
        t.Fatal(err)
    }
    if _, err := fs.ReadFile(web, "index.html"); err != nil {
        t.Fatalf("子根读取失败: %v", err)
    }
    if _, err := fs.ReadFile(web, "assets/web/index.html"); !errors.Is(err, fs.ErrNotExist) {
        t.Fatalf("意外接受了重复前缀: %v", err)
    }
}

这类测试能防止后续有人把 assets/web 又写回业务层，也能让资源目录重命名时只修改初始化位置。生产代码中如果需要列目录或匹配模板，同样从 web 这个子根开始调用 fs.ReadDir、fs.Glob 和 fs.WalkDir。

常见问题

fs.Sub 会把文件复制到新的目录吗？

不会。它返回一个文件系统视图，调用时把子根路径映射回原始文件系统；具体实现可能由底层 SubFS 优化，但调用方不应依赖复制行为。

为什么 fs.Sub 成功了，后面读取仍然报不存在？

因为它不会检查目录当前存在。先核对嵌入模式相对于 Go 文件的位置，再确认 dir 使用的是 assets/web 这样的斜杠路径，并且读取时没有再次拼接这个前缀。

可以用 fs.Sub 防止符号链接越界吗？

不可以。它改变的是 fs.FS 的路径视图，不会自动改变底层文件系统对符号链接的处理。需要安全约束时，应选择底层文件系统提供的访问控制能力。