template.FuncMap 注册顺序导致函数找不到的修复

Go 的 text/template 报 function "xxx" not defined 时，先不要改函数签名。最常见的原因是模板已经进入 Parse，template.FuncMap 却在后面才注册。修复方式是把注册动作放到解析之前：template.New(...).Funcs(funcMap).Parse(...)。解析完成后再调用 Funcs，只适合替换已经存在的同名函数，不能补救第一次解析时不存在的函数名。

把“创建模板、注册函数、解析模板”固定成一条构造链，通常就能消除这类报错；如果要热切换实现，则先解析包含该函数名的模板，再在执行前替换同名函数。

先按解析阶段定位错误

Parse 负责把模板文本转换成可执行结构，它需要先知道动作里的函数名。下面的模板在解析阶段就会查找 formatTitle：

const source = `{{formatTitle .Title}}`

// 这里故意先 Parse，解析器还不知道 formatTitle。
tmpl, err := template.New("page").Parse(source)
if err != nil {
	// 中文注释：错误发生在解析期，后续 Execute 尚未开始。
	log.Println(err)
}

// 中文注释：此时再注册，已经无法改变上一次 Parse 的结果。
tmpl = tmpl.Funcs(template.FuncMap{
	"formatTitle": strings.ToUpper,
})

排障时看清错误发生在哪一步很重要：Parse 返回错误，说明函数名、模板语法或参数形态还没有通过解析；Execute 返回错误，则应转向数据为空、函数内部错误或输出写入失败。不要用 Execute 阶段的现象反推注册顺序。

建立解析前注册链

推荐把函数表作为模板构造的一部分，使用链式写法或分步写法都可以，但顺序要固定：

func buildTemplate(source string) (*template.Template, error) {
	funcMap := template.FuncMap{
		// 中文注释：函数名必须与模板动作中的名称完全一致。
		"formatTitle": func(s string) string {
			return strings.TrimSpace(strings.ToUpper(s))
		},
	}

	// 中文注释：先注册再解析，Parse 才能识别 formatTitle。
	return template.New("page").Funcs(funcMap).Parse(source)
}

func render(w io.Writer, source string, title string) error {
	tmpl, err := buildTemplate(source)
	if err != nil {
		// 中文注释：构造失败直接返回，避免拿半成品模板继续执行。
		return fmt.Errorf("parse template: %w", err)
	}
	// 中文注释：Execute 只负责把数据写入输出，不再改变函数注册顺序。
	return tmpl.Execute(w, map[string]string{"Title": title})
}

这条链的价值不只是让示例通过：模板来源变化、增加新函数或接入文件解析时，所有调用方仍然经过同一个入口。生产代码可以在 buildTemplate 中统一做函数表分组，但不要在外层先 ParseFiles，再临时补 Funcs。

集中管理 FuncMap，避免顺序回归

当项目有多个模板目录时，把函数表和解析动作封装起来比在每个 handler 里重复注册更稳。尤其是 ParseFiles、ParseGlob 和 ParseFS，它们同样属于解析动作，必须在此前完成自定义函数注册。

type TemplateSet struct {
	base *template.Template
}

func NewTemplateSet(fsys fs.FS) (*TemplateSet, error) {
	funcMap := template.FuncMap{
		// 中文注释：返回值为 string，模板中可直接作为管道结果使用。
		"assetName": func(name string) string {
			return path.Base(strings.TrimSpace(name))
		},
	}

	// 中文注释：ParseFS 前先 Funcs，所有关联模板共享这组名称空间。
	base, err := template.New("root").Funcs(funcMap).ParseFS(fsys, "templates/*.html")
	if err != nil {
		return nil, fmt.Errorf("load templates: %w", err)
	}
	return &TemplateSet{base: base}, nil
}

如果函数名来自配置，启动时应把非法名称和非函数值当成构造错误处理。Funcs 对不合适的值或不能作为模板函数的名称会触发 panic，因此不应把未经约束的外部输入直接塞入 FuncMap。

区分解析后替换的边界

官方文档允许在解析后再次调用 Funcs，但用途是替换同名函数。例如测试环境想让 now 固定返回时间，模板在解析时已经包含 now，就可以在执行前替换实现：

func renderWithClock(w io.Writer, source string, fixed time.Time) error {
	funcMap := template.FuncMap{
		// 中文注释：先提供名字，让 Parse 能识别 now。
		"now": func() time.Time { return time.Now() },
	}
	tmpl, err := template.New("page").Funcs(funcMap).Parse(source)
	if err != nil {
		return err
	}

	// 中文注释：这里是替换已有名称，不是注册一个新模板函数。
	tmpl.Funcs(template.FuncMap{
		"now": func() time.Time { return fixed },
	})
	return tmpl.Execute(w, nil)
}

反过来，如果模板第一次出现的是 version，却等到 Parse 之后才添加 version，仍然会失败。可以把这条规则记成一句话：新名字要赶在 Parse 前，旧名字才能在 Parse 后替换。

发布前的检查清单

另外，text/template 不会自动转义 HTML。如果模板内容或模板作者不可信，应改用 html/template 并重新评估函数返回值的安全边界；这和 FuncMap 注册顺序是两个独立问题。

相关问题

Parse 后还能调用 Funcs 吗

可以，但应当是替换已经参与解析的同名函数。想新增一个此前未出现的函数，仍然要回到 Parse 前注册。

为什么 FuncMap 里的函数名看起来正确仍然报错

优先检查是否注册到了另一个模板实例、是否调用了不同的解析入口，以及模板动作中的大小写和函数名是否完全一致。