html-escape 是干什么的
转义就是把 &、<、>、"、' 换成实体,让用户输入只当文字显示、不被浏览器当成标签执行;唯一必须记住的规则是 & 要最先转。
$ printf '<a href="x">A&B</a>\n' > raw.txt
$ sed 's/&/\&/g; s/</\</g; s/>/\>/g; s/"/\"/g' raw.txt
<a href="x">A&B</a>
浏览器拿到上面这行,会原样显示 <a href="x">A&B</a> 这段文字,而不是生成一个链接。转义不是加密,只是让字符失去语法含义。
这一页的命令在哪执行
Linux / WSL 用 sed 做逐字符替换、用 python3 的 html 模块做标准转义;Windows 用 .NET 的 [System.Net.WebUtility]::HtmlEncode。
示例基于 GNU sed 与 Python 3(Ubuntu 24.04)以及 Windows PowerShell 5.1 调用的 .NET WebUtility。
展开:五个基本实体、不同上下文的转义规则、为什么模板引擎会二次转义
| 字符 | 实体 | 说明 |
|---|---|---|
& |
& |
必须最先处理,否则会把后生成的实体再转一次 |
< |
< |
防止被当成标签开始 |
> |
> |
非必须,但习惯上一并转 |
" |
" |
属性值用双引号时必须转 |
' |
' |
属性值用单引号时必须转 |
上下文不同,规则不同:
| 输出位置 | 该用什么 |
|---|---|
| HTML 正文 | 转 & < > |
| 属性值 | 额外转引号,属性始终用引号包裹 |
| URL 参数 | URL 编码(%XX),HTML 实体在这里没用 |
| JavaScript 字符串 | 转 </script>、反斜杠、换行 |
| CSS / 内联事件 | 尽量不要放用户输入 |
Thymeleaf、Vue、React 默认都会自动转义,只有 th:utext、v-html、dangerouslySetInnerHTML 才是不转义的出口。后端手工再转一次,页面上就会显示 <div> 这样的字面量。
它到底在干什么
一、顺序:& 必须第一个转
先转 < 再转 &,刚生成的 < 会被第二次转义成 &lt;,页面上真的显示 < 这几个字符。
$ sed 's/</\</g; s/&/\&/g' raw.txt
&lt;a href="x">A&B&lt;/a>
对比正确顺序的结果:
$ sed 's/&/\&/g; s/</\</g; s/>/\>/g; s/"/\"/g' raw.txt
<a href="x">A&B</a>
错误顺序那行里,< 变成了 <,紧接着 & 规则又把其中的 & 换成 &,得到 &lt;。另外它没转引号,href="x" 原样保留,放进属性上下文仍然有风险。
二、Python 的 html.escape 与 html.unescape
html.escape 默认连引号一起转,quote=False 只转 & < >;unescape 只还原一层实体。
$ python3 - <<'PY'
import html
s = '<a href="x">A&B</a>'
print(html.escape(s))
print(html.escape(s, quote=False))
print(html.unescape(html.escape(s)))
print(repr(html.unescape('&lt;div&gt;')))
PY
<a href="x">A&B</a>
<a href="x">A&B</a>
<a href="x">A&B</a>
'<div>'
第三行说明转义再反转义能回到原文。第四行说明 &lt; 只被还原成 <,不会继续还原成 <——双重转义要再跑一次 unescape 才能恢复,这也正是它难排查的原因。
三、 是另一个字符,不是空格
对应 U+00A0,在 UTF-8 里是 c2 a0 两个字节;普通空格是 20,两者字符串比较不相等。
$ printf 'a\xc2\xa0b\n' > nbsp.txt
$ od -An -tx1 nbsp.txt
61 c2 a0 62 0a
$ sed 's/\xc2\xa0/ /g' nbsp.txt | od -An -tx1
61 20 62 0a
从网页复制下来的文本经常夹着它。数据库去重、关键词匹配、LIKE 'a b' 都会因为它失败,而肉眼看两个字符串一模一样。
四、URL 编码不是 HTML 转义
html.escape 只动 &;URL 里的空格、=、中文要交给 urllib.parse.quote,两套规则不能互换。
$ python3 - <<'PY'
from urllib.parse import quote
import html
s = 'a b&c=d/中'
print(html.escape(s))
print(quote(s))
PY
a b&c=d/中
a%20b%26c%3Dd/%E4%B8%AD
html.escape 输出里空格还是空格、= 还是 =,只有 & 被转。**把 HTML 实体塞进 URL 参数,服务端收到的是字面量 &,不是 &。**反过来,URL 编码后的 %26 放进 HTML 正文也不会被浏览器解码成 &。
语法骨架
sed 's/&/\&/g; s/</\</g; s/>/\>/g; s/"/\"/g' 文件
python3 -c 'import html; print(html.escape(字符串))'
python3 -c 'import html; print(html.unescape(字符串))'
python3 -c 'from urllib.parse import quote; print(quote(字符串))'
[System.Net.WebUtility]::HtmlEncode(字符串)
[System.Net.WebUtility]::HtmlDecode(字符串)
| 写法 | 作用 |
|---|---|
& |
& 的实体,必须最先替换 |
< / > |
< / > 的实体 |
" / ' |
双引号 / 单引号实体 |
html.escape(s) |
Python 标准转义,默认转引号 |
html.escape(s, quote=False) |
只转 & < >,不转引号 |
html.unescape(s) |
还原一层实体 |
quote(s) |
URL 编码,空格变 %20,默认保留 / |
quote(s, safe='') |
连 / 也编码 |
WebUtility.HtmlEncode |
.NET 转义,引号转成 " |
WebUtility.HtmlDecode |
.NET 反转义 |
出错会怎样:转义顺序错不会报错,只会产生双重转义的文本;属性里漏转引号也不会报错,但会给 XSS 留口子。这一类问题没有异常可抓,只能靠输出检查。
失败长这样:
| 情况 | 结果 | 说明 |
|---|---|---|
先转 < 后转 & |
&lt;a href="x">... |
双重转义,页面显示 < |
unescape('&lt;div&gt;') |
'<div>' |
只还原一层 |
与普通空格比较 |
不相等 | c2 a0 与 20 是两个字符 |
URL 里用 & |
参数值变成字面量 & |
HTML 实体在 URL 里无效 |
常见用法示例
采集目录:WSL 下 /mnt/e/.../smalldemo,raw.txt 内容为 <a href="x">A&B</a> 加换行。
1. 用 sed 转义一段 HTML
$ sed 's/&/\&/g; s/</\</g; s/>/\>/g; s/"/\"/g' raw.txt
<a href="x">A&B</a>
四条规则按 &、<、>、" 的顺序执行,这是最关键的一点。
2. 顺序写反会双重转义
$ sed 's/</\</g; s/&/\&/g' raw.txt
&lt;a href="x">A&B&lt;/a>
&lt; 在页面上显示为 <。只要看到页面出现实体字面量,先怀疑转义跑了两次。
3. Python 标准转义
$ python3 -c 'import html; print(html.escape("<a href=\"x\">A&B</a>"))'
<a href="x">A&B</a>
结果和 sed 四条规则一致。生产代码优先用它,不要手写替换链。
4. quote=False 只转三个字符
$ python3 -c 'import html; print(html.escape("<a href=\"x\">A&B</a>", quote=False))'
<a href="x">A&B</a>
引号保持原样。只有确定这段文本不进属性值时才能这样用,否则 " 会提前闭合属性。
5. 反转义一层
$ python3 -c 'import html; print(html.unescape("<div>"))'
<div>
反转义会把实体变回真实标签。对用户输入反转义后再输出,等于把已经安全的文本重新变成可执行内容。
6. 识别双重转义
$ python3 -c 'import html; print(repr(html.unescape("&lt;div&gt;")))'
'<div>'
跑一次只回到 <div>,还要再跑一次才变成 <div>。修复时要找到多转的那一层,而不是在展示层反复 unescape。
7. 清洗
$ printf 'a\xc2\xa0b\n' > nbsp.txt
$ od -An -tx1 nbsp.txt
61 c2 a0 62 0a
$ sed 's/\xc2\xa0/ /g' nbsp.txt | od -An -tx1
61 20 62 0a
c2 a0 变成 20。入库前统一替换成普通空格,否则搜索、去重、排序都会出怪问题。
8. URL 编码与 HTML 转义的区别
$ python3 -c 'from urllib.parse import quote; print(quote("a b&c=d/中"))'
a%20b%26c%3Dd/%E4%B8%AD
空格、&、=、中文全部变成 %XX。URL 参数用这个,不要用 &。
9. 什么时候要连斜杠一起编码
$ python3 -c 'from urllib.parse import quote; print(quote("a/b c"))'
a/b%20c
$ python3 -c 'from urllib.parse import quote; print(quote("a/b c", safe=""))'
a%2Fb%20c
默认 safe="/",斜杠不编码,适合拼整条路径。如果这段值要作为一个路径段传参(斜杠要当数据而不是分隔符),必须传 safe="",否则服务端会多切一层路径。
10. PowerShell 里用 .NET 转义
PS> [System.Net.WebUtility]::HtmlEncode('<a href="x">A&B</a>')
<a href="x">A&B</a>
结果和 html.escape 一致,五个字符都转,引号是 "。
11. PowerShell 里反转义
PS> [System.Net.WebUtility]::HtmlDecode('<div>')
<div>
用于读取已转义的配置或日志。同样只还原一层,且不要在输出前对用户输入做这一步。[System.Web.HttpUtility]::HtmlDecode 已随 .NET Framework 标记过时,优先用 WebUtility。
容易误解与失败对照
最常见的几个误解
- "转义一次就安全了":还要看输出上下文,属性、URL、JS 规则都不同。
- "转义顺序无所谓":
&不先转就会双重转义。 - "
html.escape能防所有 XSS":它只处理 HTML 上下文,防不住 URL 注入和 JS 注入。 - "反转义是无害的":反转义后再输出等于主动还原攻击载荷。
- "
就是空格":它是 U+00A0,和空格不是同一个字符。 - "URL 里写
&也行":服务端收到的是字面量,参数会解析错。 - "正则删掉
<script>就安全了":变形写法、事件属性、javascript:协议都绕得过去。 - "页面上显示
<是浏览器坏了":是内容被转义了两次。 - "模板引擎会自动转义,后端不用管":用了
th:utext、v-html就绕过了自动转义。
失败对照:现象、原因、处理
| 现象 | 原因 | 处理 |
|---|---|---|
页面显示 <div> |
内容被转义两次 | 找到多转的一层,去掉后端手工转义 |
页面显示 &lt; |
& 没有最先转 |
调整替换顺序,或用 html.escape |
| 属性值被截断、页面结构乱 | 属性里的引号没转 | 属性统一用双引号,转 " |
URL 参数多出 amp; |
把 HTML 实体写进了 URL | 改用 urllib.parse.quote |
| 文本看起来一样但比较不相等 | 夹了 (c2 a0) |
统一替换成普通空格 |
| 反转义后出现可点击链接 | 对用户输入做了 unescape 再输出 | 只在读取展示前 unescape,输出前重新转义 |
删了 <script> 仍有弹窗 |
用了事件属性或 javascript: 协议 |
用白名单清洗库,不要用正则 |
| 日志里实体和原文混在一起 | 写入前转义、读出来没还原 | 明确"存储原文、输出转义"的分层 |
什么时候不该用这些命令
- 用
sed清洗用户 HTML 防 XSS:替换链挡不住变形写法,用成熟的转义或清洗库。 - 把转义结果再入库:库里应存原文,输出时再按上下文转义。
- 对已转义内容反复 escape:层数越多越难还原,最终页面全是实体字面量。
- 在 URL 参数里用 HTML 实体:编码规则不同,必须用 URL 编码。
- 用
innerHTML输出用户输入:即使转义过,也要确认上下文,优先用textContent。