html-escape 是干什么的

转义就是把 &、<、>、"、' 换成实体,让用户输入只当文字显示、不被浏览器当成标签执行;唯一必须记住的规则是 & 要最先转。

$ printf '<a href="x">A&B</a>\n' > raw.txt
$ sed 's/&/\&amp;/g; s/</\&lt;/g; s/>/\&gt;/g; s/"/\&quot;/g' raw.txt
&lt;a href=&quot;x&quot;&gt;A&amp;B&lt;/a&gt;

浏览器拿到上面这行,会原样显示 <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。

展开:五个基本实体、不同上下文的转义规则、为什么模板引擎会二次转义
字符 实体 说明
& &amp; 必须最先处理,否则会把后生成的实体再转一次
< &lt; 防止被当成标签开始
> &gt; 非必须,但习惯上一并转
" &quot; 属性值用双引号时必须转
' &#39; 属性值用单引号时必须转

上下文不同,规则不同:

输出位置 该用什么
HTML 正文 转 & < >
属性值 额外转引号,属性始终用引号包裹
URL 参数 URL 编码(%XX),HTML 实体在这里没用
JavaScript 字符串 转 </script>、反斜杠、换行
CSS / 内联事件 尽量不要放用户输入

Thymeleaf、Vue、React 默认都会自动转义,只有 th:utext、v-html、dangerouslySetInnerHTML 才是不转义的出口。后端手工再转一次,页面上就会显示 &lt;div&gt; 这样的字面量。

它到底在干什么

一、顺序:& 必须第一个转

先转 < 再转 &,刚生成的 &lt; 会被第二次转义成 &amp;lt;,页面上真的显示 &lt; 这几个字符。

$ sed 's/</\&lt;/g; s/&/\&amp;/g' raw.txt
&amp;lt;a href="x">A&amp;B&amp;lt;/a>

对比正确顺序的结果:

$ sed 's/&/\&amp;/g; s/</\&lt;/g; s/>/\&gt;/g; s/"/\&quot;/g' raw.txt
&lt;a href=&quot;x&quot;&gt;A&amp;B&lt;/a&gt;

错误顺序那行里,< 变成了 &lt;,紧接着 & 规则又把其中的 & 换成 &amp;,得到 &amp;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('&amp;lt;div&amp;gt;')))
PY
&lt;a href=&quot;x&quot;&gt;A&amp;B&lt;/a&gt;
&lt;a href="x"&gt;A&amp;B&lt;/a&gt;
<a href="x">A&B</a>
'&lt;div&gt;'

第三行说明转义再反转义能回到原文。第四行说明 &amp;lt; 只被还原成 &lt;,不会继续还原成 <——双重转义要再跑一次 unescape 才能恢复,这也正是它难排查的原因。

三、&nbsp; 是另一个字符,不是空格

&nbsp; 对应 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&amp;c=d/中
a%20b%26c%3Dd/%E4%B8%AD

html.escape 输出里空格还是空格、= 还是 =,只有 & 被转。**把 HTML 实体塞进 URL 参数,服务端收到的是字面量 &amp;,不是 &。**反过来,URL 编码后的 %26 放进 HTML 正文也不会被浏览器解码成 &。

语法骨架

sed 's/&/\&amp;/g; s/</\&lt;/g; s/>/\&gt;/g; s/"/\&quot;/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(字符串)
写法 作用
&amp; & 的实体,必须最先替换
&lt; / &gt; < / > 的实体
&quot; / &#39; 双引号 / 单引号实体
html.escape(s) Python 标准转义,默认转引号
html.escape(s, quote=False) 只转 & < >,不转引号
html.unescape(s) 还原一层实体
quote(s) URL 编码,空格变 %20,默认保留 /
quote(s, safe='') 连 / 也编码
WebUtility.HtmlEncode .NET 转义,引号转成 &quot;
WebUtility.HtmlDecode .NET 反转义

出错会怎样:转义顺序错不会报错,只会产生双重转义的文本;属性里漏转引号也不会报错,但会给 XSS 留口子。这一类问题没有异常可抓,只能靠输出检查。

失败长这样:

情况 结果 说明
先转 < 后转 & &amp;lt;a href="x">... 双重转义,页面显示 &lt;
unescape('&amp;lt;div&amp;gt;') '&lt;div&gt;' 只还原一层
&nbsp; 与普通空格比较 不相等 c2 a0 与 20 是两个字符
URL 里用 &amp; 参数值变成字面量 &amp; HTML 实体在 URL 里无效

常见用法示例

采集目录:WSL 下 /mnt/e/.../smalldemo,raw.txt 内容为 <a href="x">A&B</a> 加换行。

1. 用 sed 转义一段 HTML

$ sed 's/&/\&amp;/g; s/</\&lt;/g; s/>/\&gt;/g; s/"/\&quot;/g' raw.txt
&lt;a href=&quot;x&quot;&gt;A&amp;B&lt;/a&gt;

四条规则按 &、<、>、" 的顺序执行,这是最关键的一点。

2. 顺序写反会双重转义

$ sed 's/</\&lt;/g; s/&/\&amp;/g' raw.txt
&amp;lt;a href="x">A&amp;B&amp;lt;/a>

&amp;lt; 在页面上显示为 &lt;。只要看到页面出现实体字面量,先怀疑转义跑了两次。

3. Python 标准转义

$ python3 -c 'import html; print(html.escape("<a href=\"x\">A&B</a>"))'
&lt;a href=&quot;x&quot;&gt;A&amp;B&lt;/a&gt;

结果和 sed 四条规则一致。生产代码优先用它,不要手写替换链。

4. quote=False 只转三个字符

$ python3 -c 'import html; print(html.escape("<a href=\"x\">A&B</a>", quote=False))'
&lt;a href="x"&gt;A&amp;B&lt;/a&gt;

引号保持原样。只有确定这段文本不进属性值时才能这样用,否则 " 会提前闭合属性。

5. 反转义一层

$ python3 -c 'import html; print(html.unescape("&lt;div&gt;"))'
<div>

反转义会把实体变回真实标签。对用户输入反转义后再输出,等于把已经安全的文本重新变成可执行内容。

6. 识别双重转义

$ python3 -c 'import html; print(repr(html.unescape("&amp;lt;div&amp;gt;")))'
'&lt;div&gt;'

跑一次只回到 &lt;div&gt;,还要再跑一次才变成 <div>。修复时要找到多转的那一层,而不是在展示层反复 unescape。

7. 清洗 &nbsp;

$ 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 参数用这个,不要用 &amp;。

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>')
&lt;a href=&quot;x&quot;&gt;A&amp;B&lt;/a&gt;

结果和 html.escape 一致,五个字符都转,引号是 &quot;。

11. PowerShell 里反转义

PS> [System.Net.WebUtility]::HtmlDecode('&lt;div&gt;')
<div>

用于读取已转义的配置或日志。同样只还原一层,且不要在输出前对用户输入做这一步。[System.Web.HttpUtility]::HtmlDecode 已随 .NET Framework 标记过时,优先用 WebUtility。

容易误解与失败对照

最常见的几个误解

  • "转义一次就安全了":还要看输出上下文,属性、URL、JS 规则都不同。
  • "转义顺序无所谓":& 不先转就会双重转义。
  • "html.escape 能防所有 XSS":它只处理 HTML 上下文,防不住 URL 注入和 JS 注入。
  • "反转义是无害的":反转义后再输出等于主动还原攻击载荷。
  • "&nbsp; 就是空格":它是 U+00A0,和空格不是同一个字符。
  • "URL 里写 &amp; 也行":服务端收到的是字面量,参数会解析错。
  • "正则删掉 <script> 就安全了":变形写法、事件属性、javascript: 协议都绕得过去。
  • "页面上显示 &lt; 是浏览器坏了":是内容被转义了两次。
  • "模板引擎会自动转义,后端不用管":用了 th:utext、v-html 就绕过了自动转义。

失败对照:现象、原因、处理

现象 原因 处理
页面显示 &lt;div&gt; 内容被转义两次 找到多转的一层,去掉后端手工转义
页面显示 &amp;lt; & 没有最先转 调整替换顺序,或用 html.escape
属性值被截断、页面结构乱 属性里的引号没转 属性统一用双引号,转 "
URL 参数多出 amp; 把 HTML 实体写进了 URL 改用 urllib.parse.quote
文本看起来一样但比较不相等 夹了 &nbsp;(c2 a0) 统一替换成普通空格
反转义后出现可点击链接 对用户输入做了 unescape 再输出 只在读取展示前 unescape,输出前重新转义
删了 <script> 仍有弹窗 用了事件属性或 javascript: 协议 用白名单清洗库,不要用正则
日志里实体和原文混在一起 写入前转义、读出来没还原 明确"存储原文、输出转义"的分层

什么时候不该用这些命令

  • 用 sed 清洗用户 HTML 防 XSS:替换链挡不住变形写法,用成熟的转义或清洗库。
  • 把转义结果再入库:库里应存原文,输出时再按上下文转义。
  • 对已转义内容反复 escape:层数越多越难还原,最终页面全是实体字面量。
  • 在 URL 参数里用 HTML 实体:编码规则不同,必须用 URL 编码。
  • 用 innerHTML 输出用户输入:即使转义过,也要确认上下文,优先用 textContent。