Golang模板引擎渲染HTML教程

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}} 会静默为空，{{.}} 可能输出 。

• 确保传入模板的数据是导出结构体指针或值，字段名首字母大写（如 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 模板不支持空值安全链式访问（没有类似 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 统一走预编译模板实例。