必须在调用 parse 或 parsefiles 前通过 funcs 方法注册自定义函数，funcmap 是 map[string]interface{}，值必须是符合模板约束的函数，返回 template.html 才能绕过 html 转义，且应统一初始化避免重复定义。
怎么注册自定义函数到 template.FuncMap
直接在调用 template.New() 或 template.ParseFiles() 前，把函数映射传进去就行。关键不是“怎么加”，而是“加的位置必须早于模板解析”——如果先 Parse 再 Funcs，函数根本不会生效。
常见错误是写成这样：
t := template.New("test")
t.Parse("{{ now }}") // 此时还没注册函数，报错 undefined function "now"
t.Funcs(template.FuncMap{"now": func() string { return time.Now().Format("2006-01-02") }})
正确顺序是：
funcs := template.FuncMap{
"now": func() string { return time.Now().Format("2006-01-02") },
"add": func(a, b int) int { return a + b },
}
t := template.New("test").Funcs(funcs)
t.Parse("{{ now }} {{ add 2 3 }}") // ✅
-
FuncMap是map[string]interface{}，value 必须是函数（不能是方法、闭包捕获了不可序列化变量也容易出问题） - 函数参数和返回值类型受模板引擎限制：只支持基本类型、指针、结构体、切片、map；不支持 channel、func 类型
- 函数名区分大小写，
"Now"和"now"是两个不同函数
为什么 template.FuncMap 里的函数不能访问外部变量
因为模板执行时，函数是被反射调用的，没有闭包上下文。如果你写 func() string { return username } 并试图捕获外层变量，编译期不会报错，但运行时可能 panic 或返回空值——尤其在并发渲染多个模板时，变量状态不可控。
安全做法是把依赖显式传入：
funcs := template.FuncMap{
"userLink": func(name, host string) string {
return fmt.Sprintf("<a href="https://%s/%s">%s</a>", host, url.PathEscape(name), name)
},
}
- 所有输入都靠模板传参，比如
{{ userLink .Name .Host }} - 如果真需要全局配置（如站点 base URL），建议封装成结构体方法，再通过
.Site.BaseURL这类方式传入数据，而不是塞进 FuncMap - 避免在 FuncMap 函数里做 I/O（如查数据库、读文件），模板渲染应尽量无副作用
HTML 模板中自动转义怎么绕过又不破坏安全
默认情况下，{{ .Content }} 会 HTML 转义，但你写的函数返回字符串也会被转义——比如 userLink 返回带 <a></a> 的字符串，结果页面显示的是字面量 <a>。
解决办法只有一个：让函数返回 template.HTML 类型：
import "html/template"
funcs := template.FuncMap{
"userLink": func(name, host string) template.HTML {
return template.HTML(fmt.Sprintf("<a href="https://%s/%s">%s</a>", host, url.PathEscape(name), name))
},
}
- 必须是
template.HTML，不能是string强转，否则无效 - 别滥用：只对明确可信、已做过 XSS 过滤的内容返回
template.HTML - 如果函数逻辑复杂（比如要渲染子模板），可用
template.HTMLTemplate，但更推荐用define+template指令组合，而非在 FuncMap 里拼 HTML
多个模板共享同一套 FuncMap 怎么组织才不重复
不要每个 template.New() 都重新定义一遍 FuncMap。典型错误是分散在各个 handler 里重复写 Funcs(...)，既难维护又容易漏配。
推荐做法：统一初始化一个全局变量或私有构造函数：
var commonFuncs = template.FuncMap{
"now": func() string { return time.Now().Format("2006-01-02") },
"safe": func(s string) template.HTML { return template.HTML(s) },
"title": strings.Title,
}
func NewHTMLTemplate(name string) *template.Template {
return template.New(name).Funcs(commonFuncs)
}
// 使用
t := NewHTMLTemplate("index").ParseFiles("index.html")
- 如果项目用了子模板（
{{ template "header" }}），确保所有子模板都用同一个*template.Template实例或其克隆（Clone()），否则 FuncMap 不继承 - 注意
template.Must(t.Parse(...))里的t必须已调用Funcs，否则 panic 信息里看不到函数缺失提示，只报 “undefined function” - FuncMap 本身不可并发写，但读是安全的；所以初始化一次后，多 goroutine 调用没问题
template.HTML 的类型精确性，写错一个字符（比如返回 string 却以为能绕过转义），就会卡半天。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
