Go embed 怎样组织多级静态资源

Go 项目里把模板、CSS、JavaScript 或内置配置打进二进制时，真正容易出错的不是 //go:embed 本身，而是资源根目录被带进了运行时路径。我的处理方式是：先用一个 embed.FS 接住完整目录，再用 fs.Sub 把业务需要的子目录切成独立文件系统，后面的模板解析和 HTTP 静态文件服务只面对这个更小的根。

官方文档：https://go.dev/doc/

先把磁盘目录映射成 embed.FS

假设项目中有下面这棵目录树。这里的重点是资源层次，而不是把每个文件单独声明；把公共的 assets 目录交给一个 embed.FS，后面可以从同一份嵌入内容中分别取模板和静态文件。

web/
├── assets/
│   ├── templates/
│   │   └── index.html
│   └── static/
│       ├── css/app.css
│       └── js/app.js
└── main.go

//go:embed 后面的模式相对于当前 Go 源文件所在目录，使用正斜杠书写。目录模式可以把目录树嵌入；如果项目确实需要以点号或下划线开头的资源，再根据 embed 包的规则选择 all: 前缀。先把路径范围控制好，通常比运行时再猜文件位置更容易维护。

package main

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

//go:embed assets
var embedded embed.FS

func listEmbeddedFiles() error {
    // WalkDir 使用嵌入文件系统中的斜杠路径，从 assets 根开始枚举。
    return fs.WalkDir(embedded, "assets", func(path string, entry fs.DirEntry, err error) error {
        if err != nil {
            // 把读取错误原样返回，避免把缺失目录误报成空目录。
            return err
        }
        if !entry.IsDir() {
            fmt.Println(path)
        }
        return nil
    })
}

用 fs.Sub 截取稳定的资源子树

如果所有调用都写成 assets/static/css/app.css，调用方就会被嵌入时的外层目录绑住。fs.Sub 的作用是创建一个新的文件系统视图：它仍然读取同一份嵌入内容，但把指定目录当成新的根。子文件系统里的 css/app.css 不再需要重复写 assets/static 前缀。

package main

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

//go:embed assets
var embedded embed.FS

func readCSS() ([]byte, error) {
    // 只暴露 static 子树，让上层代码不必知道完整的打包目录。
    staticFS, err := fs.Sub(embedded, "assets/static")
    if err != nil {
        // 目录名写错时立即失败，避免后面出现迷惑的 file not found。
        return nil, fmt.Errorf("切分静态资源目录: %w", err)
    }

    // 对新的 FS 根使用相对路径，路径仍然采用正斜杠。
    return fs.ReadFile(staticFS, "css/app.css")
}

这里有两个容易混淆的根：embedded 的根包含 assets，而 staticFS 的根已经是 assets/static。因此对 staticFS 再读取 assets/static/css/app.css 会多拼一层，必然得到找不到文件的错误。

把子文件系统交给模板或 HTTP 服务

切分完成后，模板和静态文件服务都可以只接收 fs.FS。这样做的好处是，处理函数不再关心资源是来自嵌入文件、测试目录还是其他实现；资源根的决定集中在组装阶段。

package main

import (
    "embed"
    "fmt"
    "html/template"
    "io/fs"
    "net/http"
)

//go:embed assets
var embedded embed.FS

func newServer() (http.Handler, error) {
    // 模板和静态文件各自拥有清晰的 FS 根，避免路径前缀相互泄漏。
    templateFS, err := fs.Sub(embedded, "assets/templates")
    if err != nil {
        return nil, fmt.Errorf("切分模板目录: %w", err)
    }
    staticFS, err := fs.Sub(embedded, "assets/static")
    if err != nil {
        return nil, fmt.Errorf("切分静态目录: %w", err)
    }

    // ParseFS 的模式相对于 templateFS 根，不能再带 assets/templates。
    page, err := template.ParseFS(templateFS, "*.html")
    if err != nil {
        return nil, fmt.Errorf("解析模板: %w", err)
    }

    mux := http.NewServeMux()
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        // 这里只演示把解析好的模板写出，真实项目应传入页面数据。
        if err := page.ExecuteTemplate(w, "index.html", nil); err != nil {
            http.Error(w, "渲染页面失败", http.StatusInternalServerError)
        }
    })

    // StripPrefix 后，FileServer 看到的是 css/app.css 或 js/app.js。
    files := http.FileServer(http.FS(staticFS))
    mux.Handle("/static/", http.StripPrefix("/static/", files))
    return mux, nil
}

如果模板文件名使用了自定义模板名，ExecuteTemplate 的名字要与模板声明一致；这和 fs.Sub 无关。HTTP 部分则要同时检查 URL 前缀和 StripPrefix：/static/css/app.css 去掉 /static/ 后，文件系统根下必须真的存在 css/app.css。

按根目录分层排查路径问题

遇到 file does not exist 时，我会按下面三层检查，而不是先改 URL 或反复改 StripPrefix：

还有一个边界值得记住：嵌入文件系统使用的是编译时内容，部署后修改工作目录中的同名文件不会改变二进制里的资源。如果需求是热更新模板，就不应把“运行时目录”与 embed.FS 混为一谈；可以把读取器抽象为 fs.FS，再按环境注入不同实现。

最后留一张可执行清单

• 嵌入模式从当前 Go 源文件位置出发，目录名和大小写先核对。
• 每次调用 fs.Sub 后，都把返回值当成新的根，不再重复拼接被截掉的前缀。
• 模板用相对子根解析，HTTP 用 StripPrefix 把 URL 映射到同一个相对根。
• 需要点号或下划线开头的资源时，确认是否需要 all: 模式，不要以为空目录。
• 将读取逻辑依赖在 fs.FS 上，测试时可以替换为本地目录或测试文件系统。

常见问题

为什么 fs.Sub 返回成功，后面读取仍然找不到文件？

最常见原因是把被截掉的目录前缀又写了一遍。切到 assets/static 后，应读取 css/app.css，而不是完整的 assets/static/css/app.css。

embed.FS 能不能直接给 http.FileServer？

可以通过 http.FS 把实现转换成 http.FileSystem。如果只服务静态子目录，先用 fs.Sub 缩小根，再配合 StripPrefix，路径更容易对齐。

运行时修改 assets 文件为什么不生效？

因为资源已经在编译时嵌入二进制。需要热更新时，应改用可替换的 fs.FS 实现或显式读取外部目录，而不是期待嵌入内容随工作目录变化。