Go embed 管理默认模板的构建组织方式

把默认模板随 Go 程序一起发布，比较稳的组织方式是：在负责渲染的包里声明包级 embed.FS，让 //go:embed 只匹配该包内的模板目录；启动时用 fs.Sub 收敛根路径，再用 html/template.ParseFS 解析一次。请求处理阶段只执行已经解析好的模板，不再读取磁盘，也不把模板解析错误拖到首个请求。

先把默认模板的构建边界固定下来

go:embed 不是运行时的文件查找器。它在编译时读取源文件所在包目录下匹配到的文件，并把内容放进字符串、字节切片或 embed.FS。因此，推荐把目录设计成下面这样：

web/
├── embed.go
└── templates/
    ├── home.html
    └── error.html

声明文件和模板目录属于同一个包，路径用正斜杠表达，发布时不依赖工作目录。不要把模板放到包外再期待 ../templates 被打进二进制；也不要用当前目录的模糊通配符掩盖漏文件问题。

用 embed.FS 和 fs.Sub 管理模板根目录

将默认模板封装在一个加载函数中，调用方只关心“拿到可执行的模板”。fs.Sub 的价值在于把资源树里的 templates/ 隐藏掉，后续新增布局或页面时，模板名称仍然保持短而稳定。

package web

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

// templateFiles 只保存包内的默认模板，构建时注入资源。
//go:embed templates/*.html
var templateFiles embed.FS

// LoadDefaultTemplates 在启动阶段解析默认模板，失败就让服务启动失败。
func LoadDefaultTemplates() (*template.Template, error) {
    // 先收敛根目录，避免业务代码到处拼接 templates/ 前缀。
    root, err := fs.Sub(templateFiles, "templates")
    if err != nil {
        return nil, err
    }
    // ParseFS 使用 html/template，输出 HTML 时保留上下文转义。
    return template.ParseFS(root, "*.html")
}

这里的边界很明确：fs.Sub 失败代表嵌入目录结构不符合预期，ParseFS 失败代表模板语法或模板集合有问题。两者都应该在启动阶段暴露，而不是等用户访问某个页面才发现。

启动时解析一次，请求时只传数据

模板解析通常属于初始化工作。服务启动时加载一次并保存指针，请求处理函数只负责选择名称和传入数据；这样既避免重复解析，也能把错误分成“服务无法启动”和“单次渲染失败”。

type Server struct {
    templates *template.Template
}

func NewServer() (*Server, error) {
    // 启动阶段完成解析，模板缺失时直接返回错误。
    t, err := LoadDefaultTemplates()
    if err != nil {
        return nil, err
    }
    return &Server{templates: t}, nil
}

func (s *Server) RenderHome(w http.ResponseWriter, data any) error {
    // 每次请求只执行已解析模板，不重新访问磁盘。
    if err := s.templates.ExecuteTemplate(w, "home.html", data); err != nil {
        return fmt.Errorf("execute home template: %w", err)
    }
    return nil
}

实际文件还需要导入 fmt 和 net/http。示例故意保留返回错误的路径：执行失败可能来自数据类型不符合模板动作，不能和构建时漏文件混成一个“模板错误”。

构建前用清单检查默认模板边界

还要记住目录匹配的细节：目录递归嵌入时，以点号或下划线开头的文件默认会被排除；模式不能穿出模块边界，也不能匹配符号链接等不允许的对象。默认模板一旦进入二进制，修改磁盘文件不会改变正在运行的进程；需要热更新时，应另设外部模板方案，不要悄悄改变默认模板的发布语义。

相关问题

为什么模板文件改了但服务没有变化？

因为模板内容在构建时已经写进程序。重新生成并重启二进制后才会看到改动；运行中的进程不会重新读取模板目录。

可以把 text/template 换成 html/template 吗？

输出 HTML 时应使用 html/template，它会按 HTML、CSS、JavaScript 和 URI 上下文进行转义。只有纯文本模板才考虑 text/template。

为什么要使用 fs.Sub？

它把嵌入资源的物理目录和业务模板名分开，调用方只处理 home.html 这类稳定名称，目录调整时改动更集中。

默认模板的关键不是把文件“藏进二进制”，而是让目录、初始化时机和错误边界都可预测：包内声明负责构建，ParseFS 负责启动检查，ExecuteTemplate 负责请求渲染。