Go html/template 怎样排查模板变量被转义

先判断数据原值、模板位置和最终观察对象。普通字符串中的标签被 html/template 编码通常是正常行为；原值已经含实体时，可能又编码了实体的 &；URL 位置出现 #ZgotmplZ 则应检查上下文过滤。不要为了让标签生效，把所有变量统一转成 template.HTML。

官方地址：https://pkg.go.dev/html/template

用一个小程序同时观察几种输入

在一个已有 Go 环境的独立目录保存 main.go。示例只依赖标准库，把结果写到内存后输出源码，不启动服务器。数据全部是本次构造的固定样例，代码未在本文制作过程中执行，后文说明的是按语义推导的表现。

package main

import (
    "bytes"
    "fmt"
    "html/template"
    "log"
)

func main() {
    // 模板由程序维护；三个位置分别是正文、普通属性和 URL
    const page = `
{{.Text}}
{{.Encoded}}
提示
链接
{{.Trusted}}
`

    data := struct {
        Text    string
        Encoded string
        Title   string
        Link    string
        Trusted template.HTML
    }{
        Text:    "记录",
        Encoded: "记录",
        Title:   `A "quote" & note`,
        Link:    "custom:demo",
        // 仅演示程序内固定、可信的 HTML，不接收用户或接口内容
        Trusted: template.HTML("固定说明"),
    }

    t, err := template.New("page").Parse(page)
    if err != nil {
        log.Fatal(err)
    }
    var out bytes.Buffer
    // 先写缓冲区；执行失败时不交付一半 HTML
    if err := t.Execute(&out, data); err != nil {
        log.Fatal(err)
    }
    fmt.Print(out.String())
}

这里特意把 Text 和 Encoded 分开：前者包含原始标签字符，后者包含已经编码成实体的文本。Trusted 只放程序内固定的可信片段，用来展示显式信任和普通字符串的区别，不能把它替换为未经处理的请求参数。

看到实体时，先区分源码和页面文字

模板输出是 HTML 源码，浏览器显示的是解析后的页面。Text 对应的原始标签会作为文字表达，而不是让 em 元素生效。查看输出源码时会看到实体，这与页面上显示字面量标签是同一件事的两个观察层面。

Encoded 的值本来就写着实体。模板又把其中的 & 当成普通文本编码，所以输出源码会出现 < 这类片段，页面上可能看见 < 的字面文字。排查时应先追到数据进入模板之前的内容，看看是否在数据库写入、接口转换或视图模型组装时提前做了 HTML 编码。

不能只根据页面里有一个 & 就认定编码重复。用户原本也可能要展示实体写法。应先明确字段语义：是普通文字、供人阅读的代码片段，还是已被可信处理的 HTML 内容，再决定哪一层负责输出编码。

属性变化和 #ZgotmplZ 是同一种问题吗？

html/template 根据 HTML 位置实施上下文处理。普通属性中的引号或 & 需要相应编码，不能因为它与正文的输出不同就判定异常。示例里的 title 属性展示的是字符串作为属性数据使用，并不是动态拼接属性语法。

Link 使用一个不受普通 URL 过滤器接受的自定义协议样例 custom:demo，因此应关注 href 的过滤结果。#ZgotmplZ 是需要回看数据和上下文的信号，不是模板变量丢失，也不应通过删除该字符串“修复”。若业务确实需要某类链接，应先明确允许的来源和协议，再设计符合要求的输出路径。

不要换成 text/template 来逃避 HTML 编码。两个包虽然接口相近，输出 HTML 时仍应保留 html/template 的上下文处理。本文不扩展脚本或样式模板的全部规则；遇到那些位置应查对应上下文，而不是复制正文里的处理方式。

重复转义和可信富文本分别怎样处理？

普通文字字段通常以未做 HTML 输出编码的形式交给模板，由展示层根据上下文处理。若历史数据确实经过预编码，先确认数据格式契约和来源，再在明确边界设计迁移或适配；不要在模板末尾对所有内容反复解码。

需要展示富文本时，先把来源、允许内容及清理策略确定下来，再让经过可信处理的结果进入专用字段。template.HTML 的含义是开发者声明该值可信，而不是调用了一个 HTML 清洗器。示例仅使用固定常量，因此其信任依据清楚；来自编辑器、数据库或接口的字符串不会仅因存放位置改变就自动可信。

也不建议加一个通用“safe”模板函数，把任意字符串直接转换成可信类型。这样的名字容易掩盖实际行为，导致调用方以为它做过检查。若确需专用可信字段，应让类型和字段名表达用途，并把信任建立的位置留在可追踪的代码中。

放进项目时怎样判断问题已定位？

读者可在隔离示例目录使用下面命令查看输出；这里不附虚构运行日志。

# 只运行当前 main.go，观察标准输出中的 HTML 源码
go run main.go

集成回项目时，先选一个不含个人信息的代表性字段，记录其模板前格式与输出位置。若普通文字能按原本意思显示、没有多余预编码，且需要富文本的字段有独立可信处理路径，就比“实体数量减少了”更能说明问题被定位。诊断时避免把完整用户正文直接写进日志。

模板执行可能在报错前写出部分内容，示例先写 bytes.Buffer，只在执行成功后输出。放到 HTTP 项目时，也应按自己的响应策略处理模板错误，不能把缓冲区写法当成所有网络错误的兜底。

常见问题

标签变成可见文字，是 html/template 出错了吗？普通字符串本来就按数据处理。先确认你需要显示文字还是可信 HTML，不能仅凭标签没生效判断故障。

数据库中的内容能直接转成 template.HTML 吗？不能只凭“来自数据库”建立信任。要回看最初来源与内容处理过程。

预先调用 HTML 编码函数更保险吗？对交给 html/template 的普通文字，额外预编码可能导致重复编码。应保持字段格式契约清楚，而不是在各层叠加相同操作。

有实体输出就说明绝对安全吗？不能。模板内容应由可信作者维护，变量所在上下文和显式可信类型也会影响处理；不能用肉眼看到几个实体替代完整信任设计。

参考：Go html/template 官方文档：上下文转义、类型与错误。