html/template 自动转义失效时的上下文判断

如果你发现 html/template 输出的内容“没有按预期转义”，先别急着给字符串再套一层 html.EscapeString。多数情况不是自动转义失效，而是插值所在的上下文变了：普通文本、HTML 属性、URL、JavaScript 和 CSS 的编码规则本来就不同。

html/template 的判断顺序可以概括为：先确认导入的是安全的 HTML 模板包，再看 {{.}} 位于哪种上下文，最后检查传入值是不是普通字符串或被显式标记为可信类型。按这条路径排查，既能解释转义结果，也能处理 #ZgotmplZ 和模板解析错误。

真正的修复通常是把动态值放回正确的上下文，并让不可信数据保持普通 string。只有经过明确审核或可靠消毒器处理的内容，才考虑使用 template.HTML、template.URL 等可信类型。

先确认使用的是 html/template

text/template 和 html/template 的 API 很像，但安全职责不同。前者面向普通文本，不会自动保护 HTML 输出；后者专门生成 HTML 片段，会在解析模板时根据上下文补充内部转义步骤。网页响应、邮件 HTML 或 HTML 片段应优先使用后者。

package main

import (
    "html/template"
    "log"
    "os"
)

func main() {
    // 这里使用 html/template，让用户输入按 HTML 文本上下文处理。
    tmpl, err := template.New("page").Parse(`
{{.}}
`)
    if err != nil {
        log.Fatal(err)
    }

    // 普通 string 被视为不可信文本，尖括号不会直接成为 HTML 标签。
    if err := tmpl.Execute(os.Stdout, ``); err != nil {
        log.Fatal(err)
    }
}

常见误区是只看模板文件后缀，或者在业务代码中同时引入两个包并把别名混在一起。排查时直接看 import 路径和模板变量的实际类型；如果 HTML 响应使用了 text/template，那不是“上下文判断错了”，而是包选错了。

同一个值进入不同位置，结果为什么不一样

html/template 不是把所有字符统一替换成同一种实体。它识别 HTML 文本、属性、URL、JavaScript 和 CSS 等上下文，并为动作管道加入相应处理。比如普通文本主要关注标签边界，href 还要关注协议，脚本字符串则要避免破坏 JavaScript 的引号和语法边界。

可以把下面几类位置作为快速判断表：

用最小示例区分普通字符串和危险 URL

下面的示例把三个插值放在不同位置。输入值只是一段普通字符串时，文本和属性会按各自上下文编码；当 URL 值带有不安全协议时，包会过滤它，而不是照原样放进链接。

package main

import (
    "html/template"
    "log"
    "os"
)

type PageData struct {
    Text string
    Link string
}

func main() {
    const page = `
{{.Text}}
  打开
`

    tmpl, err := template.New("page").Parse(page)
    if err != nil {
        log.Fatal(err)
    }

    data := PageData{
        // 普通文本应保持 string，让模板包负责编码。
        Text: `用户输入`,
        // 不安全协议会在 URL 上下文被过滤，而不是变成可执行链接。
        Link: `javascript:alert(1)`,
    }
    if err := tmpl.Execute(os.Stdout, data); err != nil {
        log.Fatal(err)
    }
}

如果输出中出现 #ZgotmplZ，它通常是一个有意的安全信号：动态值进入了 CSS 或 URL 上下文，但内容不符合允许的协议或语法。不要把这个占位值当成网络故障，也不要用字符串替换把它改回原始 URL；应先确认这个字段是否真的应该允许动态协议。

手动转义为什么可能让问题更复杂

在 html/template 中，很多人会继续写 {{. | html}} 或 {{. | urlquery}}，希望“再保险一次”。这会让上下文信息和业务意图变得不清楚，甚至触发模板解析错误或产生双重编码。优先把值放在正确的 HTML 位置，让包自动选择编码；只有在确实处理纯文本输出时，才在业务边界使用明确的转义函数。

另一个误区是把 template.HTML 当作“关闭转义”的快捷方式。它表示调用者声明这段内容已经是可信 HTML 片段，模板会把它原样纳入输出。这个声明不会替你清理用户提交的标签、属性或脚本，因此不能直接套在数据库字段、评论内容或外部接口返回值上。

可信类型应该放在哪个边界

当业务确实需要输出由服务器生成的安全片段，可以把“生成或消毒”和“渲染”分成两个边界：前一个边界负责证明内容来源和结构完整，后一个边界才接收 template.HTML 等类型。类型转换要集中、可读、容易审查，不要散落在模板执行前的各处。

package main

import (
    "html/template"
    "log"
    "os"
)

type ViewData struct {
    // SafeHTML 只能来自受控的服务端片段，不能直接接收用户输入。
    SafeHTML template.HTML
    Message  string
}

func main() {
    tmpl := template.Must(template.New("view").Parse(`
{{.SafeHTML}}
  
{{.Message}}
`))

    data := ViewData{
        // 这是示例中的固定片段；真实项目应由可信生成器或审核过的消毒器提供。
        SafeHTML: template.HTML(`服务端生成的标签`),
        // 用户可见文本仍保持普通 string，不能借安全类型绕过编码。
        Message: ``,
    }
    if err := tmpl.Execute(os.Stdout, data); err != nil {
        log.Fatal(err)
    }
}

同理，template.URL、template.JS 等类型也都带有“内容已经经过信任判断”的含义。尤其是 template.JS，不能把任意 JSON 字符串或用户输入直接转换进去；需要传递结构化数据时，应先解析成 Go 值，再让模板在 JavaScript 上下文中生成安全的 JSON 表示。

把“自动转义失效”拆成五个问题

1. 导入路径是不是 html/template，而不是 text/template？
2. 插值点属于 HTML 文本、属性、URL、JavaScript 还是 CSS？预期编码是否与该上下文匹配？
3. 传入值的动态类型是不是 template.HTML、template.URL 等可信类型？如果是，谁做了信任判断？
4. 是不是手动追加了 html、urlquery 等管道，导致重复处理或解析错误？
5. 是不是把 #ZgotmplZ 当成应该被替换掉的错误文本，而没有回到 URL 或 CSS 的协议边界检查？

最终原则很简单：模板作者负责结构，执行时传入的数据默认不可信；普通数据交给上下文自动转义，可信类型只在经过清晰审核的边界上出现。这样看到“输出变了”时，先解释上下文，再决定是否修改数据类型，排查结果通常比继续叠加转义函数更稳定。

相关问题

为什么 html/template 输出的 JSON 看起来有转义字符？

因为 JSON 被放入 JavaScript 或 HTML 上下文时还要满足对应语法边界。应把结构化 Go 值交给模板处理，不要把已经拼好的 JSON 字符串直接标记成 template.JS。

看到 ZgotmplZ 能不能直接改成空字符串？

不建议。它表示上下文过滤发现了不安全值；应该检查 URL 或 CSS 的允许协议和数据来源，再决定业务上是否允许这个链接。

什么时候可以使用 template.HTML？

只有当内容来自可信的服务端生成逻辑，或已经经过可靠的 HTML 消毒并确认结构完整时才考虑使用。用户输入本身不满足这个条件。