用 embed.FS 打包静态模板并保持目录结构可测试

把模板编译进 Go 二进制并不难，真正容易留下工程债的是目录边界：业务代码到处写着 web/templates/...，测试必须从仓库根目录启动，渲染器还直接持有一个全局 embed.FS。项目一旦改目录，生产代码和测试代码会一起震动。

更稳妥的做法是增加一层很薄的嵌入资源适配层：资源包负责“打包什么”和“对外暴露哪一棵子树”，渲染包只接收标准库接口 fs.FS。这样，生产环境可以注入 embed.FS 的子目录，单元测试则注入 fstest.MapFS，两边运行同一套模板解析逻辑。

官方文档：https://pkg.go.dev/embed、https://pkg.go.dev/io/fs、https://pkg.go.dev/testing/fstest、https://pkg.go.dev/html/template

先看最终目录：让资源归资源、渲染归渲染

示例项目把“资源声明”和“模板使用”分成两个内部包。assets 知道源文件位于 web/templates，但 render 只知道自己能看到一个 templates 目录。

myapp/
├── cmd/server/main.go
└── internal/
    ├── assets/
    │   ├── assets.go
    │   └── web/templates/
    │       ├── layout.html
    │       └── home.html
    └── render/
        ├── render.go
        └── render_test.go

# web 是打包层目录，templates 才是渲染层可见的逻辑根。

这里有两个不同的稳定性目标。第一，二进制内部保留源代码中的目录树，避免所有文件挤在包根目录。第二，调用方不应该知道打包层根目录叫 web；这个前缀以后改成 site，渲染器也不该跟着修改。

用嵌入资源适配层稳定路径

//go:embed 的匹配模式相对于当前 Go 源文件所在包目录；路径统一使用正斜杠。指令必须紧邻包级变量声明，并且每个模式至少匹配一个文件，否则构建直接失败。把这条规则集中在一个资源包里，能避免业务包各自维护模式。

package assets

import (
    "embed"
    "io/fs"
)

// files 保存编译期快照，业务包不直接访问它。
//go:embed web/templates/*.html
var files embed.FS

func Web() (fs.FS, error) {
    // 去掉仅属于打包层的 web 前缀，对外从 templates/ 开始。
    return fs.Sub(files, "web")
}

embed.FS 本身实现了 fs.FS，而 fs.Sub 会返回指定目录对应的子文件系统。经过这一步，外部打开 templates/layout.html 即可，不需要重复书写 web/。目录调整只会影响适配层中的一个位置。

io/fs 使用逻辑路径，不是操作系统路径。合法名称不以斜杠开头或结尾，也不包含空元素、. 或 ..；根目录用 . 表示。因此不要用 filepath.Join 拼嵌入路径，也不要把 Windows 反斜杠带进模板模式。

渲染器只依赖 fs.FS

接口边界的关键并不是“能否把参数写成接口”，而是让渲染器完全不知道资源来自哪里。它不导入 embed，不读取全局变量，也不依赖当前工作目录。

package render

import (
    "html/template"
    "io"
    "io/fs"
)

type Renderer struct {
    templates *template.Template
}

func New(source fs.FS) (*Renderer, error) {
    // 相对路径属于 fs.FS 契约，与磁盘绝对路径无关。
    parsed, err := template.ParseFS(source, "templates/*.html")
    if err != nil {
        return nil, err
    }
    return &Renderer{templates: parsed}, nil
}

func (r *Renderer) Home(w io.Writer, data any) error {
    // layout 是模板内部的稳定名字，不暴露文件系统根目录。
    return r.templates.ExecuteTemplate(w, "layout", data)
}

模板文件用显式定义固定执行名称。这样即使文件名用于组织目录，调用端仍然可以稳定执行 layout。

{{/* layout.html：定义公共页面骨架。 */}}
{{define "layout"}}


{{template "content" .}}

{{end}}

{{/* home.html：只提供当前页面内容。 */}}
{{define "content"}}
{{.Title}}
{{end}}

在启动入口完成生产注入即可。错误应在进程启动时暴露，而不是等到第一次请求才发现目录不存在或模板解析失败。

webFS, err := assets.Web()
if err != nil {
    // 子目录不存在属于部署前错误，启动阶段立即终止。
    log.Fatal(err)
}

renderer, err := render.New(webFS)
if err != nil {
    // 模板语法问题同样应尽早失败。
    log.Fatal(err)
}

把生产资源和测试资源放进同一接口

测试渲染逻辑时，最小输入不是整个项目目录，而是渲染器真正依赖的两份模板。fstest.MapFS 用一个映射构造内存文件系统，键名仍然遵守 io/fs 的正斜杠逻辑路径。

package render

import (
    "bytes"
    "strings"
    "testing"
    "testing/fstest"
)

func TestHome(t *testing.T) {
    // 测试只声明业务依赖的逻辑路径，不依赖仓库工作目录。
    testFS := fstest.MapFS{
        "templates/layout.html": {
            Data: []byte(`{{define "layout"}}{{template "content" .}}{{end}}`),
        },
        "templates/home.html": {
            Data: []byte(`{{define "content"}}
{{.Title}}
{{end}}`),
        },
    }

    renderer, err := New(testFS)
    if err != nil {
        t.Fatal(err)
    }

    var out bytes.Buffer
    if err := renderer.Home(&out, struct{ Title string }{"嵌入资源"}); err != nil {
        t.Fatal(err)
    }
    if !strings.Contains(out.String(), "嵌入资源") {
        t.Fatalf("输出缺少标题：%s", out.String())
    }
}

这类测试验证的是“渲染器面对符合约定的文件系统时是否正确工作”。它不需要编译真实模板资源，也不会因为测试进程从 IDE、仓库根目录或临时目录启动而出现不同结果。

如果模板样本很多，也可以把样本放到 testdata/web，再注入 os.DirFS("testdata/web")。两三个短模板优先用 MapFS，需要人工查看或复用的大型样本用 testdata。两种方式对渲染器都只是一个 fs.FS。

再用一个契约测试盯住真实资源树

替身测试不能证明生产资源真的被打进二进制，因此还需要一个很小的契约测试。它不重复测试渲染内容，只检查适配层暴露的路径存在并符合文件系统约定。

package assets_test

import (
    "testing"
    "testing/fstest"

    "example.com/myapp/internal/assets"
)

func TestEmbeddedTemplateTree(t *testing.T) {
    webFS, err := assets.Web()
    if err != nil {
        t.Fatal(err)
    }

    // TestFS 检查指定文件以及文件系统行为是否满足 fs.FS 约定。
    if err := fstest.TestFS(
        webFS,
        "templates/layout.html",
        "templates/home.html",
    ); err != nil {
        t.Fatal(err)
    }
}

现在测试职责被拆开了：render 包的单元测试快速覆盖模板解析和输出；assets 包的契约测试覆盖真实嵌入模式与目录裁剪。任何一侧失败时，原因都更容易定位。

# 运行渲染测试与嵌入资源契约测试。
go test ./...

五个常见反模式

1. 渲染器直接引用全局 embed.FS。依赖藏在包变量里，测试无法替换。应通过构造函数传入 fs.FS。
2. 函数参数写成 embed.FS。实现类型泄漏到业务层，MapFS 和 DirFS 无法直接替换。
3. 运行时使用 os.ReadFile("./web/...")。相对路径绑定当前工作目录，打包成单文件后也没有对应磁盘资源。
4. 所有调用点都写 web/templates 前缀。打包目录变成业务协议。应在边界处用 fs.Sub 裁掉前缀。
5. 直接嵌入整个 web 目录。范围过宽可能把草稿或测试文件一起编译进去。优先使用 web/templates/*.html 这类窄模式。

边界条件与取舍

embed.FS 保存编译时快照，源模板修改后必须重新构建二进制；它适合随程序版本发布的资源，不适合需要在线编辑的模板。普通目录模式会忽略名称以点号或下划线开头的文件，如果确实需要这些文件，要显式使用 all: 前缀，并确认没有把无关内容带入。

fs.Sub 不是安全隔离机制，它只是路径视图适配。真正的价值是缩小调用方可见的命名空间，并把目录知识固定在资源边界。生产环境中的资源依旧只读，这也促使上传文件、缓存文件等可变数据走独立存储。

模板文件的基础文件名最好保持唯一，或统一使用 {{define}} 明确命名。一次解析多个目录时，含糊的同名模板会让覆盖关系难以阅读；目录结构可测试，不等于模板命名可以随意。

什么时候值得采用这套模式

如果项目需要单二进制发布，同时拥有 HTML 模板、邮件模板、SQL 迁移片段或静态配置，这套模式很合适。判断是否实现到位，可以看三点：业务包是否只依赖 fs.FS；测试是否能用 MapFS 完成；目录前缀是否只出现在资源适配层。

最终结构并不复杂：//go:embed 负责收集，fs.Sub 负责收口，fs.FS 负责解耦，ParseFS 负责消费，MapFS 负责替换。把这五个角色放在正确边界，静态模板既能跟着程序可靠发布，也能在测试中保持轻量、可控和可定位。