Go template 执行时报 function not defined 怎么修

Go 的 text/template 报 function not defined，通常不是数据对象为空，而是模板在解析时还找不到这个函数。最常见的修复顺序是：先用 Funcs 注册与模板中完全同名的函数，再调用 Parse、ParseFiles 或 ParseFS；如果模板已经解析失败，之后再注册函数不会补救这次解析。

一、先判断错误发生在 Parse 还是 Execute

模板函数是在模板动作中按名称查找的。例如模板写成 {{upper .Name}}，解析器需要先知道 upper 是一个可调用函数。下面的顺序会在 Parse 阶段失败，后面的 Funcs 根本没有机会生效：

package main

import (
	"fmt"
	"strings"
	"text/template"
)

func main() {
	// 这里故意先 Parse；解析器还不知道 upper 是什么。
	t, err := template.New("page").Parse("{{upper .Name}}")
	if err != nil {
		fmt.Println("parse failed:", err)
		return
	}

	// 这一步来得太晚，不能修复上面的解析错误。
	t = t.Funcs(template.FuncMap{"upper": strings.ToUpper})
	_ = t
}

如果错误出现在 Execute，则更像是函数已经注册但调用模板、数据或返回值出了问题。先看错误返回点，不要一看到模板报错就改数据结构。

二、把 Funcs 放到 Parse 前面

正确写法是先建立模板、绑定函数表、再解析文本。FuncMap 的键就是模板里写的名字，所以 Go 侧函数叫 strings.ToUpper 没关系，模板侧仍然要通过键 upper 调用：

package main

import (
	"os"
	"strings"
	"text/template"
)

type PageData struct {
	Name string
}

func main() {
	// 先注册模板可见名称，再解析包含 {{upper ...}} 的文本。
	funcs := template.FuncMap{"upper": strings.ToUpper}
	tmpl, err := template.New("page").Funcs(funcs).Parse("你好，{{upper .Name}}")
	if err != nil {
		// 解析失败要返回错误，避免服务带着半成品模板启动。
		panic(err)
	}

	// Execute 只负责把数据交给已经解析好的模板。
	if err := tmpl.Execute(os.Stdout, PageData{Name: "gopher"}); err != nil {
		panic(err)
	}
}

这个例子会输出大写后的名称。生产代码通常不应该直接 panic，但示例保留了清晰的失败边界：装载模板时返回错误，业务请求阶段只执行已经成功解析的模板。

三、仍然报错时，按名称链路逐项核对

把问题拆成“模板调用名—FuncMap 键—实际 Parse 入口”三段，通常比盲目增加函数更快。

还要检查函数签名。模板函数可以返回一个值，也可以返回“值加 error”；如果函数有不支持的参数或返回形式，可能从“找不到函数”变成执行阶段的调用错误。需要输出 HTML 时应使用 html/template，不要仅为绕过报错而改用不自动转义的 text/template。

四、生产装载代码要让错误尽早暴露

建议把函数表和模板解析封装在一个入口，避免某个调用方忘记注册。文件模板可以沿用同样顺序：

func loadTemplate(fsys fs.FS) (*template.Template, error) {
	// 所有入口共用同一份函数表，避免 ParseFS 路径遗漏注册。
	funcs := template.FuncMap{"upper": strings.ToUpper}
	return template.New("page").Funcs(funcs).ParseFS(fsys, "templates/*.tmpl")
}

启动阶段遇到错误就记录并退出或交给上层处理；不要把错误吞掉后让请求阶段才暴露。只有模板内容是编译期可信常量、并且确实希望启动时直接崩溃时，才考虑 template.Must。如果模板来自用户或运营输入，应保留显式错误返回，并单独评估模板执行权限。

五、常见问题

为什么函数已经注册，还是提示找不到？

优先确认注册发生在真正的 Parse 调用之前，并确认模板使用的名称与 FuncMap 键完全一致；多套模板装载路径最容易漏掉其中一套。

把 Funcs 放在 Execute 前可以吗？

不应依赖这个顺序。函数需要在解析阶段可见，稳定做法是构造模板后立即调用 Funcs，随后再 Parse。

text/template 和 html/template 的函数注册方式一样吗？

两者都有相同的模板函数注册思路，但 HTML 输出应优先使用 html/template，让上下文转义承担安全边界。

记住一条排查主线：先看错误阶段，再核对 FuncMap 键和模板动作，最后确认实际使用的 Parse 与 ExecuteTemplate 入口。这样通常不需要改数据模型，就能修好 function not defined。