在 Go 中安全显示用户文本，关键不是“删掉尖括号”，而是先确认数据最终进入什么输出上下文。如果你明确地把一个普通字符串放进 HTML 的文本节点，可以使用 html.EscapeString 把五类特殊字符编码成实体；如果页面由模板生成，则更推荐直接使用 html/template，让模板根据 HTML、属性、URL、JavaScript 等上下文自动选择转义方式。

本文从零完成一个最小留言展示页：用户通过查询参数提交昵称和留言，服务端把它们当作文字显示。项目只解决“显示普通用户文本”这一件事，不讨论允许用户提交富文本的清洗规则。

官方文档：https://pkg.go.dev/html；https://pkg.go.dev/html/template

项目目标与验收标准

最终服务提供一个 /message 地址，读取 name 和 text 两个查询参数。无论输入中是否包含 、>、&、单引号或双引号，页面都只显示这些字符代表的文本，不把输入当成页面结构。

例如留言为 今天完成 时，验收结果应是页面显示包含尖括号的整段文字，而不是把“今天完成”渲染成粗体。这个例子足以观察文本与标签的区别，不需要构造攻击代码。

环境准备：只使用 Go 标准库

新建目录后初始化模块即可。这个小项目只用 net/http、html 或 html/template，不需要第三方依赖。下面的命令仅用于建立模块：

mkdir safe-message
cd safe-message
go mod init example.com/safe-message

先把程序写成最小 HTTP 服务，再分别观察直接拼接、手工转义和模板输出。这样每次改动只有一个变量，便于判断问题究竟发生在输入读取、字符串处理还是页面渲染。

先看错误边界：直接拼接会把文本交给 HTML 解析器

下面的处理器把查询参数直接放进 HTML 字符串。fmt.Fprintf 只负责格式化，不理解其中哪部分可信，也不会替你转义用户数据：

func unsafeMessage(w http.ResponseWriter, r *http.Request) {
    text := r.URL.Query().Get("text")

    // 直接拼接会让浏览器把输入中的标签形状解释为 HTML
    fmt.Fprintf(w, "
%s
", text)
}

这里的问题不是 fmt.Fprintf 本身，而是模板骨架和不可信数据被拼成同一段 HTML。只要输出会交给 HTML 解析器，就必须在正确上下文中编码数据，或者让专用模板引擎完成这项工作。

核心代码：先把用户字符串变成可显示的文本

html.EscapeString 会处理五类字符：、>、&、单引号和双引号。根据标准库文档，UnescapeString(EscapeString(s)) == s 始终成立；这说明转义后的响应在浏览器按实体解码时，用户仍看到原本的文字。

在这个小项目中，我们明确知道数据只进入

...

package main

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

func messageHandler(w http.ResponseWriter, r *http.Request) {
    name := r.URL.Query().Get("name")
    text := r.URL.Query().Get("text")

    // 先把不可信字符串编码为适合 HTML 文本节点的内容
    safeName := html.EscapeString(name)
    safeText := html.EscapeString(text)

    w.Header().Set("Content-Type", "text/html; charset=utf-8")

    // 只有固定结构由程序提供，用户数据都已经完成文本转义
    fmt.Fprintf(
        w,
        "
%s
%s
",
        safeName,
        safeText,
    )
}

func main() {
    http.HandleFunc("/message", messageHandler)

    // 示例服务只监听本机，便于完成本地验收
    log.Fatal(http.ListenAndServe("127.0.0.1:8080", nil))
}

这段实现有三个可检查的边界：输入仍是原始字符串，EscapeString 产生供 HTML 文本节点使用的编码字符串，固定的页面结构才负责组合输出。不要在转义后继续把结果当作“已对所有上下文安全”的通用值。

五类字符具体会变成什么

理解替换表有助于排查“响应源码为什么与页面显示不一样”。浏览器在文本节点中解析实体后，会呈现用户原本输入的字符；安全目标不是让字符消失，而是避免它们参与 HTML 结构解析。

实际替换顺序由标准库实现负责，业务代码不要重复手写一组 strings.ReplaceAll；漏项、顺序错误和重复编码都会让结果变得不可预测。

本地运行与验收

保存为 main.go 后运行 go run .。访问 /message 并传入普通文字、带标签外观的文字、引号和 &，逐项确认页面显示与响应源码的差异。

最直接的断言可以写成单元测试，不依赖浏览器。测试应检查响应体包含已转义字符串，并且不包含未转义的用户片段：

func TestMessageHandlerEscapesText(t *testing.T) {
    req := httptest.NewRequest(
        http.MethodGet,
        "/message?name=%3Cb%3EGo%3C%2Fb%3E&text=A%26B",
        nil,
    )
    recorder := httptest.NewRecorder()

    // 直接调用处理器，检查服务端真正生成的响应体
    messageHandler(recorder, req)

    body := recorder.Body.String()
    if !strings.Contains(body, "Go") {
        t.Fatalf("name was not escaped: %s", body)
    }
    if !strings.Contains(body, "A&B") {
        t.Fatalf("text was not escaped: %s", body)
    }
}

测试响应源码而不是只凭肉眼看页面，因为页面会把实体还原成可读字符。源码中的 < 与页面中的 同时正确，恰恰说明数据以文本身份进入了文档。

项目集成：页面模板优先交给 html/template

手工调用 EscapeString 适合边界非常明确的 HTML 文本片段，但真实页面通常还包含属性、链接、样式或脚本位置。html/template 会在解析模板时识别动作所在的上下文，并为普通字符串加入对应的转义处理。官方安全模型假定模板作者可信，而传给 Execute 的数据不可信。

把上一版处理器改为模板后，不要再预先调用 EscapeString，直接传入原始字符串：

package main

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

var page = template.Must(template.New("message").Parse(`
{{.Name}}
{{.Text}}
搜索这条留言`))

type messagePage struct {
    Name string
    Text string
}

func messageHandler(w http.ResponseWriter, r *http.Request) {
    data := messagePage{
        Name: r.URL.Query().Get("name"),
        Text: r.URL.Query().Get("text"),
    }

    w.Header().Set("Content-Type", "text/html; charset=utf-8")

    // 模板根据文本、属性和 URL 所在位置分别处理普通字符串
    if err := page.Execute(w, data); err != nil {
        http.Error(w, "render failed", http.StatusInternalServerError)
    }
}

func main() {
    http.HandleFunc("/message", messageHandler)

    // 启动本地示例服务
    log.Fatal(http.ListenAndServe("127.0.0.1:8080", nil))
}

同一个 .Name 在元素文本和 title 属性中所需的编码并不完全相同，查询参数中的 .Text 又需要 URL 相关处理。模板可以依据位置组合内部的转义函数，这正是它比“所有位置先过一次 EscapeString”更稳妥的原因。

四个常见边界不要混淆

不要对模板数据预转义

如果先执行 html.EscapeString，再把结果作为普通字符串传给 html/template，其中的 & 还会再次被模板编码，页面可能显示 < 这类实体文本。选择一层负责输出编码：手工拼固定文本节点时自己转义；使用模板时传原始数据。

HTML 转义不是 URL 编码

EscapeString 不会把空格、斜杠和查询参数保留字符按 URL 规则编码。构造 URL 参数应使用 net/url，或者在 HTML 模板中把数据放到正确的 URL 上下文，让模板执行相应处理。

HTML 文本转义不能替代 JavaScript 或 CSS 上下文编码

把经过 EscapeString 的字符串直接塞进脚本或样式，并不能证明它在这些语法中安全。真实模板包含这些位置时，优先让 html/template 根据上下文处理，不要把 HTML 文本规则复制到其他语言。

转义不等于允许富文本

如果业务要求用户提交一部分可用标签，EscapeString 会把它们全部当作文字。允许富文本需要独立的白名单清洗设计；不要为了“保留格式”就把未经审查的输入转换成 template.HTML。该类型会绕过普通字符串转义，只应承载经过可信流程确认的内容。

上线前检查清单

• 确认输出位置：文本节点、属性、URL、JavaScript 和 CSS 不是同一种上下文。
• 优先使用 html/template：完整 HTML 页面让模板负责上下文转义。
• 避免重复转义：模板数据传原始字符串，不提前调用 EscapeString。
• 固定页面骨架：模板源码由可信开发者维护，用户只提供数据。
• 检查 Execute 错误：渲染失败应中止并返回明确状态，而不是继续拼接响应。
• 测试特殊字符：至少覆盖五类字符、空字符串、中文和较长文本。
• 限制输入规模：转义解决结构解释问题，不替代长度限制和资源保护。

常见问题

EscapeString 会删除用户输入吗？

不会。它把五类特殊字符改写为 HTML 实体，使浏览器在文本位置显示原字符。页面源码和视觉文本不同是预期行为。

已经设置 Content-Type，还需要转义吗？

需要。text/html 只是告诉客户端按 HTML 解析响应，并不会自动区分模板结构与用户数据。编码责任仍在输出代码或 HTML 模板。

只显示纯文本，可以不用 HTML 吗？

可以。如果响应本来就不需要 HTML，把 Content-Type 设置为 text/plain; charset=utf-8 并直接写入文本，边界会更简单。是否需要 EscapeString 取决于数据是否进入 HTML 解析上下文。

html.EscapeString 和 template.HTMLEscapeString 该选哪个？

两者都能生成 HTML 转义字符串，但完整页面应优先使用 html/template 的模板执行能力，而不是在业务代码中到处手工调用字符串转义函数。本文使用 html.EscapeString 是为了讲清明确文本节点中的最小机制。

总结

html.EscapeString 的正确定位是：把普通字符串编码为适合 HTML 文本展示的字符串，它只处理五类特殊字符，不是 URL、JavaScript、CSS 或富文本清洗工具。对于一个固定文本节点，它简单直接；对于真实页面，html/template 能根据数据所在位置进行上下文转义，通常是更可靠的集成方案。

完成这个小项目后，可以用一句话验收：用户输入始终作为数据进入页面，而不是变成模板结构。只要这条边界在代码、模板和测试中都清晰，安全显示用户文本就不再依赖零散的字符串替换。