应优先使用 html/template 渲染 HTML 内容以防止 XSS，text/template 适用于配置、CLI 等非 HTML 场景；二者语法兼容但注册表隔离；推荐 embed.FS 替代 ParseFiles/ParseGlob；自定义函数须在 Parse 前注册；safeHTML 需谨慎使用，应结合白名单过滤。
Go 标准库 text/template 和 html/template 足够应对绝大多数服务端模板渲染需求，无需引入第三方引擎——除非你明确需要模板继承、自动转义开关、或跨语言模板复用。
什么时候该用 html/template，而不是 text/template
核心区别在输出安全：只要最终渲染结果会嵌入 HTML 页面（比如生成响应体、邮件正文、前端片段），必须用 html/template；它会在插值时自动对 <、>、"、'、& 做 HTML 实体转义，防止 XSS。
- 用
text/template的典型场景：生成配置文件、CLI 输出、SQL 拼接（需格外谨慎）、日志模板 - 用
html/template的典型场景：HTTP handler 中返回 HTML 响应、生成带用户输入的邮件内容 - 二者语法完全兼容，仅安全策略不同；混用会导致
template: xxx: "xxx" is not defined for template "yyy"类错误——因为它们维护独立的模板注册表
template.ParseFiles() 与 template.ParseGlob() 的路径陷阱
这两个函数都要求路径是相对于**当前工作目录**（即运行 go run 或二进制时的 pwd），不是相对于源码文件位置。本地开发可能正常，部署后常因工作目录变化导致 open xxx: no such file or directory。
- 推荐统一用
embed.FS+template.ParseFS()（Go 1.16+）：把模板打包进二进制，路径相对go:embed注释位置 - 若必须用文件系统，显式构造绝对路径：
filepath.Join(filepath.Dir(runtime.Caller(0)), "templates", "*.html") -
ParseGlob("templates/*.html")不会递归匹配子目录；要支持嵌套，得写两次：ParseGlob("templates/**/*.html")（需 Go 1.19+）或手动遍历
自定义函数必须在 Parse 前注册
模板函数（如 dateformat、truncate）属于模板对象的元数据，一旦调用 Parse 或 ParseFiles，函数表就冻结了。之后再调用 Funcs 不生效，也不会报错，容易误以为函数已加载成功。
立即学习“go语言免费学习笔记（深入）”；
- 正确顺序：
t := template.New("name").Funcs(myFuncMap).ParseFiles(...) - 常见错误：先
template.ParseFiles()得到*template.Template，再链式调用.Funcs(...)—— 这实际新建了一个未解析的模板实例，原模板仍无函数 - 函数签名必须是可导出的：第一个参数可以是任意类型，但后续参数和返回值只能是 Go 基本类型、指针、切片、map 或接口；返回值建议至少两个：
interface{}, error，便于模板内用if检查
html/template 中的 safeHTML 不是万能解药
当确实需要插入未经转义的 HTML（比如 CMS 后台存的富文本），可用 {{ .Content | safeHTML }}，但它绕过所有安全机制，等同于信任该字段完全可控。生产环境滥用等于主动开后门。
- 更稳妥的做法：用
template.HTML类型接收数据（即在 Go 层提前转成该类型），而非依赖模板层转换 - 永远不要对用户输入直接调用
safeHTML；若必须支持富文本，应在入库前用bluemonday等库白名单过滤，再以template.HTML传入模板 - 注意：
safeHTML只影响当前插值；它不会让后续的{{ .OtherField }}也跳过转义
模板变量作用域、嵌套 range 中的 $ 引用、预编译缓存失效条件——这些细节不常触发问题，但一旦出错极难定位。上线前务必用真实数据跑通边界 case，尤其含空 slice、nil interface、嵌套 map 的场景。
