Go 项目里页头、页脚和导航一旦复制到多个 HTML 文件，改一次就要搜很多处。更稳的做法是把模板分成 layout、partials、pages 三层：layout 负责页面骨架，partials 负责页头页脚，page 只填正文。用 embed.FS 配合 template.ParseFS 统一解析，再让 block 提供页面内容，handler 最后只执行一个布局入口。

先把模板职责拆成三层，后面才好复用

先建立一个清晰的目录边界，避免把“通用结构”和“页面内容”混到同一个文件里：

layout 不应该知道首页的业务字段，page 也不应该重新写导航。这样换一套页头时只动 partial，新增页面时只增加 page。

用 embed.FS 和 ParseFS 把模板统一装载

embed.FS 把模板编进二进制，部署时不必再猜当前工作目录。下面的 layout 使用 block 预留正文区域，页头和页脚则通过命名模板复用。

{{ define "layout" }}




  
  {{ template "header" . }}
  
{{ block "content" . }}
暂无内容
{{ end }}
  {{ template "footer" . }}


{{ end }}

{{ define "header" }}
项目首页
{{ end }}

{{ define "footer" }}

{{ end }}

页面文件只定义同名的 content 区域即可：

{{ define "content" }}

{{ .Heading }}
{{ .Message }}
{{ end }}

这里的变量仍然由 html/template 按上下文转义。不要因为页面中出现 HTML 就把普通字符串强行转换成 template.HTML；只有内容确实由可信模板作者控制时，才应该使用带类型的安全值。

用 block 让页面只填自己的内容

解析模板时把文件模式一次交给 ParseFS，然后 handler 执行 layout。解析失败属于程序装载问题，应该在启动时直接终止；执行失败则可能发生在请求数据不完整时，应返回服务器错误并记录原因。

package main

import (
  "embed"
  "html/template"
  "log"
  "net/http"
)

//go:embed templates/*.html templates/partials/*.html templates/pages/*.html
var templateFS embed.FS

type PageData struct {
  Title   string
  Heading string
  Message string
  Year    int
}

func main() {
  // 启动时解析，文件名或模板动作写错就立即暴露。
  pages, err := template.ParseFS(templateFS,
    "templates/layout.html",
    "templates/partials/*.html",
    "templates/pages/home.html",
  )
  if err != nil {
    log.Fatal(err)
  }

  http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    data := PageData{Title: "首页", Heading: "欢迎回来", Message: "页面正文由 block 注入", Year: 2026}
    // 执行布局入口，避免 handler 自己拼接页头和页脚。
    if err := pages.ExecuteTemplate(w, "layout", data); err != nil {
      log.Printf("render home: %v", err)
      http.Error(w, "页面渲染失败", http.StatusInternalServerError)
    }
  })

  log.Fatal(http.ListenAndServe(":8080", nil))
}

真实项目中可以为每个页面建立独立模板集合，或者使用唯一的正文模板名，避免多个页面同时定义 content 时互相覆盖。关键不是把所有文件都塞进一个目录，而是保证一次执行对应一套明确的 layout 与 page 组合。

多页面扩展时检查这张清单

• 输出类型：生成 HTML 时使用 html/template，不要把 text/template 当成等价替代。
• 解析顺序：让布局和局部模板的命名稳定，多个页面不要无意间重复定义同一个正文名。
• 错误位置：ParseFS 错误在启动阶段处理，ExecuteTemplate 错误在 handler 中处理。
• 数据边界：模板接收业务数据，不接收拼接好的 HTML 字符串；需要安全 HTML 时要明确审查来源。

如果页面数量继续增加，可以把“页面数据结构”和“模板集合”一起按功能拆分，再让路由只选择渲染入口。这样模板复用解决的是维护成本，而不是把所有页面强行变成同一种结构。

相关问题

为什么 HTML 页面不建议直接使用 text/template？

html/template 会根据 HTML、属性、URL、JavaScript 等上下文做自动转义，目标是防止数据破坏页面结构；text/template 不承担这层 HTML 安全语义。

ParseFS 找不到模板通常先查什么？

先查 //go:embed 的路径是否覆盖了实际文件，再查 ParseFS 使用的模式是否相对于嵌入根目录，最后确认文件没有被放在错误的目录层级。

多个页面都需要复用页脚怎么办？

把页脚写成独立的 define "footer"，由 layout 统一调用；页面只提供自己的正文定义，不重复复制页脚 HTML。