c.HTML() 不支持传函数，因其数据参数仅接受 map[string]interface{} 或结构体，Go 模板引擎禁止运行时注入函数以保障安全；必须通过 gin.Engine.SetFuncMap() 在加载模板前全局注册首字母大写的导出函数。
为什么不能在 c.HTML() 里传函数
因为 c.HTML() 的数据参数只接受 map[string]interface{} 或结构体，Go 模板引擎禁止在运行时动态注入函数值——这是安全机制，不是 Gin 的限制。你试图往数据里塞一个 func(int) string，Go 会直接 panic：template: can't evaluate field XXX in type interface{}。
SetFuncMap 是唯一合法入口
gin.Engine.SetFuncMap() 是注册自定义模板函数的唯一通道，它接收一个 template.FuncMap（本质是 map[string]interface{}），且必须在 r.LoadHTMLGlob() 之前调用，否则函数不会生效。
- 函数必须首字母大写（导出），签名要严格匹配模板调用方式，比如
func(int64) string就不能接收string参数 - 所有函数共享同一个 FuncMap 命名空间，重复注册同名函数会静默覆盖
- 不支持按路由或模板文件做局部注册，全局生效是设计前提
批量注册多个函数的实操写法
把函数集中定义、统一注册，比零散 r.SetFuncMap(...) 多次调用更可靠。常见错误是漏掉某个函数、类型不一致、或注册时机错位。
func main() {
r := gin.Default()
// ✅ 批量定义
funcMap := template.FuncMap{
"formatTime": func(t int64) string {
return time.Unix(t, 0).Format("2006-01-02 15:04")
},
"md5sum": func(s string) string {
h := md5.Sum([]byte(s))
return hex.EncodeToString(h[:])
},
"truncate": func(s string, n int) string {
if len(s) <= n {
return s
}
return s[:n] + "..."
},
}
// ✅ 一次性注册（必须在 LoadHTMLGlob 之前）
r.SetFuncMap(funcMap)
r.LoadHTMLGlob("templates/*")
r.GET("/", func(c *gin.Context) {
c.HTML(http.StatusOK, "index.html", gin.H{
"now": time.Now().Unix(),
"text": "hello world",
})
})
r.Run()
}
模板中调用：{{formatTime .now}}、{{md5sum .text}}、{{truncate .text 5}}。
容易被忽略的兼容性细节
Go 版本升级后，template.FuncMap 对函数返回值的要求更严格：若函数返回多个值（如 (string, error)），模板只会取第一个，且第二个值会被丢弃——但不会报错，容易误以为“函数没生效”。
- 所有自定义函数应只返回单个可模板渲染的值（
string、int、bool或template.HTML） - 若需错误处理，应在函数内部兜底（比如返回空字符串或默认值），而不是向外暴露
error - 模板里调用时传参类型必须和函数声明完全一致，
{{formatTime "123"}}会 panic，因为期待的是int64
