Gin中自定义HTML模板函数必须先调用router.SetFuncMap()再LoadHTMLGlob，因模板加载后缓存实例，SetFuncMap对已缓存模板无效；FuncMap函数参数返回值需符合html/template规则，支持基础类型、指针、导出字段，返回template.HTML可绕过转义，不支持多返回值或error。
Gin 中自定义 HTML 模板函数，核心在于 router.SetFuncMap() —— 它必须在模板加载前调用，否则函数不会生效。
为什么 SetFuncMap 必须放在 LoadHTMLGlob 之前？
Gin 的模板加载机制是：调用 LoadHTMLGlob 或 LoadHTMLFiles 时，会内部创建并缓存一个 *template.Template 实例；SetFuncMap 只影响后续新建的模板，对已缓存的模板无效。一旦模板已加载，再调用 SetFuncMap 就完全不起作用。
- 错误写法（函数不生效）：
LoadHTMLGlob→SetFuncMap→ 路由处理 - 正确顺序：
SetFuncMap→LoadHTMLGlob→ 路由处理 - 验证方式：模板里调用自定义函数报错
undefined function "xxx"，基本就是顺序错了
FuncMap 里函数签名有哪些限制？
模板函数参数和返回值类型受限于 html/template 的反射解析规则，不是任意 Go 函数都能用。
- 支持常见基础类型：如
string、int、int64、float64、bool、time.Time - 支持指针和结构体字段访问，但不能传入未导出字段（首字母小写）
- 返回值若需绕过 HTML 转义（比如渲染原始 HTML），必须是
template.HTML类型，例如：func() template.HTML { return template.HTML("<b>bold</b>") } - 不支持多返回值，也不支持
error类型返回（模板内无法处理 error 分支）
常见格式化需求对应函数示例
实际开发中高频场景有时间格式化、字符串安全输出、数值单位转换等，直接贴可用片段：
立即学习“前端免费学习笔记（深入）”；
func main() {
r := gin.Default()
// ✅ 必须先注册
r.SetFuncMap(template.FuncMap{
"formatTime": func(t time.Time) string {
return t.Format("2006-01-02 15:04")
},
"safeHTML": func(s string) template.HTML {
return template.HTML(s)
},
"kb": func(b int64) string {
return fmt.Sprintf("%.1f KB", float64(b)/1024)
},
})
// ✅ 再加载模板
r.LoadHTMLGlob("templates/**/*")
r.GET("/demo", func(c *gin.Context) {
c.HTML(200, "index.tmpl", gin.H{
"now": time.Now(),
"raw": "<em>italic</em>",
"size": int64(2048),
})
})
r.Run()
}
对应模板中写法：{{.now | formatTime}}、{{.raw | safeHTML}}、{{.size | kb}}
调试时容易忽略的两个细节
函数注册后仍报错或不生效，大概率卡在这两点：
- 模板文件名带路径时，函数名大小写必须严格匹配：比如注册了
"FormatTime"，模板里写{{.t | formattime}}就失败 - 函数体 panic 会导致整个模板渲染中断，且错误只打印在服务端日志，浏览器看到的是空页或 500；建议函数内加
recover或简单兜底，例如：if t.IsZero() { return "" }
真正麻烦的不是写函数，而是函数被 silently ignored —— 多半是顺序或类型没对上。
