17370845950

text/template 渲染时变量未替换，因需显式传入导出结构体、map[string]interface{}或单值；HTML内容需用template.HTML类型避免转义。

text/template 渲染字符串时变量未被替换？检查数据传入方式

Go 的 text/template 不会自动展开局部变量或未命名字段，必须显式传入结构体、map 或单值。常见错误是直接调用 t.Execute(os.Stdout, nil) 却期望模板里写 {{

.Name}} 能生效——nil 没有字段，自然不渲染。

• 传结构体：确保字段是导出的（首字母大写），例如 type User { Name string }
• 传 map：键名需与模板中 {{.Name}} 一致，且 map 声明为 map[string]interface{}
• 传单值：若只渲染一个字符串，用 {{.}}，例如 t.Execute(w, "hello") 配合模板 "Say: {{.}}"

如何安全插入 HTML 内容而不被转义？用 template.HTML 类型

text/template 默认对所有 {{.}} 输出做 HTML 实体转义（如 → ），这是防 XSS 的默认行为。但如果你确定内容可信（比如后台拼接的 HTML 片段），不能靠 {{. | safeHTML}} ——那个函数属于 html/template，不是 text/template。

• 改用 html/template 包（推荐）：它识别 template.HTML 类型并跳过转义
• 若坚持用 text/template：无法关闭转义，也不应尝试绕过；它本就不是为 HTML 设计的
• 示例正确做法：

  import "html/template"
  
  t := template.Must(template.New("").Parse("{{.Body}}"))
  data := struct{ Body template.HTML }{Body: template.HTML("OK")}
  t.Execute(w, data)

模板中调用自定义函数失败？确认函数注册时机和签名

自定义函数必须在 Parse 之前注册，且函数签名必须符合 func(...interface{}) (interface{}, error) 或更具体的形式（如 func(string) string）。常见错误是注册后又调用 template.New() 创建新模板，导致函数丢失。

• 注册函数用 Funcs(map[string]interface{})，返回的是原模板对象，可链式调用
• 函数名在模板中不带括号，如 {{toUpper .Name}}，不是 {{toUpper(.Name)}}
• 参数数量必须匹配：定义为 func(int) string，模板里传字符串就会 panic
• 示例：

  t := template.New("").Funcs(template.FuncMap{
      "toUpper": strings.ToUpper,
      "add": func(a, b int) int { return a + b },
  })
  t.Parse("{{toUpper .Text}} + {{add 2 3}}")

嵌套模板（define / template）不生效？注意执行上下文和名称作用域

define 定义的模板不会自动执行，必须用 {{template "name" .}} 显式调用，且传参决定子模板能访问的字段。容易忽略的是：子模板内部的 . 是你传进去的那个值，不是外层上下文。

• 避免重复定义同名模板：多次 Parse 会覆盖，建议一次性 ParseFiles 或用 Option("missingkey=error") 提前暴露问题
• 跨文件引用需用 template.Must(t.ParseGlob("*.tmpl")) 并确保 template 调用时名称完全匹配
• 调试技巧：在模板开头加 {{printf "DEBUG: %#v" .}} 查看当前作用域数据结构

实际项目中，最常卡住的是数据结构与模板字段名不一致、函数注册顺序错乱、以及误用 text/template 处理 HTML 场景。这些点一旦写错，错误信息往往不直接指向根源，得逐层检查传参路径和类型声明。