Go html/template Templates 怎样列出已经解析的命名模板

Go html/template 解析多个文件或多个 {{define}} 后，最直接的确认方法是遍历 t.Templates()，对每个结果调用 Name()。如果只想检查一个名字，就调用 t.Lookup(name)：找到时返回模板指针，找不到时返回 nil。

排查模板未定义时，先把实际注册名称列出来，再拿这个清单去对照 ExecuteTemplate 的 name 参数；不要凭文件目录或自己想象的名字猜测。

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

先划定要保护的模板命名空间

这里要确认的资产不是 HTML 内容，而是“哪些名称已经进入当前模板集合”。一个根模板可以和多个命名模板建立关联：文件名可能产生根名称，{{define "header"}} 会产生名为 header 的模板，而 ExecuteTemplate 最终需要使用其中某个实际名称。

名称排查的第一条原则是把解析错误与名称错误分开。解析失败时，模板对象通常不会按预期完成；解析成功后仍然报模板未定义，才重点检查 Templates() 列出的名称、Lookup 的参数和执行调用中的名称是否一致。

用 Templates 列出关联模板名称

Templates() 返回与当前模板关联的模板切片，包括当前模板本身。结合 Name() 遍历，就能得到实际名称清单。下面的示例使用内存字符串，不依赖本地文件，重点只放在注册和列名。

package main

import (
	"fmt"
	"html/template"
	"log"
)

func main() {
	const source = `{{define "header"}}页头{{end}}
{{define "content"}}正文{{end}}`

	t, err := template.New("layout").Parse(source)
	if err != nil {
		// 解析失败时先停止，避免把不完整的模板集合当成有效结果。
		log.Fatal(err)
	}

	for _, item := range t.Templates() {
		// Name 返回模板注册时使用的名称，用它建立排查清单。
		fmt.Println(item.Name())
	}
}

这段程序的清单会包含 layout、header 和 content。这里的关键不是输出顺序，而是确认名称确实存在于同一个关联集合中。业务代码可以把这一步放到启动期诊断、单元测试或开发环境日志中。

用 Lookup 验证单个命名模板

当你已经知道期望名称时，不必每次都遍历整个集合。Lookup 会在当前模板关联的命名空间中查找；官方文档明确说明，没有对应名称时返回 nil。因此判空本身就是排障控制点。

func requireTemplate(t *template.Template, name string) (*template.Template, error) {
	// Lookup 只负责查找，不会替调用方决定缺失模板该怎么处理。
	item := t.Lookup(name)
	if item == nil {
		return nil, fmt.Errorf("模板未注册: %q", name)
	}

	// 返回查到的对象，调用方可以继续 ExecuteTemplate 或读取 Name。
	return item, nil
}

如果 Lookup("content") 成功而 Lookup("Content") 返回 nil，先检查大小写、空格和命名约定。名称匹配是精确的，不能把文件路径、URL 路径或业务标题当成自动别名。

ParseFiles 的根名称与 define 名称要分开看

ParseFiles 解析多个文件并把结果关联到模板。官方文档说明，返回模板的名称与第一个文件的基础名称有关；文件中的 define 块又可以建立额外的命名模板。也就是说，文件名和 define 名称是两套容易混淆的线索。

func listAndCheck(t *template.Template, wanted string) error {
	for _, item := range t.Templates() {
		// 先记录实际名称，再检查调用方期望的名称是否出现。
		fmt.Printf("registered=%q\n", item.Name())
	}

	if t.Lookup(wanted) == nil {
		// 缺失时保留期望值，方便和上面的清单逐字比较。
		return fmt.Errorf("找不到命名模板 %q", wanted)
	}
	return nil
}

排查 template: ... is undefined 一类错误时，可以按下面的顺序检查：

1. 确认每次 Parse 或 ParseFiles 都检查了返回的 error。
2. 打印 Templates() 和 Name()，确认命名模板真的进入当前集合。
3. 对照 Lookup 的参数，检查大小写、空格和 define 名称。
4. 最后检查 ExecuteTemplate 传入的 name 是否就是清单中的精确名称。

常见问题

Templates() 返回的模板里为什么还有根模板？

因为官方 API 的定义就是返回与当前模板关联的模板，并包含当前模板本身。遍历时不要把根模板误判为多余项；如果只关心命名模板，可以按名称或自己的命名约定过滤。

DefinedTemplates() 能不能代替 Templates()？

它更适合生成错误消息：返回一段列出已定义模板的字符串。需要逐个读取名称、调用 Lookup 或继续执行时，优先使用 Templates() 和 Lookup。

Lookup 找不到模板时会返回错误吗？

不会，它返回 nil。调用方应先判空，再把缺失名称包装成自己的错误或记录诊断信息。

文件名就是 ExecuteTemplate 的名称吗？

不一定。使用 ParseFiles 时，根模板名称与首个文件的基础名称有关；命名模板通常来自 define。最终以 Templates() 列出的实际名称为准。

小结：先用 Templates() 加 Name() 得到完整清单，再用 Lookup 检查单个名称；确认名称后，ExecuteTemplate 才能稳定调用。这样可以把“没有解析成功”和“名称没对上”两条故障路径分开。