根本原因是函数未在Parse前注册且未导出：Funcs必须在Parse/ParseFiles前调用，函数须首字母大写导出，签名类型须与模板传参严格匹配，否则报“function not defined”或panic。
模板函数注册失败、调用时报 function "xxx" not defined，根本原因只有一个：函数没在 Parse 或 ParseFiles 之前绑定到模板实例上。
Funcs 必须在 Parse 之前调用
Go 模板的函数映射不是运行时动态查表，而是在 AST 构建阶段注入的。一旦 Parse 完成，AST 就定型了，Funcs 再调也没用。
-
template.Must(template.ParseFiles("a.tmpl")).Funcs(f)❌ —— 此时模板已解析完，Funcs被忽略 -
template.Must(template.New("t").Funcs(f).ParseFiles("a.tmpl"))✅ ——Funcs在ParseFiles前链式调用 - 用
ParseGlob("*.tmpl")同理：必须template.New("x").Funcs(f).ParseGlob(...)
自定义函数必须是导出的具名函数
模板引擎只认首字母大写的导出函数。哪怕你在同一包里写了 func myUpper(s string) string，传进 FuncMap 也会被静默跳过，渲染时报错却不提示“未导出”。
- ✅ 正确写法：
func Upper(s string) string { return strings.ToUpper(s) }，然后注册"upper": Upper - ❌ 不支持匿名函数、闭包、方法值（如
(*MyType).Method） - 如果逻辑想保持私有，就包一层导出函数：
func FormatTime(t time.Time, layout string) string { return t.Format(layout) }
函数签名和参数类型必须严格匹配
模板传参全是 interface{}，但函数声明了什么类型，运行时就 expect 什么类型。不匹配直接 panic，不会自动转型。
立即学习“go语言免费学习笔记（深入）”；
- 比如
func Divide(a, b int) int，模板里写{{divide .A .B}}，那.A和.B运行时必须是int，传float64或string都会 panic - 函数名不能含点号（
.），否则Parse阶段就报错：unexpected . in identifier - 返回值最多两个，且第二个只能是
error（用于管道判断），如func LoadUser(id string) (User, error)
html/template 与 text/template 的 FuncMap 兼容性
二者底层共享同一套函数注册机制，FuncMap 可复用，但要注意使用场景：
- 渲染 HTML 页面必须用
html/template，否则{{.HTMLContent | safeHTML}}无效，且无法识别template.HTML类型 - 若用
html/template渲染 JSON/YAML，{、"会被转义成{、"，结果非法 —— 这种情况请切回text/template - 自定义函数里如果返回
template.HTML，必须用html/template；返回普通字符串则两者都可
最容易被忽略的是：函数是否导出、注册顺序是否在 Parse 前、以及传入数据的实际类型是否和函数签名完全一致——这三处任一出错，都不会给出清晰提示，只会表现为函数未定义或 panic。
