Gin模板路径必须用正斜杠“/”，Windows下filepath.Join生成的反斜杠会被忽略导致空白页；LoadHTMLGlob和LoadHTMLFiles仅识别“/”，且模板名须与完整路径（含大小写）严格一致。
模板路径必须用正斜杠，不能用 filepath.Join
Gin 的 LoadHTMLGlob 和 LoadHTMLFiles 对路径分隔符敏感：只认 /，不认 \ 或系统默认分隔符。Windows 下用 filepath.Join("views", "admin", "user", "index.html") 会生成 views\admin\user\index.html，Gin 直接忽略——连报错都不会有，只是渲染空白页。
正确做法是手动拼接或用 strings.Join：
r := gin.Default()
r.LoadHTMLGlob("views/**/*")
// 或显式列出
r.LoadHTMLFiles(
"views/index.html",
"views/admin/user/list.html",
"views/admin/user/detail.html",
"views/public/footer.html",
)
- 所有路径以项目根目录为基准，开头不加
./也能识别，但加了也无害 -
**/*支持嵌套任意深度，但注意它不会递归加载子目录下隐藏文件（如_partial.html），需显式包含或改名 - 若用
LoadHTMLGlob("views/*/*.html")，只会匹配一级子目录，views/admin/user/这种二级结构不会被扫到
template name 必须与文件路径一致，且区分大小写
Gin 渲染时靠的是模板的注册名（即文件路径），不是文件名。比如 views/admin/user/profile.html 注册后的 name 就是 admin/user/profile.html，调用时必须写全：
c.HTML(http.StatusOK, "admin/user/profile.html", data)
常见错误：
- 写成
"profile.html"→ 报错template: "profile.html" is undefined - 写成
"admin/user/profile"（缺后缀）→ 同样报未定义 - Linux/macOS 下
"Admin/User/profile.html"和"admin/user/profile.html"是两个模板，混用导致 404
嵌套模板里 {{ template }} 的路径也是相对整个 views 根目录
假设你有 views/layouts/base.html，想在其中嵌入 views/partials/header.html：
{{ define "base" }}
<html>
<body>
{{ template "partials/header.html" . }}
{{ template "content" . }}
</body>
</html>
{{ end }}
关键点：
-
{{ template "partials/header.html" . }}中的字符串必须和LoadHTMLFiles加载进来的完整路径完全一致 - 不能写成
{{ template "./partials/header.html" . }}或{{ template "header.html" . }} - 如果
header.html没被LoadHTMLFiles或LoadHTMLGlob显式加载，template调用直接 panic，不提示缺失，只报 “template not defined”
调试模板加载失败最有效的办法：打印 engine.HTMLRender 的内部 map
Gin 不提供公开 API 查看已加载模板列表，但可以临时反射读取（仅开发期用）：
import "reflect"
// ...
r := gin.Default()
r.LoadHTMLGlob("views/**/*")
// 调试：查看实际加载了哪些模板名
t := reflect.ValueOf(r.HTMLRender).Elem().FieldByName("funcMap").MapKeys()
for _, k := range t {
fmt.Println("Loaded:", k.String())
}
这能立刻暴露路径拼写错误、大小写不一致、glob 未覆盖等问题。上线前删掉这段代码即可。
多级目录本身不难，难的是 Gin 对路径的“字面量匹配”逻辑——它不解析路径语义，只做字符串比对。漏掉一个斜杠、多一个点、大小写错一位，都会静默失败。
