页面里要输出一段由后台拼出来的富文本时，最容易踩的坑不是模板语法，而是把“想显示的 HTML”与“用户提交的字符串”混成同一种数据。Go 的 html/template 默认把数据当普通文本，并根据它所在的 HTML、属性、URL 或 JavaScript 上下文做转义；只有确实由可信代码构造的片段，才有理由考虑 template.HTML。

先让普通字符串走自动转义；只有经过严格白名单处理、来源可控的 HTML 片段，才把它标记为 template.HTML。类型转换不是消毒器，反而会关闭这一段内容的自动保护。

普通字符串为什么会被安全地当成文本

先看最小模板。这里的 Title 和 Body 都是普通字符串，模板作者没有声明它们可以改变页面结构。

package main

import (
    "html/template"
    "os"
)

const page = `
{{.Title}}
{{.Body}}
`

func main() {
    t := template.Must(template.New("page").Parse(page))
    data := struct {
        Title string
        Body  string
    }{
        Title: "欢迎页",
        Body:  "",
    }
    if err := t.Execute(os.Stdout, data); err != nil {
        panic(err)
    }
}

输出中的尖括号会变成 < 和 > 一类的实体，浏览器看到的是文字，不会把它重新解释为脚本标签。这里的关键不是手动调用某个转义函数，而是 html/template 在执行模板时读取了插值所在的上下文，最终把数据放回安全的 HTML文本。

同一个值放进属性和 URL，转义规则会发生变化

模板的安全边界跟插值位置绑定。把值放进 title 属性、href 查询参数和普通文本节点，不能用“统一替换尖括号”的思路判断是否安全。

const page = `{{.Value}}`

data := struct{ Value string }{
    Value: `O'Reilly: Go`,
}

普通文本节点更关注 HTML 特殊字符，属性还要保护引号边界，URL 查询参数则需要 URL 语义下的编码。这里把三个判断位置明确记成 文本节点、title属性 和 href查询。官方文档把这种行为称为 contextual autoescaping。实际排查时，先找出插值所在的上下文，再决定数据类型和允许的协议；不要看到输出变化就直接改成 template.HTML。

template.HTML 什么时候才是合理的最小配方

template.HTML 是一种 typed string。它告诉模板引擎：这段值已经是调用方认可的 HTML 结构，可以按 HTML 输出，而不是再次当成普通文本编码。

type PageData struct {
    TrustedNotice template.HTML
}

data := PageData{
    TrustedNotice: template.HTML("系统维护窗口已确认"),
}

const page = `
{{.TrustedNotice}}
`

这段写法的前提是字符串来自可信的常量、经过可靠白名单过滤的结果，或由程序自己拼接且每个动态字段都已单独编码。不能把表单内容、评论内容或外部接口返回值直接转换成 template.HTML。如果只是想显示用户输入里的换行，优先存纯文本，在模板或 CSS 层解决展示，而不是放开 HTML 解释权。

三个容易误判的边界

• 把 text/template 换成 html/template：两者 API 很像，但输出目标不同。生成 HTML 时使用 text/template，不会得到上下文自动转义。
• 把所有富文本都转成 template.HTML：这会把“清理责任”推给调用方；类型名不会替你检查标签、属性或协议。
• 只测正常输入：至少用包含尖括号、引号和不受信任 URL 的样本执行一次模板，检查输出是否仍保持结构边界。

完整可验证片段：固定结构，动态值仍保持 string

下面的例子把允许出现的标签写死，动态标题和正文继续使用 string。运行后可以直接观察模板执行成功，且恶意样本只作为文字出现。

package main

import (
    "html/template"
    "os"
)

type PageData struct {
    Title string
    Body  string
}

func main() {
    const page = `
{{.Title}}
{{.Body}}
`

    t := template.Must(template.New("page").Parse(page))
    data := PageData{
        Title: "模板边界",
        Body:  `这只是文本`,
    }
    if err := t.Execute(os.Stdout, data); err != nil {
        panic(err)
    }
}

验收点只有两个：输出结构仍由模板中的 main、h1、p 决定；Body 里的标签不会改变结构。若业务确实需要有限富文本，先在独立函数中做允许标签和属性的白名单处理，再把返回类型和调用位置限制清楚。

相关问题

html/template 能不能直接渲染 Markdown？

不能把 Markdown 当成已经安全的 HTML。应先使用可信 Markdown 转换器得到结果，再做适合业务的 HTML 白名单处理，最后才考虑是否输出 typed string。

template.HTML 会不会自动清理脚本？

不会。它是对内容可信性的声明，不是过滤器。对外部或用户输入做类型转换属于危险用法。

什么时候应该继续用 text/template？

当输出目标是纯文本、邮件模板或配置片段，并且不需要 HTML 上下文保护时可以使用；一旦目标是 HTML 页面，优先选择 html/template。

小结

这类问题的最小判断顺序是：先确认输出目标，再确认插值上下文，最后才讨论是否存在可信的 typed string。普通动态数据保持 string，让 html/template 自动转义；只有结构和来源都能被代码与审查证明时，才把局部内容提升为 template.HTML。