Go text/template block 怎样覆盖基础模板的默认内容

我在把几个页面拼到同一套 Go 模板布局时，最容易混淆的是：既想保留一份默认内容，又想让具体页面按名称替换它。text/template 的 block 正好解决这个问题：它把“定义一个命名模板”和“在当前位置调用它”合成一段写法；如果后续在同一模板关联集合中重新定义这个名字，页面就能使用新的内容，未覆盖时仍保留默认内容。

官方地址：https://pkg.go.dev/text/template

记住一句话：block 是带默认实现的命名模板入口，覆盖是否生效取决于定义是否被解析进同一个模板集合，最终页面仍要通过稳定的模板名执行。

block 把默认内容变成可覆盖的命名模板

官方语义可以拆成两部分：{{block "content" .}}默认内容{{end}} 等价于先定义名为 content 的模板，再在当前位置调用它。这里的默认内容不是临时变量，而是一个可被同名定义替换的模板体。

这让基础布局可以只关心页头、页脚和内容槽位，而具体页面只负责提供 content。如果没有覆盖定义，默认内容照常输出；如果有同名定义，调用位置使用覆盖后的模板体。

先解析基础布局，再解析同名定义

实际使用时，关键不是把两段字符串简单拼起来，而是把它们解析到同一个 *template.Template 关联集合。下面的例子保留了默认块，也提供了一个页面覆盖版本；错误处理放在解析和执行边界，方便调用方区分模板语法错误与写出错误。

package main

import (
	"os"
	"text/template"
)

type Page struct {
	Title string
}

func main() {
	const layout = `{{define "layout"}}页头|{{block "content" .}}默认内容{{end}}|页脚{{end}}`
	const detail = `{{define "content"}}详情页：{{.Title}}{{end}}`

	// 先建立基础布局，block 会登记默认的 content 模板。
	tmpl, err := template.New("root").Parse(layout)
	if err != nil {
		panic(err)
	}

	// 同一个模板集合解析同名定义，覆盖 block 的默认内容。
	tmpl, err = tmpl.Parse(detail)
	if err != nil {
		panic(err)
	}

	// 用稳定的根模板名执行，数据会传给被调用的 content 模板。
	if err := tmpl.ExecuteTemplate(os.Stdout, "layout", Page{Title: "订单详情"}); err != nil {
		panic(err)
	}
}

这个程序的输出形态是“页头|详情页：订单详情|页脚”。如果删除第二次 Parse，同一个 layout 仍然可以执行，只是中间回到“默认内容”。所以覆盖是可选的，基础布局不必为每个页面复制一份。

覆盖 block 时要把模板放在同一个关联集合

模板文件拆分后，最常见的失误是基础布局和覆盖文件各自调用 template.New，结果它们属于两个互不认识的集合。正确的判断标准不是“文件是否在同一目录”，而是“是否对同一个模板对象继续调用 Parse、ParseFiles 或 ParseFS”。

// 这一段展示多文件场景的核心关系，文件名只是示意。
tmpl, err := template.New("root").ParseFS(fs, "templates/layout.tmpl")
if err != nil {
	return err
}

// 继续对同一 tmpl 解析页面定义，才能覆盖 layout.tmpl 中的 block。
tmpl, err = tmpl.ParseFS(fs, "templates/detail.tmpl")
if err != nil {
	return err
}

// ExecuteTemplate 选择基础布局入口，而不是直接猜测文件名。
return tmpl.ExecuteTemplate(writer, "layout", data)

在工程里我会把入口名固定成 layout，把可替换块名当成模板接口的一部分。这样新增页面只需要提供同名定义，调用方不必知道它来自哪一个文件。

默认 block、直接 define 与 ExecuteTemplate 怎么选

三种写法解决的问题不同。需要“没有页面专属内容时仍能渲染”时，用 block；需要复用一个没有默认实现的片段时，用 define 加 template；需要从 Go 代码明确选择某个根模板时，用 ExecuteTemplate。不要把 ExecuteTemplate 当成覆盖动作，它只负责选择执行入口。

还有一个容易被忽略的安全边界：text/template 默认假设模板作者可信，不会自动为 HTML 输出做安全转义。如果最终输出是网页，应评估 html/template；不要因为 block 的覆盖机制可用，就把不可信模板文本直接交给 text/template 执行。

常见问题

覆盖定义必须和 block 同名吗？

是。block "content" 建立的可覆盖入口名就是 content，覆盖定义需要使用同一个名字，大小写和拼写都不能随意改变。

两个模板对象分别 Parse，为什么覆盖不生效？

因为模板定义属于各自的关联集合。应先创建一个根模板，再对这个对象继续调用 Parse、ParseFiles 或 ParseFS，最后从同一对象执行入口。