Go html/template怎样让模板输出自动转义用户输入为什么结果为空或不符合预期

我第一次把用户评论嵌进 Go 页面时，最容易误判的现象不是明显报错，而是“怎么没有按我写的 HTML 显示”。结论其实很明确：html/template 默认会根据 HTML 上下文自动转义普通字符串；如果页面像是空了，优先检查数据字段和 Execute 的错误返回，而不是先关闭转义。

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

安全的默认写法是把用户输入当作普通字符串交给 html/template，让模板负责转义；只有确认内容完全可信时，才讨论特殊类型。自动转义改变的是展示文本，不会让非空字符串凭空消失。

自动转义到底发生在哪里

html/template 不是简单地把字符串原样拼进 HTML。模板解析后，它会结合字段所在的上下文处理文本，例如普通文本节点、属性值或 URL 相关位置会有不同的安全编码。输入中的尖括号因此可能显示成文字，而不会被浏览器当作标签执行。

可以先记住一个判断：如果“加粗”出现在页面上，而不是出现粗体，这通常说明自动转义正在工作，不是输出失败。真正的空输出，要继续看数据值、条件分支和错误。

旧写法为什么会把问题藏起来

下面这种写法把解析和执行错误都丢掉了。模板字段写错、数据类型不匹配或执行过程中发生错误时，调用方只能看到一个不完整的响应，很难知道故障来自哪里。

package main

import (
    "net/http"
    "html/template"
)

var page = template.Must(template.New("page").Parse(`
{{.Comment}}
`))

func handler(w http.ResponseWriter, r *http.Request) {
    // 这里直接执行模板，示例故意省略错误处理，排查时不应照搬。
    _ = page.Execute(w, map[string]string{"Comment": r.FormValue("comment")})
}

这段代码还有一个容易忽略的点：FormValue 没拿到参数时会得到空字符串，而 html/template 会忠实地渲染空字符串。于是“没有输出”可能只是输入字段名、请求方法或表单名称没有对上。

把 Parse 和 Execute 的错误分开

我现在会把模板准备和模板执行分成两个可观察的边界。这样能立即区分“模板本身解析失败”和“当前数据执行失败”，也能保证 HTTP 响应在错误发生时有明确处理。

package main

import (
    "fmt"
    "html/template"
    "net/http"
)

var page = template.Must(template.New("page").Parse(`
{{.Comment}}
`))

func handler(w http.ResponseWriter, r *http.Request) {
    data := struct {
        Comment string
    }{
        // 先统一输入字段，避免模板字段和表单字段各写一套名称。
        Comment: r.FormValue("comment"),
    }

    if err := page.Execute(w, data); err != nil {
        // Execute 失败要记录真实错误，不能把异常响应当成正常空页面。
        http.Error(w, fmt.Sprintf("render template: %v", err), http.StatusInternalServerError)
        return
    }
}

如果模板写成了 {{.Commet}}，解析阶段通常就会暴露问题；如果字段存在但值为空，执行会成功，只会产生空的段落内容。排查时不要把这两类现象混为一谈。

为什么结果为空或不符合预期

可以按下面的顺序缩小范围。第一，确认数据对象真的有值，并区分空字符串、零值和字段不存在。第二，确认模板中的字段路径与传入对象一致，嵌套对象要逐层核对。第三，检查 if、with 或 range 是否因为零值跳过了内容。第四，检查是否把执行错误写进了已经开始输出的响应。

还有一种看似“格式不对”的情况：用户输入中含有 、> 或引号，最终页面出现实体编码。这是预期的安全结果。不要为了让它“像 HTML”而把字符串强制转换为 template.HTML，因为那会绕过普通字符串的安全边界。

template.HTML 什么时候才不该用

template.HTML 表示调用方已经确认这段内容是可信 HTML。它适合由应用内部生成、经过严格白名单处理的固定片段，不适合承接评论、昵称、富文本粘贴内容或任何未经清洗的请求参数。

type ViewData struct {
    Comment string
    // SafeFragment 只能来自受控的内部片段，不接收用户原文。
    SafeFragment template.HTML
}

func render(w http.ResponseWriter, data ViewData) error {
    // 普通 Comment 继续自动转义，可信片段才使用明确的特殊类型。
    return page.Execute(w, data)
}

如果业务确实需要富文本，应该先定义允许的标签和属性，再由专门的清洗流程产出受控结果，并把“清洗后的可信片段”与“用户原始字符串”分开命名。不要在模板层临时转换来掩盖数据问题。

我会留下的排查清单

相关问题

html/template 和 text/template 该怎么选？

输出 HTML 页面时优先使用 html/template；生成纯文本、邮件文本或其他非 HTML 内容时，再考虑 text/template。两者不能因为“显示效果更方便”就随意互换。

自动转义会不会修改数据库里的原文？

不会。转义发生在模板生成输出时，数据库或内存中的原字符串不会因为渲染而被改写。

为什么同一个值放在不同位置显示不同？

因为模板会考虑 HTML 上下文。文本节点、属性和 URL 等位置的风险不同，编码结果也可能不同；这正是自动转义要做的工作。

对我来说，最稳妥的习惯是保留默认转义、完整处理 Parse 与 Execute 错误，并把“值为空”和“值被安全编码”当成两种不同问题。先把这三个边界分清，绝大多数 html/template 的“输出不对”都能很快定位。