Go embed 静态资源打包模式：模板和前端文件要不要收进二进制？

Go 项目上线时，经常会遇到一个看似小但很烦的问题：模板文件、静态前端文件、邮件模板、SQL 初始化脚本，到底要不要跟二进制放在一起？如果放磁盘，部署时要保证目录完整；如果用 embed.FS 打进二进制，发布会更省心，但开发时热更新又没那么方便。

这篇文章不把 go:embed 当成单纯语法点，而是把它当成一种静态资源打包模式来看：什么时候适合收进二进制，什么时候应该继续读外部目录，以及怎么做一套开发和发布都舒服的结构。

模式命名：内嵌资源 + 可切换文件系统

这个模式可以叫“内嵌资源 + 可切换文件系统”。核心思想是：资源读取代码只依赖 fs.FS，不直接关心底层来自磁盘还是来自 embed.FS。开发环境用 os.DirFS，方便改模板和 CSS；发布环境用 embed.FS，减少部署目录缺失。

这不是为了追求“一个二进制包打天下”的形式感，而是把资源加载变成可替换边界。只要边界清楚，后面无论接 http.FileServer、模板解析，还是邮件模板渲染，都可以复用同一套入口。

适用压力：为什么部署时总是缺静态文件

很多线上问题不是代码逻辑错，而是发布产物不完整。比如本地能打开 templates/index.html，容器里却忘了复制 templates；前端构建产物放在 web/dist，发布脚本只传了二进制；新模板文件上线了，但某台机器目录没同步。

下面这张图展示了这个模式的第一条决策路径：如果资源随版本发布、体积可控、运行时不需要用户修改，就适合进入 embed.FS；否则仍然保留外部目录。

典型实现：开发读磁盘，发布读 embed.FS

先准备一个目录结构：

project/
  cmd/server/main.go
  internal/web/
    assets.go
    dist/
      index.html
      app.css
      app.js
    templates/
      email.html

在 internal/web/assets.go 中声明内嵌资源：

package web

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

//go:embed dist templates
var embedded embed.FS

func Assets(useDisk bool) (fs.FS, error) {
    if useDisk {
        return os.DirFS("internal/web"), nil
    }
    return embedded, nil
}

如果希望对外暴露静态文件，可以把子目录裁出来：

func Dist(useDisk bool) (fs.FS, error) {
    root, err := Assets(useDisk)
    if err != nil {
        return nil, err
    }
    return fs.Sub(root, "dist")
}

HTTP 服务里只依赖 fs.FS：

func mountStatic(mux *http.ServeMux, useDisk bool) error {
    dist, err := web.Dist(useDisk)
    if err != nil {
        return err
    }

    if _, err := fs.Stat(dist, "index.html"); err != nil {
        return fmt.Errorf("missing index.html: %w", err)
    }

    mux.Handle("/", http.FileServer(http.FS(dist)))
    return nil
}

这段代码的关键不是 http.FileServer，而是启动时先检查关键文件。这样资源缺失会在服务启动阶段暴露，而不是等用户访问首页才发现 404。

反例：什么东西不该塞进二进制

embed 很方便，但不是所有文件都适合收进去。下面几类要谨慎：

• 运行时频繁变化的文件，比如用户上传内容、报表输出、缓存文件。
• 不同环境不同值的配置，比如数据库地址、密钥、外部服务 token。
• 体积很大的媒体文件，比如视频、大模型权重、大量图片包。
• 需要运维临时替换的模板，比如按客户定制的邮件或页面。

一个常见反例是把生产配置也打进二进制。这样看似部署少了文件，实际会让配置变更必须重新构建，密钥轮换也更麻烦。资源是否内嵌，应该看它是否“随代码版本一起变化”，而不是看它能不能被 go:embed 语法匹配到。

后果：发布简单了，但边界也更硬

采用这个模式后，发布产物会更稳定：只要二进制是对的，模板和前端文件通常也在。容器镜像可以更薄，部署脚本也少一个复制目录的步骤。

代价也很明确：资源更新需要重新构建；二进制体积会上升；如果开发环境和发布环境的目录前缀没统一，可能出现本地能跑、发布找不到子目录的问题。因此建议把资源入口集中在一个包里，不要让业务代码到处写 os.Open 或硬编码目录。

判断清单：你的项目适不适合用 embed

最后用这份清单判断：

• 资源是否随代码版本一起发布？是的话适合内嵌。
• 资源是否需要用户或运维在运行时修改？是的话不要内嵌。
• 资源体积是否可控？如果几十 MB 以上，要评估二进制体积。
• 开发时是否需要热更新？需要的话保留 useDisk 开关。
• 服务启动时是否检查关键文件？必须检查，避免线上访问才发现缺文件。

总结一下，embed.FS 最适合模板、前端构建产物、固定示例文件、内置 SQL 脚本这类随版本走的资源。把它和 fs.FS 边界一起使用，开发阶段可以保持灵活，发布阶段可以减少遗漏，是 Go 项目里很实用的一种资源打包模式。