Go html/template 输出内容和预期不同怎么办

处理思路很简单：先确认使用的是 html/template 还是 text/template，再看变量位于正文、属性、URL 还是脚本上下文。普通输入应继续按字符串输出；只有经过明确审核、确实代表 HTML 结构的内容，才在可信边界转换为 template.HTML。官方地址：https://pkg.go.dev/html/template。

html/template 的“输出和预期不同”多数是安全保护在工作。不要先换成 text/template，先定位上下文，再决定数据类型和修复边界。

先复现：标签为什么没有按标签渲染

先把问题缩小到一个正文动作。下面的代码只展示模板包、输入值和错误处理，不把示例输出当成截图或本机运行结果。

package main

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

func main() {
    // 正文动作接收普通字符串时，尖括号会按文本处理。
    const page = `
内容：{{.}}
`
    tmpl, err := template.New("page").Parse(page)
    if err != nil {
        // 解析失败要立即返回，避免拿不完整模板继续响应。
        log.Fatal(err)
    }

    value := "需要加粗的文字"
    // Execute 的数据参数来自调用方，不能因为它看起来像 HTML 就默认信任。
    if err := tmpl.Execute(os.Stdout, value); err != nil {
        // 输出失败也要保留错误，不能只返回半截页面。
        log.Fatal(err)
    }
}

在 html/template 中，value 是普通字符串，尖括号会被转义，浏览器看到的是文字而不是一个新的标签。这正是它与 text/template 的关键区别：前者面向 HTML，并假设模板作者可信、执行时传入的数据不一定可信。

内容：需要加粗的文字

为什么同一个值在不同位置会变样

模板动作不是脱离周围语法独立处理的。放在正文时，重点是 HTML 文本转义；放在 title 属性时，要处理引号和属性边界；放在 href 或脚本中，还要按 URL、JavaScript 等语境继续限制。

因此排查时不要只打印变量本身，要把模板中的实际位置一起记录。例如下面三个动作看似都写成 {{.}}，输出责任却不同：

{{.}}


提示


打开

如果 href 的数据含有不允许的协议或无法安全放入该位置，可能看到 #ZgotmplZ。这个值不是业务数据被随机替换，而是模板包在不安全 URL 上留下的安全占位结果。此时应检查数据来源和 URL 生成逻辑，不要把占位结果替换回原始字符串。

按可信边界选择修复方式

我在实际排查中会先把输入分成两类：用户填写的内容、接口返回的描述、日志摘要等默认是不可信字符串；程序内部经过固定模板生成并完成审核的片段，才可能进入可信 HTML 边界。两类数据不要共用一个“让标签生效”的开关。

package main

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

type ViewData struct {
    // PlainText 保持 string，让模板继续负责转义。
    PlainText string
    // TrustedHTML 只接收应用内部审核过的固定片段。
    TrustedHTML template.HTML
}

func main() {
    const page = `
用户内容：{{.PlainText}}
        
固定片段：{{.TrustedHTML}}
`

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

    data := ViewData{
        PlainText: "这段只能作为文字",
        // 这里的片段不是用户输入；真实项目应在更早的边界完成审核。
        TrustedHTML: template.HTML(`应用固定强调`),
    }
    // 输出错误仍然交给调用方处理，避免响应状态不完整。
    if err := tmpl.Execute(os.Stdout, data); err != nil {
        log.Fatal(err)
    }
}

template.HTML 的作用不是“关闭安全功能”，而是告诉模板系统这段值已经属于可信 HTML。把用户提交的字符串直接转换成它，会把转义责任从模板层移走，风险也随之扩大。更稳妥的做法是让业务字段继续使用 string，需要格式化时保存结构化数据，由模板决定标签；只有在固定片段确实经过审核时，才在边界处转换。

用四项清单收尾排查

如果只是希望用户看到富文本，优先把内容拆成标题、段落、链接等结构化字段，再由模板生成 HTML；如果确实需要接收有限标签，应在进入模板前使用明确的白名单清洗策略，并把清洗结果作为独立类型流转。不要把“页面看起来正常”当成安全结论。

几个容易混淆的问题

为什么不能直接换成 text/template？

text/template 不会替你完成 HTML 上下文转义。它可能让标签显示成结构，但也把输入安全责任全部推回调用方。只有输出本来就不是 HTML 时，才考虑它。

template.HTML 能解决所有“标签不生效”吗？

它只改变被标记值的信任类型，不能修复错误的模板位置、无效的 HTML 或业务数据拼接问题。更不能把外部输入未经审核地转换过去。

为什么 URL 输出成 #ZgotmplZ？

通常说明该值放进 URL 上下文后没有通过安全规则。回到 URL 的来源、允许协议和拼接方式排查，比手工替换占位字符串更可靠。

这次问题的落点不是“怎样让模板少转义”，而是“哪一类数据应该以什么可信度进入哪一个上下文”。只要保留 html/template 的安全边界，再用类型和结构化字段表达真正的富文本需求，输出差异就能从意外现象变成可解释的设计。