transform.HTMLEscape
返回把特殊字符替换为 HTML 实体后的给定字符串。
这一页解决什么问题
要把用户输入、数据文件里的文本安全地放进 HTML:&、<、>、'、" 这五个字符在 HTML 里有特殊含义,原样输出会破坏结构甚至造成注入。htmlEscape 把它们换成实体。
htmlEscape 与 transform.HTMLEscape 是同一个函数:前者是别名。
什么时候用,什么时候别用
该用:
- 把值放进 HTML 文本节点或属性,且该值来自不受信任的来源;
- 生成 RSS/XML 之外的自定义输出,需要自己控制转义时机。
别用:
- 只想在 HTML 模板里安全输出一个变量 → 通常什么都不用做:
{{ .Params.x }}已经会被自动转义,多此一举还可能造成二次转义; - 目标是 XML/RSS → 用
transform.XMLEscape:它还会转义制表符与换行(实测); - 想放进 JavaScript 或 JSON → 用
encoding.Jsonify; - 想把实体还原成字符 → 用
transform.HTMLUnescape,方向相反。
上游给出的结果
transform.HTMLEscape 函数通过把五个特殊字符替换为 HTML 实体来转义它们:
&→&<→<>→>'→'"→"
例如:
go-html-template
{{ htmlEscape "Lilo & Stitch" }} → Lilo & Stitch
{{ htmlEscape "7 > 6" }} → 7 > 6完整示例:直接输出与 safeHTML 的差别
layouts/_partials/escape.htmlgo-html-template
<p>{{ htmlEscape "Lilo & Stitch" }}</p>
<p>{{ htmlEscape "Lilo & Stitch" | safeHTML }}</p>
<p>{{ htmlEscape "7 > 6" | safeHTML }}</p>Hugo 渲染出的 HTML 为(变量赋值行本身会留下空行,这里省略):
html
<p>Lilo &amp; Stitch</p>
<p>Lilo & Stitch</p>
<p>7 > 6</p>你应当看到什么:第一行在浏览器里会显示成 Lilo & Stitch(实体被当成文本),这就是二次转义;第二、三行才能得到 Lilo & Stitch 和 7 > 6 的预期显示。所以:在 HTML 模板里用 htmlEscape,几乎总要跟一个 safeHTML。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'zh-CN'),Windows。下表「返回值」一列是用纯文本输出格式测到的函数原始返回。
| 输入 | 原始返回值 | 是否报错 |
|---|---|---|
"Lilo & Stitch" |
Lilo & Stitch |
否 |
"7 > 6" |
7 > 6 |
否 |
单引号与双引号同时出现(输入为 '") |
'" |
否 |
数字 42 |
42 |
否 |
nil |
空字符串 "" |
否 |
| 返回类型 | string(不是 template.HTML,所以会被再次转义) |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 页面上出现 &amp; |
返回值是 string,在 HTML 模板里被二次转义 |
加 | safeHTML,或干脆不手动转义 |
| 没报错但结果不对 | 属性值里的引号仍然出问题 | 手写转义序列与上下文不匹配 | 属性场景优先用 Go 模板的自动转义,不要手工拼 |
| 没报错但结果不对 | 制表符、换行没有被转义 | htmlEscape 只处理那五个字符 |
XML/RSS 场景用 transform.XMLEscape |
| 报错看不懂 | 函数名找不到 | 别名是 htmlEscape(小写 h)而不是 htmlescape |
写 htmlEscape 或 transform.HTMLEscape |
更多排查入口见故障排查。