必须用html/template渲染HTML页面以防XSS，text/template仅适用于纯文本；前者自动上下文感知转义并校验HTML结构，后者无转义、不校验，混用将导致漏洞或乱码。
模板选错：html/template 和 text/template 混用导致 XSS 或乱码
生成报告时若输出目标是浏览器 HTML 页面，必须用 html/template；若是纯文本报告（如日志、CSV、配置片段），才用 text/template。两者 API 一致，但转义逻辑完全不同：html/template 会识别 <script>、onclick=、href="javascript:" 等上下文并做针对性转义；text/template 只做基础实体替换（如 & → &），用它渲染网页等于裸奔。
常见错误现象：用户输入含 <b>加粗</b> 的字段，页面直接显示标签而非加粗效果；或更糟——插入 <img src="https://img.php.cn/" alt="如何在Golang语言学习中实现基于模板引擎的动态报告生成"> 触发执行。
- 检查 import 是否为
"html/template"（非"text/template"） - 若报告最终写入文件且供人阅读（如 README.md、SQL 脚本），可用
text/template；但只要内容可能被浏览器解析，一律用html/template - 别试图“手动拼接 HTML 字符串 +
template.HTML”绕过转义——除非你 100% 控制输入源，否则仍是 XSS 温床
ParseFiles 找不到模板文件：工作目录 ≠ 项目根目录
template.ParseFiles("templates/report.html") 失败不是因为路径写错，而是 Go 进程当前工作目录（os.Getwd()）不等于你的源码所在目录。尤其是用 go run main.go 时，工作目录是执行命令的路径；构建后二进制运行时，工作目录更是随意。
错误信息典型为：open templates/report.html: no such file or directory。
立即学习“go语言免费学习笔记（深入）”；
- 最稳方案：用
filepath.Join(filepath.Dir(os.Executable()), "templates", "report.html")定位二进制同级的templates/目录 - 次选方案：启动时传入绝对路径参数，或通过环境变量（如
REPORT_TEMPLATES_DIR）指定 - 避免
./templates/...这类相对路径——它在go build后必然失效 -
ParseFiles返回非 nil error 时必须处理，它不会静默跳过缺失文件
Execute 前漏设 Content-Type 或 data 为 nil 导致 panic
把模板写入 http.ResponseWriter 时，如果没提前设置 header，可能触发 panic 或浏览器解析失败；传入 nil 数据则必定 panic。
典型错误：直接 tmpl.Execute(w, data)，结果浏览器显示空白，服务端 log 出现 write tcp ...: broken pipe 或 nil pointer dereference。
- HTTP 场景下，务必在
Execute前调用w.Header().Set("Content-Type", "text/html; charset=utf-8") -
data不能为nil——空结构体（struct{}{}）或空 map（map[string]interface{}{}）可接受，但nil *MyStruct会 panic - 若报告导出为文件，写入
*os.File时无需设 header，但需确保文件已os.Create且无权限问题
嵌套模板传参混乱：{{template "name" .}} 中的点不是全局变量
用 {{define "header"}}...{{end}} 定义子模板后，{{template "header" .}} 的 . 是当前作用域完整数据，不是顶层变量池。很多人误以为子模板能自动访问 $.Title，其实只有在 range 内部才需 $ 回溯。
常见症状：子模板里 {{.Title}} 显示为空，但主模板中 {{.Title}} 正常。
- 子模板接收的数据完全取决于
{{template "name" xxx}}中的xxx表达式 - 想传部分字段？用
{{template "header" (dict "Title" .Title "Version" .Version)}}（需先注册dict函数），或改用with：{{with .HeaderData}}{{.Title}}{{end}} - 所有
{{define}}名称在同一个*template.Template实例中全局唯一，多个ParseFiles共享同一实例时重名会覆盖
真正麻烦的是跨模板复用逻辑——比如日期格式化、金额千分位，得靠自定义函数注册到 FuncMap；而这类函数若带副作用（如修改全局状态、IO），会在并发渲染时引发不可预测问题。别让模板函数做业务计算，只做纯转换。
