Gin需手动注入模板全局变量，因c.HTML()仅接受一次性data参数且不继承外部值；推荐用中间件存通用数据到c.Keys，并封装HTMLWithGlobal方法合并全局与业务数据。
Gin 没有内置的“模板全局变量”机制，必须手动注入，否则每次 c.HTML() 都得重复传一遍通用数据（比如站点名、当前用户、环境标识）。
为什么 c.HTML() 不能直接用全局变量？
Gin 的模板渲染是纯函数式调用：c.HTML(status, "name.html", data) 中的 data 是一次性的 gin.H（即 map[string]interface{}），它不自动继承任何上下文外的值。即使你在 global.App 或 viper 里存了 AppName，模板里写 {{ .AppName }} 也不会自动解析——除非你把它显式塞进第三个参数里。
最稳妥的注入方式：中间件 + 自定义 c.HTML() 封装
不要试图改 Gin 源码或用反射劫持模板引擎。推荐在路由层统一注入，同时保持原有 API 习惯：
- 写一个中间件，在
c.Next()前把通用变量挂到c.Keys上（例如c.Set("site_name", viper.GetString("app.app_name"))） - 再封装一个
c.HTMLWithGlobal()方法（通过扩展*gin.Context实现），内部自动合并全局变量和业务数据 - 模板里仍用
{{ .site_name }}，但数据来源已由你控制
示例（middleware/template.go）：
func GlobalTemplateData() gin.HandlerFunc {
return func(c *gin.Context) {
c.Set("site_name", viper.GetString("app.app_name"))
c.Set("env", viper.GetString("app.env"))
c.Set("year", time.Now().Year())
c.Next()
}
}
// 扩展方法（需在 main.go 初始化后注册）
func (c *gin.Context) HTMLWithGlobal(code int, name string, data gin.H) {
global := gin.H{
"site_name": c.MustGet("site_name").(string),
"env": c.MustGet("env").(string),
"year": c.MustGet("year").(int),
}
for k, v := range data {
global[k] = v
}
c.HTML(code, name, global)
}
使用时：c.HTMLWithGlobal(http.StatusOK, "index.html", gin.H{"title": "首页"})，模板中就能同时访问 {{ .title }} 和 {{ .site_name }}。
r.SetHTMLTemplate() + 自定义 template.FuncMap 的局限性
有人尝试用 template.FuncMap 注入函数来“动态取值”，比如 "getSiteName": func() string { return viper.GetString("app.app_name") }，然后在模板里写 {{ getSiteName }}。这看似省事，但要注意：
- 所有函数调用发生在模板渲染时，无法访问
*gin.Context，所以拿不到请求级信息（如当前登录用户、语言偏好） - 函数无缓存，高频访问下可能重复读配置、触发锁竞争
- 调试困难：错误堆栈指向模板行号，而非 Go 函数，排查成本高
- 不支持嵌套结构体展开（比如
{{ .user.Name }}），只能返回扁平值
容易被忽略的关键点
模板变量名冲突比想象中更常见。比如你往 data 里传了 gin.H{"env": "prod"}，而中间件也设了 c.Set("env", "dev")，最后合并时业务数据会覆盖全局数据——顺序很重要。建议在 HTMLWithGlobal 中固定「全局变量优先级低于业务数据」，避免意外覆盖；如果需要强制覆盖，就明确加前缀，比如 global_env 和 env 分开管理。
