自定义模板函数必须在loadhtmlglob或loadhtmlfiles之前注册，因为gin首次加载模板时即完成编译并固化函数映射表，后续setfuncmap对已编译模板无效；函数签名须为导出类型且单返回值，返回template.html才能安全输出html。
必须在调用 LoadHTMLGlob 或 LoadHTMLFiles 之前注册自定义模板函数，否则运行时 c.HTML 渲染会 panic 报错“function not defined”。
为什么自定义函数要放在模板加载前？
Gin 的模板引擎在首次调用 LoadHTMLGlob 时就完成模板编译并固化函数映射表；后续注册的函数不会被已编译的模板识别。这不是延迟绑定，而是 Go html/template 底层机制决定的。
-
r.SetFuncMap(...)只影响之后新创建的模板实例，对已加载/已编译的模板无效 - 即使你 reload 服务，只要没重启进程，旧模板缓存仍在内存中
- 常见错误现象：
template: index.html:12: function "unixToTime" not defined
SetFuncMap 的正确写法与参数约束
函数签名必须严格匹配 Go 模板引擎要求：所有参数和返回值都得是导出类型（首字母大写），且不能有多个返回值（除非最后一个为 error）。
- ✅ 正确示例：
func(str string) template.HTML、func(t int64) string - ❌ 错误示例：
func(str string) (string, error)（多返回值不支持）、func(s *myStruct)（未导出类型） - 注册位置必须在
r.LoadHTMLGlob("templates/**/*")之前，顺序不可颠倒 - 若使用
template.Must(template.ParseFiles(...))手动构造模板，则需直接传入FuncMap给template.New(...).Funcs(...)
安全输出 HTML 内容的 safe 函数怎么写？
默认所有 {{ .content }} 都会被 HTML 转义，想原样渲染富文本或生成的 HTML 片段，必须用自定义函数绕过转义。
- 函数体必须返回
template.HTML类型（不是string），否则仍会被转义 - 示例代码：
r.SetFuncMap(template.FuncMap{ "safe": func(s string) template.HTML { return template.HTML(s) }, }) - 模板中调用：
{{ .rawHtml | safe }}，不是{{ safe .rawHtml }} - ⚠️ 注意：该函数完全关闭 XSS 防护，仅限可信内容使用，切勿直接透传用户输入
自带函数不够用？注意这些兼容性细节
Gin 没有新增模板函数，它复用 Go 标准库 html/template 的全部内置函数，但部分行为在 Gin 场景下容易踩坑：
-
index对map[string]interface{}取值时，key 必须是字符串字面量或变量，不能是表达式：{{index .data "user_name"}}✅，{{index .data (.prefix + "_name")}}❌（语法错误） -
eq支持多参数比较（{{eq .status 200 201}}），但所有参数类型必须一致，混用int和string会静默失败 -
printf格式化时间必须用 Go 时间布局字符串"2006-01-02"，不是"Y-m-d"，错写会导致空字符串输出 - 自定义函数无法在
{{define}}块内被子模板继承，每个{{template}}调用需单独传入数据或重注册
最常被忽略的是函数注册时机和 template.HTML 类型强制转换——这两点一旦出错，错误信息模糊且调试成本高，建议把 SetFuncMap 和 LoadHTMLGlob 放在同一初始化块里，用注释明确标出顺序依赖。
