Go html/template 与 text/template 的安全机制：自动转义是如何防止注入的

从一次模板注入说起

很多团队在使用Go开发Web服务时，都会遇到一个比较微妙的问题：模板引擎明明把变量输出成了文本，但页面还是被注入了意料不到的HTML代码。有人第一反应是换成更“安全”的框架，也有人会怪前端过滤不严。其实问题往往出在模板包的选择上。

标准库里同时提供了text/template和html/template两个包，名字非常接近，以至于不少项目从一开始就用错了对象。今天这篇文章就围绕这两个包的安全机制展开，重点聊聊html/template的自动转义是如何实现防注入的，以及哪些情况下text/template仍然有它的位置。

text/template 与 html/template 是什么关系

text/template是Go最早提供的通用模板引擎，作用是将数据应用到文本模板中。它会严格按照模板语法进行替换，但不会关心结果会被用在什么场景。也就是说，你只负责提供数据，它只负责把数据填充进去，至于填充后是纯文本、SQL、JSON还是HTML，它一概不管。

html/template则是在text/template的基础上重新实现的模板包。它同样支持所有的模板语法，但额外引入了一个非常重要的机制：上下文感知的自动转义。这个机制会根据模板输出位置所在的HTML上下文，对变量进行对应的编码处理，从而避免恶意输入破坏页面结构。

官方给出的设计思路是：html/template不仅把模板当作字符串拼接，还把它当作一个有结构的HTML文档来分析。因此它能识别当前变量是输出在标签内、属性中、JavaScript脚本里还是CSS样式中，并采用不同的转义规则。

自动转义到底在防什么

重点来看最常见的注入场景。一个博客网站允许用户提交评论，评论内容会显示在页面上。如果代码这样写：

// 错误示范：使用 text/template 渲染 HTML
 t := template.Must(template.New("comment").Parse(`<div>{{.Content}}</div>`))
 t.Execute(w, comment)

用户提交的内容如果是普通的“元旦快乐”，一切正常。但恶意用户提交的可能是：

<script>alert(document.cookie)</script>

使用text/template时，这个内容会原封不动地写入HTML，最终浏览器把它当成真实脚本执行。一个简单的存储型XSS就这样形成了。

如果换成html/template，情况就会完全不同：

t := template.Must(template.New("comment").Parse(`<div>{{.Content}}</div>`))
 t.Execute(w, comment)

html/template会自动发现当前输出位置是HTML元素内容，于是把<和>转义成实体。最终页面会显示用户输入的文本，但绝不会把<script>当成标签执行。

这就是自动转义最基础的防护：把不可信内容从“结构”里剥离，让它成为纯文本。

上下文感知转义是如何工作的

html/template不仅会处理HTML标签内容，还会根据变量所在位置选择不同的编码方式。举几个常见上下文例子：

• 在HTML正文中，对<、>、&、'、"进行HTML实体转义。
• 在HTML属性值中，例如<a href="{{.URL}}">，会额外进行URL相关校验，防止javascript:之类的伪协议。
• 在JavaScript代码块中，例如<script>var name = "{{.Name}}"</script>，会针对JS字符串上下文转义，避免闭合字符串后注入代码。
• 在CSS上下文中，会对可能逃逸的字符进行处理。

为什么需要区分？因为不同上下文的转义规则不同。如果把HTML转义过的文本直接塞进JavaScript字符串，攻击者依然可能构造出"); alert(1); (这样的payload。而html/template会识别当前状态，采用对应上下文的转义方案。

这里有一个很容易被忽视的点：这个“上下文”是动态跟踪的，不是简单粗暴地全局转义。模板引擎在解析模板时，会模拟HTML解析器状态，记录每个action分别处于什么环境，然后生成相应的转义策略。

我们可以在模板中用{{printf "%#v" .}}这样的方式，输出变量在渲染时的真实形式，帮助调试转义效果。

text/template 就一无是处吗

当然不是。text/template适合生成纯文本内容，例如配置文件、通知消息、代码生成。当你需要生成一个结构不依赖HTML语义的文本时，text/template就是正确的选择。如果你在生成这些文本时使用了html/template，反而可能因为多了一层不必要的转义而得到错误结果。

所以决策标准很简单：如果最终结果会被解释为HTML，就用html/template；如果只是普通文本，就用text/template。

但在实际团队中，我看到不少项目因为早期赶进度使用了text/template来渲染页面模板，后面即使知道有风险也不敢轻易迁移。原因可能是担心转义规则改变页面表现，也可能是代码里已经大量使用了template.HTML来绕过转义。后面我们会专门讨论这些坑。

真正容易出问题的地方

自动转义不是万能的，它只能处理它“知道”是输出内容的action。以下几个场景，是实际项目中最容易出问题的。

强制跳过转义

html/template定义了一些特殊类型，例如template.HTML、template.URL、template.JS。当变量是这些类型时，模板引擎会认为开发者已经做了安全检查，从而不再转义。

type Comment struct {
    Content template.HTML
}

这个设计本来是为了让开发者能够输出富文本，比如从富文本编辑器产生的受信任HTML。但如果只是简单地把用户提交的内容强制转换成template.HTML，就等于亲手关闭了安全保护。常见版本迭代时，后端同学为了快速实现“支持富文本”，直接把字段类型改成template.HTML，也没有做任何过滤清洗，这无异于裸奔。

如果你的确需要支持富文本，建议对输入做白名单过滤（比如使用bluemonday库），只允许安全的标签和属性，再用template.HTML或sanitized后的字符串输出。

在JavaScript上下文中使用内联模板

很多前端页面会在<script>标签中定义初始化数据：

<script>
    var settings = {{.Settings}};
</script>

这里{{.Settings}}处于JavaScript对象字面量上下文。html/template会根据上下文进行JS转义，但危险的是，如果Settings原本是一个JSON字符串，开发者可能会提前用json.Marshal转成字符串，然后输出。比如：

data, _ := json.Marshal(map[string]string{"name": "张三"})
t.Execute(w, string(data))

由于传入的是string类型，html/template会把它当作普通的JS字符串进行转义，导致输出内容里多出反斜杠或改变JSON结构。为了修复，有人又选择使用template.JS(string(data))来强制原样输出。一旦这样做了，XSS防护再次失效。

正确的做法是：在模板中直接渲染结构体或map，让html/template根据JS上下文自动处理每个字段。或者把JSON字符串放在一个自定义类型里，提供安全编码方法，由开发者自己保证编码安全。

嵌套模板时丢失上下文

html/template支持模板嵌套，上下文信息会在模板调用之间传递。但如果嵌套时通过define定义子模板，再把变量作为参数传入，有时会因为临时变量导致上下文判断不准确。这更多是模板设计问题，不是包本身的缺陷。

一个典型的反例是：在父模板中调用一个子模板，子模板的内容被内联到某段JavaScript中，而子模板内部又使用了一个通用文本模板。如果子模板没有显式声明上下文，html/template可能默认按HTML或text上下文处理，进而产生不正确的转义。

解决思路是避免在JS中复用通用的HTML子模板，或者将子模板设计成只接收确定上下文的参数。

方案对比：三种常见做法

从表格可以看出，默认选择html/template是性价比最高的方案。虽然它会牺牲一点性能，但换来的是默认安全和更少的漏洞。

落地建议：如何正确地在项目中使用

如果你正打算在一个新的Web项目里引入Go模板，或者考虑把旧的text/template迁移到html/template，下面的建议可以参考。

1. 所有面向浏览器的渲染，统一使用html/template。
2. 明确区分数据字段的类型：不可信内容用string，需要按原样输出时使用白名单流程后转为template.HTML。
3. 模板中尽量暴露对象属性，而不是把预先拼接好的HTML片段传入。
4. 对URL参数进行额外校验，html/template会拦截javascript:协议，但业务层的合法性判断仍然不能省。
5. 在测试里加入安全用例，直接构造恶意输入，断言输出不包含原始脚本标签。

另外，值得注意的是，html/template的自动转义只作用于action的输出，不会修改模板中静态写死的HTML。如果模板本身存在漏洞，例如用{{if}}拼接了不可信的逻辑，那还是要从模板设计上解决。

一个小实验：观察自动转义的细节

我们可以写个简单的程序验证自动转义的行为。假设模板中有三个位置：<div>内，href属性内，以及<script>内。

package main

import (
    "html/template"
    "os"
)

func main() {
    t := template.Must(template.New("demo").Parse(`
<div>{{.Content}}</div>
<a href="{{.Link}}">link</a>
<script>var msg = "{{.Msg}}"</script>
`))
    data := struct {
        Content string
        Link    string
        Msg     string
    }{
        Content: `<script>alert(1)</script>`,
        Link:    `javascript:alert(1)`,
        Msg:     `"; alert(1); var x="`,
    }
    t.Execute(os.Stdout, data)
}

输出结果中，第一行会看到<div>&lt;script&gt;alert(1)&lt;/script&gt;</div>，Script标签被HTML转义。第二行的href属性会被过滤掉javascript:，输出成无害值。第三行的JS字符串会被转义成类似\x22; alert(1); var x=\x22的安全形式。这就是上下文感知转义的具体体现。

聊聊性能与取舍

有些人担心自动转义带来的性能开销。确实，html/template在首次解析模板时需要做额外的上下文分析，这一步比text/template重一些。但实际项目中，模板解析通常只发生一次，随后会被缓存，真正执行时的开销差异并不会很明显。相比纠结那几微秒的性能，少写一个安全漏洞的价值大得多。

另一个取舍在于灵活度。html/template会在某些边界情况下限制你的表达方式，比如很难直接输出一个已经编码好的URL参数，你需要改变数据传递的结构。这种限制本质上是在逼你选择更安全的设计。

总结

html/template的自动转义是Go在Web安全上做得非常正确的一件事。它把“输出转义”从开发者的自觉行为，变成了框架的默认行为，几乎消灭了最常见的模板注入漏洞。但我们需要清醒地认识到，任何自动机制都有边界。template.HTML这个逃生舱，JavaScript上下文的特殊处理，以及嵌套模板的复杂性，仍然是漏洞高发区。

下次当你面对“为什么页面被注入了”的问题，可以先检查一下自己用的是哪个模板包。如果是text/template，答案可能已经写在你的代码里了。