推荐统一用r.LoadHTMLGlob("templates/*.html")显式限定后缀防误加载，分层目录建议按子目录分批glob；必须先构造带FuncMap的*template.Template再调用r.SetHTMLTemplate()，最后LoadHTMLGlob()；路径问题应优先使用embed.FS打包模板与静态资源，确保跨环境一致性。
模板文件怎么加载才不会漏、不重复
直接用 r.LoadHTMLFiles() 加单个文件容易漏加，尤其新增模板时忘记补调用；用 r.LoadHTMLGlob("templates/**") 又可能误加载备份文件（比如 index.tmpl.bak）或隐藏文件，导致启动报错或渲染异常。
推荐做法是统一用 r.LoadHTMLGlob("templates/*.html") 或 r.LoadHTMLGlob("templates/*/*.html")，显式限定后缀，避免匹配到非模板文件。如果目录结构分层明确（如 templates/admin/, templates/user/），建议按子目录 glob 分批加载，方便后续做模板隔离或权限控制。
- 不要在多个地方重复调用
LoadHTMLGlob—— Gin 的模板引擎只允许加载一次，第二次会 panic 报"html/template: cannot Parse after Execute - 确保模板路径是相对
os.Executable()所在目录的，不是相对main.go；本地开发常用os.Chdir()或硬编码绝对路径易出错，建议用embed.FS（Go 1.16+）打包进二进制
如何在 Handler 中安全传参并避免 nil panic
c.HTML() 第三个参数必须是非 nil 的 interface{}，但很多人习惯传 nil 或空 struct，结果运行时报 template: xxx: nil data。更隐蔽的是传了 map 但 key 不存在，模板里 {{.User.Name}} 会静默渲染为空字符串，而不是报错，调试时很难发现字段缺失。
建议始终用具名 struct 传参，配合 Go 的零值语义和模板的 with/if 控制：
type IndexData struct {
Title string `json:"title"`
User *User `json:"user,omitempty"`
Items []Item `json:"items"`
}
// 模板里写 {{with .User}} {{.Name}} {{end}}，不会因 User == nil 崩溃
- 避免用
gin.H动态 map，它绕过编译检查，字段拼错、类型错只能靠运行时暴露 - 如果必须用 map，至少加一层包装函数做 key 存在性校验，比如
safeGet(m, "user.name") - 模板中访问嵌套字段前，先用
{{if .User}}判断，别依赖“默认不报错”
自定义模板函数为什么注册后不生效
常见错误是把 template.FuncMap 传给 LoadHTMLFiles 或 LoadHTMLGlob 之后，又忘了调用 r.SetHTMLTemplate()；或者在 LoadHTMLGlob 之后再调用 template.New().Funcs()，但 Gin 已经用默认 template 实例加载完了。
正确顺序只有一种：先构造带函数的 *template.Template，再用 r.SetHTMLTemplate() 注入：
tmpl := template.Must(template.New("").Funcs(template.FuncMap{
"formatTime": func(t time.Time) string { return t.Format("2006-01-02") },
}))
r.SetHTMLTemplate(tmpl)
r.LoadHTMLGlob("templates/*.html")
- 函数名首字母必须大写，否则模板里调用
{{formatTime .CreatedAt}}会报function "formatTime" not defined - 所有自定义函数必须是可导出的（首字母大写），且参数/返回值类型要能被
text/template序列化 - 别在中间件或 handler 里动态改
template.FuncMap—— 它是全局共享的，改了会影响所有模板
静态文件和模板混放时路径怎么理清楚
很多人把 static/css/ 和 templates/ 都放在项目根目录，然后用 r.Static("/static", "static") 和 r.LoadHTMLGlob("templates/*")，结果部署时发现线上模板路径对不上，或者静态资源 404 —— 根本原因是 Static 和 LoadHTMLGlob 的路径参数都是相对于当前工作目录（os.Getwd()），而它在不同环境（IDE 启动 / systemd / Docker）下可能完全不同。
最稳的方式是统一用 embed.FS 打包所有前端资源：
import _ "embed"
<p>//go:embed templates/*
var templatesFS embed.FS</p><p>//go:embed static/*
var staticFS embed.FS</p><p>func main() {
r := gin.Default()
r.StaticFS("/static", http.FS(staticFS))
tmpl := template.Must(template.New("").ParseFS(templatesFS, "templates/*"))
r.SetHTMLTemplate(tmpl)
}
- 这样编译后二进制自带全部资源，不依赖外部文件系统，彻底规避路径问题
- Docker 构建时不用再 COPY 模板和静态文件，
FROM golang:alpine编译完直接FROM scratch运行 - 注意
embed.FS不支持通配符递归（**），多级目录需显式写templates/admin/*,templates/user/*
实际项目里最容易被忽略的，是模板函数的并发安全性 —— 如果你在函数里用了全局变量或缓存，没加锁，高并发下数据会错乱。还有就是 embed.FS 的路径必须是字面量字符串，不能拼接变量，否则编译失败。
