template.ParseFiles失败主因是工作目录不匹配，应改用filepath.Join拼接绝对路径或embed.FS；html/template中字段须首字母大写才可访问；多模板需同一实例解析；Execute时data为nil会panic，须校验或用with/if兜底。
template.ParseFiles 读取文件失败的常见原因
直接调用 template.ParseFiles 报错 open xxx.html: no such file or directory，大概率不是模板语法问题，而是工作目录不匹配。Go 程序默认以 os.Getwd() 返回的路径为基准查找文件，而 IDE 运行、go run、构建后二进制执行时当前目录可能完全不同。
- 硬编码相对路径（如
"templates/index.html"）在go run main.go时指向的是main.go所在目录；但若从其他目录执行该命令，就会失败 - 推荐改用
filepath.Join拼接基于os.Executable()或runtime.Caller获取的绝对路径，或统一使用嵌入式文件系统（Go 1.16+ 的embed.FS） - 开发期可临时加一句
log.Println("cwd:", os.Getwd())快速验证路径是否符合预期
html/template 中 {{.}} 和 {{.Name}} 渲染空白或报错
html/template 默认对所有输出做 HTML 转义，且字段访问严格遵循 Go 结构体导出规则：只有首字母大写的字段（即导出字段）才能被模板访问。如果结构体字段是小写（如 name string），{{.Name}} 会静默为空，{{.}} 可能输出 <no value>。
- 确保传入模板的数据是导出结构体指针或值，字段名首字母大写（如
Name string） - 若需渲染原始 HTML（比如后台存的富文本），用
{{.Content | safeHTML}}，并提前在模板中注册函数：funcMap := template.FuncMap{"safeHTML": func(s string) template.HTML { return template.HTML(s) }} - 调试时可在模板开头加
{{printf "%#v" .}}查看实际传入数据的结构和字段可见性
多模板共用时 template.New 和 template.ParseFiles 的组合陷阱
想复用同一个 *template.Template 实例加载多个文件，但误用 t, _ := template.New("base").ParseFiles("a.html", "b.html")，会导致只有最后一个文件（b.html）的内容生效——因为 ParseFiles 内部对每个文件都调用 template.New(name)，而 name 来自文件名，最终只保留最后一个解析结果。
- 正确做法是先创建主模板，再用
ParseFiles或ParseGlob加载全部文件：t := template.New("base"); t, _ = t.ParseFiles("layout.html", "index.html", "partial/header.html") - 若需显式定义子模板（如
{{define "header"}}），必须确保所有含define的文件都被同一*template.Template实例解析过，否则{{template "header"}}会报template: "header" is not defined - 避免在 HTTP handler 中反复调用
ParseFiles，应预编译好模板实例并复用，否则每次请求都重新读磁盘+解析，性能极差
HTTP handler 中执行 Execute 时 panic: runtime error: invalid memory address
典型错误信息是 panic: runtime error: invalid memory address or nil pointer dereference，通常发生在调用 t.Execute(w, data) 时，data 是 nil 且模板里又直接访问了字段（如 {{.User.Name}}）。
立即学习“go语言免费学习笔记（深入）”；
- Go 模板不支持空值安全链式访问（没有类似 JS 的
?.），{{.User.Name}}在.User == nil时直接 panic - 解决方式有三种：① 提前校验
data非 nil 并设默认值；② 在模板中用{{with .User}}{{.Name}}{{end}}；③ 使用{{if .User}}{{.User.Name}}{{end}} - 更稳妥的做法是在 handler 开头统一处理：
if data == nil { data = struct{}{} }，再配合模板中{{if .Foo}}{{.Foo}}{{else}}—{{end}}显式兜底
func renderTemplate(w http.ResponseWriter, t *template.Template, name string, data interface{}) {
w.Header().Set("Content-Type", "text/html; charset=utf-8")
if err := t.ExecuteTemplate(w, name, data); err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
log.Printf("template execute error: %v", err)
}
}
嵌套模板、动态数据、路径管理这三块最容易出问题，尤其当项目从单文件 demo 扩展到多页面+布局+组件时，早期没约束的路径和数据结构会迅速变成维护负担。建议从第一天就固定模板根目录、用 embed.FS 封装、所有 handler 统一走预编译模板实例。
