text/template missingkey 设置不生效的原因

给 text/template 设置 missingkey=error 后仍然没有报错，通常不是 Option 失效，而是模板没有在访问“缺失的 map 键”。这个选项只作用于模板执行期间的 map 索引；如果数据是结构体、字段本身存在但值为空，或者实际执行的是关联模板，现象都会不同。

missingkey 先管清楚：它只处理 map 缺键

官方文档把 missingkey 定义为：模板索引 map 时找不到键，应该返回默认值、元素零值，还是直接让执行停止。默认的 default（别名 invalid）通常会继续执行并可能输出 ；zero 返回 map 元素类型的零值；error 才会让执行立即返回错误。

package main

import (
	"os"
	"text/template"
)

func main() {
	// 这里故意不提供 Missing，观察 missingkey=error 是否命中。
	t := template.Must(template.New("demo").Option("missingkey=error").Parse("{{.Missing}}"))
	err := t.Execute(os.Stdout, map[string]string{"Name": "Go"})
	if err != nil {
		// Execute 的错误要被检查，否则“没有报错”可能只是被忽略了。
		println("execute error:", err.Error())
	}
}

这个例子访问的是 map[string]string 的缺失键，因此 Execute 会返回错误。若把输入改成包含 Missing 的 map，或者改成字段已经存在的结构体，missingkey 就没有同样的触发点。

为什么换成结构体或 nil 后看起来像设置失效

排查时最容易混淆的是“字段没有可用值”和“map 没有这个键”。结构体字段存在但值为字符串空值、数字零值或布尔值 false，都不是缺失 map 键；missingkey=error 不会把它们当错误。相反，map 的键不存在时，选项才有机会改变执行结果。

因此，看到输出为空时先打印或记录传入数据的真实类型，再确认模板表达式是否真的走到了 map 索引。不要只盯着 Option 那一行。

ParseFiles 与 ExecuteTemplate 可能让你设置错对象

多个文件模板通常属于同一个关联命名空间。ParseFiles 会把文件按基础名关联到模板集合；之后如果用 ExecuteTemplate 执行某个名称，排查时必须确认这个名称确实在刚刚设置 Option 的集合里。一个稳妥写法是先创建根模板、设置选项，再解析文件，并检查解析和执行的错误：

package main

import (
	"os"
	"text/template"
)

func render(path, name string, data any) error {
	// 根模板持有选项和关联模板，ExecuteTemplate 使用同一个集合查找 name。
	t, err := template.New("root").Option("missingkey=error").ParseFiles(path)
	if err != nil {
		// 文件不存在或语法错误属于 Parse 阶段，不能靠 missingkey 处理。
		return err
	}
	// name 必须是 ParseFiles 产生的模板名；不要误执行未定义的 root。
	return t.ExecuteTemplate(os.Stdout, name, data)
}

如果实际代码重新调用了 template.ParseFiles 创建另一组模板，或把错误丢掉后执行了不同对象，前面设置的选项自然不会影响那次执行。这里的关键不是把 Option 放在某个固定行，而是确认“设置、解析、执行”使用的是同一套模板集合。

用四项清单定位“设置不生效”

• 数据是否真的是 map，并且模板表达式访问的是不存在的键？
• 选项是否写成精确的 missingkey=error、missingkey=zero 或 missingkey=default？无效选项会触发 panic。
• ParseFiles、ParseGlob、Execute 和 ExecuteTemplate 是否围绕同一个模板集合？
• Parse 与 Execute 的 error 是否都被返回或记录，而不是被忽略？

把这四项走完，通常可以把问题归到数据形状、模板名称、解析阶段或真正的缺键执行阶段。只有最后一种情况才应该继续比较三种 missingkey 行为。

常见问题

missingkey=error 会检查结构体字段为空吗？

不会。它针对的是 map 缺键；结构体字段为空、零值或 nil 链路需要由数据建模、条件判断或业务校验处理。

missingkey=zero 为什么没有报错？

这是它的定义：缺失键返回 map 元素类型的零值并继续执行。需要阻断渲染时应选择 missingkey=error 并检查 Execute 返回值。

Option 应该放在 Parse 前还是 Parse 后？

更重要的是设置和执行使用同一个模板集合。工程上可在根模板创建后先设置选项，再调用 ParseFiles 或 ParseGlob，这样更容易把配置边界固定下来。