html/template 与 text/template 的转义边界有什么不同

html/template 与 text/template 的 API 很像，真正的分界在输出会不会被浏览器当作 HTML 解析：页面、HTML 邮件和服务端渲染应优先使用 html/template；日志、纯文本邮件、配置片段或代码生成物才适合 text/template。前者把执行数据视为不可信文本，并按 HTML、属性、URL、JavaScript 等上下文自动转义；后者只负责把值格式化进文本，不替你建立浏览器安全边界。

官方资料：https://pkg.go.dev/html/template

文本模板资料：https://pkg.go.dev/text/template

一句话判断：输出交给浏览器解析就选 html/template；输出只是字符序列就选 text/template。不要为了“显示原 HTML”而把外部输入强行转换成安全类型。

同一份数据，两个包的默认结果不同

两套包都提供 Parse、Execute、FuncMap 等模板操作方式，所以把导入路径从 text/template 改成 html/template 看起来很容易。但默认输出不是一回事。下面的最小示例故意传入带标签的字符串：

package main

import (
    "html/template"
    "os"
)

func main() {
    // 模板作者写结构，执行数据按不可信文本处理。
    const page = `
{{.}}
`
    data := `来自请求的内容`

    t, err := template.New("page").Parse(page)
    if err != nil {
        panic(err) // 解析失败时不要继续输出半成品页面。
    }
    if err := t.Execute(os.Stdout, data); err != nil {
        panic(err) // 写出失败也要让调用方感知。
    }
}

这里的标签会被当成文字编码，浏览器不会把它重新解释为元素。若把导入改成 text/template，同一数据会原样进入输出，适合纯文本场景，却不适合直接作为 HTML 响应。迁移时最容易忽略的不是函数名，而是“数据是否可能改变输出结构”这一安全假设。

html/template 不是简单的全局替换

html/template 会在解析阶段识别动作所在的上下文，并为管道补上内部转义逻辑。相同的 {{.}} 放在普通文本、属性和查询参数里，结果可能不同：

例如：

const page = `搜索
`

// Query 会按 URL/属性上下文处理，Message 会按 JavaScript 值编码。
t, err := template.New("search").Parse(page)
if err != nil {
    return err // 上下文不完整时，优先修正模板结构。
}
return t.Execute(w, data) // w 可以是 http.ResponseWriter 或缓冲区。

因此不能先在业务层统一调用某个转义函数，再把结果随意塞进所有位置。模板本身提供的上下文信息更完整，业务代码应尽量传递原始值，让模板包完成对应位置的编码。

为什么有时会看到 #ZgotmplZ

当值出现在 URL 上下文，却包含不允许的协议或结构时，html/template 可能输出 #ZgotmplZ 这样的占位结果。它表达的是“这个值不应直接进入该 URL”，不是编码失败。开发时应回到输入约束和链接构造处排查，例如只允许业务需要的 https、mailto 或站内相对路径，并在模板外完成 URL 解析与策略判断。

这也是 text/template 与 html/template 不能互换的关键：前者不会理解 href、事件处理器或 CSS 上下文，原样输出的字符串可能被浏览器当作结构或代码的一部分。

template.HTML 等类型只能跨过明确的信任边界

如果内容确实由受信任的程序生成，html/template 提供 template.HTML、template.URL 等类型，表示调用方已经承担了相应上下文的安全责任。它们的作用是避免可信片段被重复转义，不是“让用户输入可以执行”。

// 只有经过固定白名单构造的片段才能标记为 template.HTML。
func trustedBadge(level string) template.HTML {
    switch level {
    case "success":
        return template.HTML(`成功`)
    default:
        return template.HTML(`未确认`)
    }
}

不要把数据库字段、请求参数或 Markdown 原文直接写成 template.HTML(value)。这会把原本由模板包承担的转义责任转移给调用方，一旦信任判断失误，输出就可能重新获得改变页面结构的能力。

迁移和选型可以按这张清单执行

1. 先确认输出是否会被浏览器、WebView 或 HTML 邮件客户端解析；是就使用 html/template。
2. 保留原有模板语法、FuncMap 和执行流程，但重新检查每个动作所在的上下文。
3. 用标签、引号、危险 URL 和 JavaScript 字符串做最小回归样例，分别检查文本、属性和脚本位置。
4. 只对白名单生成的固定片段使用安全类型，用户输入继续保持普通字符串。
5. 如果目标只是日志、纯文本通知或配置文件，使用 text/template，并在下游解析器边界单独做校验。

最终判断不在于两个包的调用方式有多像，而在于输出端是否存在结构解释器。面向 HTML 时，让 html/template 保留上下文并自动转义；面向纯文本时，text/template 的原样输出才是预期行为。

常见疑问

可以先用 text/template 生成 HTML，再手动调用 HTMLEscape 吗？不建议。手动转义很难覆盖属性、URL、JavaScript 和 CSS 的上下文组合，直接使用 html/template 更稳妥。

html/template 能保证模板作者写出的逻辑安全么？它主要假设模板作者可信、执行数据不可信；模板作者仍可能主动写出危险结构或错误地使用安全类型。

纯文本邮件能用 html/template 吗？可以，但会得到 HTML 转义语义；如果邮件正文不会被解析为 HTML，使用 text/template 更符合输出目标。