我第一次把 Go 项目的模板从磁盘读取改成 embed.FS 时，以为只要把 ParseFiles 换成 ParseFS 就结束了。真正上线后才发现，麻烦不在“文件从哪里读”，而在“同名模板属于哪个页面”：多个页面都定义 content，如果它们进入同一个模板集合，后解析的定义会覆盖先解析的定义，首页可能渲染出关于页的正文。

更稳妥的迁移方式是：启动时先解析公共布局，然后针对每个页面克隆一份独立模板集合，再把页面自己的内容块解析进克隆。这样既保留多层布局，也让最终二进制不再依赖部署机上的模板目录。

升级范围：改的是模板装配方式

这次迁移不需要改路由协议，也不需要让每个处理函数重新解析文件。核心变化集中在模板初始化阶段。

目录与多层布局约定

下面的目录把外层文档、站点壳层和页面正文分开。文件路径可以调整，但模板名称应保持稳定。

templates/
├── layouts/
│   ├── base.html
│   └── shell.html
└── pages/
    ├── home.html
    └── about.html
# 中文说明：不同目录中的文件名尽量保持唯一，避免按基本文件名注册时发生覆盖。

base.html 负责完整 HTML 文档，调用第二层 shell：

{{/* 中文说明：base 是所有页面统一的执行入口。 */}}
{{define "base"}}



  {{template "shell" .}}

{{end}}

shell.html 提供公共导航、页脚和默认内容块：

{{/* 中文说明：block 同时声明默认内容并立即调用它。 */}}
{{define "shell"}}
示例站点

  {{block "content" .}}
暂无内容
{{end}}

{{end}}

页面文件只覆盖同名 content。例如 home.html：

{{/* 中文说明：这个定义只会进入 home 对应的模板克隆。 */}}
{{define "content"}}
{{.Heading}}
{{.Message}}
{{end}}

新写法：启动期构建页面模板注册表

html/template 会按 HTML 上下文做转义，比直接使用 text/template 更适合网页输出。下面的渲染器把公共模板解析、页面克隆和页面查找集中在一个地方。

package view

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

// 中文说明：编译时把布局和页面模板一起写入最终二进制。
//go:embed templates/layouts/*.html templates/pages/*.html
var templateFiles embed.FS

type Renderer struct {
    pages map[string]*template.Template
}

func NewRenderer() (*Renderer, error) {
    // 中文说明：公共集合尚未执行，因此后续可以安全 Clone。
    common, err := template.New("root").
        Option("missingkey=error").
        ParseFS(
            templateFiles,
            "templates/layouts/base.html",
            "templates/layouts/shell.html",
        )
    if err != nil {
        return nil, fmt.Errorf("解析公共布局: %w", err)
    }

    pageNames := []string{"home", "about"}
    pages := make(map[string]*template.Template, len(pageNames))

    for _, name := range pageNames {
        // 中文说明：每个页面获得独立命名空间，content 不会串页。
        pageSet, err := common.Clone()
        if err != nil {
            return nil, fmt.Errorf("克隆页面 %s: %w", name, err)
        }

        pagePath := "templates/pages/" + name + ".html"
        if _, err := pageSet.ParseFS(templateFiles, pagePath); err != nil {
            return nil, fmt.Errorf("解析页面 %s: %w", name, err)
        }
        pages[name] = pageSet
    }

    return &Renderer{pages: pages}, nil
}

func (r *Renderer) Render(w io.Writer, page string, data any) error {
    tmpl, ok := r.pages[page]
    if !ok {
        return fmt.Errorf("未知页面模板: %s", page)
    }

    // 中文说明：明确执行 base，不依赖 ParseFS 返回对象的文件名。
    if err := tmpl.ExecuteTemplate(w, "base", data); err != nil {
        return fmt.Errorf("渲染页面 %s: %w", page, err)
    }
    return nil
}

处理器只需要复用已经构建好的 Renderer。模板可以并行执行，只要不同请求不要共享同一个写入器。模板执行可能已经写出部分响应后才报错，因此对错误页有严格要求时，可以先渲染到 bytes.Buffer，成功后再写入 http.ResponseWriter。

旧代码最容易留下的四类风险

1. 依赖当前工作目录

template.ParseFiles("templates/base.html") 在本地项目根目录运行通常没问题，但 systemd、容器或临时测试目录的当前路径可能不同。嵌入文件后，读取路径属于编译期确定的虚拟文件系统，不再依赖进程启动位置。

2. 把所有页面一次解析到同一集合

如果 home.html 和 about.html 都定义 content，后解析的非空定义会替换先前定义。模板允许在首次执行前继续解析和重定义，但这不等于所有页面都应该共享覆盖结果。

3. 执行之后再 Clone 或 Parse

Clone 会复制模板及其关联模板的命名空间，但已执行过的模板不能再克隆；ParseFS 也不应在执行后继续修改同一集合。因此注册表应在服务启动、接收请求之前一次构建完成。

4. 不检查通配模式和重名文件

ParseFS 接收文件名或 glob 模式，模式至少要匹配一个文件。多个目录若出现相同基本文件名，后解析的文件可能成为该名称对应的模板。实践中我会让布局文件名唯一，并为每个页面传入明确路径，而不是用过宽的 pages/*.html 把所有覆盖块混在一起。

回归检查：别只看首页能否打开

• 分别渲染 home 与 about，确认两者正文不会互换。
• 从项目根目录之外启动二进制，确认不再出现模板文件不存在。
• 删除一个页面模板或写错 embed 模式，确认应用在启动阶段明确失败。
• 给模板传入缺失字段，确认 missingkey=error 返回可定位错误。
• 并发请求两个页面，确认模板集合不在请求期间被修改。
• 确认错误渲染不会把半截 HTML 与错误页混合写入响应。

迁移清单

1. 把模板目录加入 //go:embed，并确认构建上下文包含这些文件。
2. 为外层文档、公共壳层和正文块使用稳定且唯一的模板名称。
3. 启动时只解析公共布局一次，不在请求处理器里解析文件。
4. 在任何执行发生之前，为每个页面调用 Clone。
5. 只向对应页面克隆解析该页面的覆盖文件。
6. 使用 ExecuteTemplate(w, "base", data) 明确根入口。
7. 把初始化错误作为启动失败处理，把渲染错误带页面名返回。

如果模板都放在 templates 子目录，还可以用 fs.Sub(templateFiles, "templates") 得到以该目录为根的文件系统，让后续模式缩短为 layouts/base.html。它只是调整虚拟文件系统的根，不会改变“公共集合先解析、页面集合后克隆”的关键边界。

Go html/template 官方文档：https://pkg.go.dev/html/template

Go embed 官方文档：https://pkg.go.dev/embed

Go io/fs 官方文档：https://pkg.go.dev/io/fs

这套结构最有价值的地方不是少复制几行 HTML，而是把模板命名空间变成可推理的边界：共享布局明确共享，页面覆盖明确隔离，启动失败早于线上请求。等页面数量增长后，这种边界会比“把所有文件一口气 Parse”省下更多排查时间。