HTML实体转义与XSS防御：从原理到实战的完整指南

HTML 里的和这两个符号看起来简单到不能再简单但我在实际项目里踩过的坑十有八九都和它们脱不了干系。你可能觉得不就是两个尖括号吗浏览器认识就行了。但问题恰恰出在这里——浏览器太“聪明”了它会把任何看起来像标签的东西都当成标签来解析哪怕你只是想老老实实显示一段代码、一段用户评论、或者一封邮件里的原文。这个解析规则本身没错错的是我们没搞清楚什么时候该转义、什么时候不该转义、转义成什么、以及转义之后又会引发什么新问题。这篇文章我想从一线开发的视角把 HTML 实体转义这件事彻底讲透。不管你是刚接触前端的新手还是写了几年业务代码的后端工程师只要你的系统里存在“用户输入的内容要显示在网页上”这个场景这篇文章里的内容你就一定用得上。我会从最基础的字符编码原理讲起一路延伸到 XSS 攻击的防御、富文本处理的取舍、邮件模板的坑、以及各种框架里过滤器该怎么写。核心关键词就三个HTML、实体转义、XSS。这三个词串起来就是一条从“知道”到“做到”再到“做对”的完整链路。1. 为什么尖括号是万恶之源从浏览器解析机制说起1.1 浏览器眼中的和到底是什么要理解实体转义得先理解浏览器是怎么“读” HTML 的。你可以把浏览器的 HTML 解析器想象成一个极其死板的流水线工人它拿到一串文本之后只做一件事从左到右扫描遇到就认为“哦一个标签要开始了”然后继续往后读直到遇到或者/把中间的内容当作标签名和属性来处理。它不会去猜你的意图不会去判断“这个尖括号是不是用户想显示出来的”它只认规则。这就意味着如果你在页面里直接输出一段包含scriptalert(1)/script的文本浏览器不会把它当作文本显示出来而是会认认真真地把它当作一个脚本标签来执行。这不是浏览器的 bug这是 HTML 规范定义的行为。HTML 从诞生之初就是一门标记语言标记语言的核心就是“用特殊符号来标注结构”而和就是最核心的结构符号。所以实体转义的本质就是把那些“会被浏览器当作结构符号来解析的字符”替换成“浏览器只会当作普通文字来显示的等价表示”。的实体表示是lt;的实体表示是gt;。这两个名字其实很好记lt 就是 less thangt 就是 greater than。浏览器在渲染时看到lt;会把它还原成显示给用户看但在解析阶段它不会把这个当作标签的开始。1.2 不转义会发生什么一个最小可复现的例子我拿一个最简单的例子来说明。假设你有一个留言板页面后端直接把用户提交的内容拼接到 HTML 里返回div classcomment 用户说scriptalert(xss)/script /div浏览器解析到script的时候会立刻切换到脚本解析模式把后面的alert(xss)当作 JavaScript 代码执行。页面上不会显示任何“用户说”后面的内容取而代之的是弹出一个对话框。这就是最经典的反射型 XSS。如果用户提交的不是script而是img srcx onerroralert(1)效果一样。甚至更隐蔽的比如svg onloadalert(1)、body onpageshowalert(1)这些标签和事件组合在特定场景下都能触发脚本执行。攻击者不需要让页面“看起来不对劲”他只需要让浏览器执行他的代码就行了。而如果你在输出之前做了实体转义用户提交的内容会变成div classcomment 用户说lt;scriptgt;alert(xss)lt;/scriptgt; /div浏览器解析到lt;的时候知道这是一个字符实体会把它还原成显示出来但不会把它当作标签开始。最终页面上用户看到的就是一行纯文本用户说scriptalert(xss)/script。脚本不会执行攻击被挡住了。1.3 实体转义的边界不是所有字符都需要转义很多人一听到“转义”就紧张恨不得把所有特殊字符都转一遍。但实际上HTML 实体转义有明确的边界。在 HTML 文本内容也就是标签之间的文本节点中真正必须转义的只有三个字符、、。其中必须转义是因为它是实体引用的起始符号如果不转义浏览器会把后面的内容当作实体来解析可能导致显示异常。在 HTML 属性值中除了上面三个还需要额外处理引号。如果你用双引号包裹属性值那么属性值内部的必须转义为quot;如果用单引号包裹则必须转义为#39;。这是因为属性值的边界就是引号如果不转义属性值会被提前截断攻击者可以借此注入新的属性甚至新的标签。至于其他字符比如中文、数字、字母、常见的标点符号在 UTF-8 编码下都不需要转义。过度转义不仅没有必要还会让 HTML 源码变得难以阅读增加页面体积甚至在某些场景下引发二次解析问题。注意的转义有一个容易被忽略的细节——如果你先转义了和但没有转义那么用户输入的lt;会被浏览器解析成等于绕过了你的转义。所以转义的顺序很重要必须先把转成amp;再处理其他字符。2. 实体转义与 XSS 防御从原理到实战2.1 XSS 的三种类型与转义的对应关系XSS 通常被分为反射型、存储型和 DOM 型三类。这三种类型对实体转义的要求是不一样的不能一概而论。反射型 XSS 是用户提交的数据直接出现在响应页面中比如搜索关键词回显。这种场景下只要在服务端输出到 HTML 文本节点或属性值之前做实体转义就能有效防御。存储型 XSS 是用户提交的数据被保存到数据库然后在其他用户访问页面时被读取并输出。这种场景下转义的时机很关键——必须在输出时转义而不是在存储时转义。因为同一条数据可能被输出到 HTML 页面、JSON 接口、邮件正文、PDF 文件等不同媒介不同媒介需要的转义规则完全不同。如果在存储时就转义了输出到非 HTML 场景时就会显示成lt;这样的原始实体用户体验很差。DOM 型 XSS 比较特殊它不经过服务端而是前端 JavaScript 直接把用户输入插入到 DOM 中。比如element.innerHTML userInput这种写法如果 userInput 包含恶意标签就会被执行。防御 DOM 型 XSS 的关键是避免使用innerHTML、outerHTML、document.write等会解析 HTML 的 API改用textContent或innerText。如果确实需要插入 HTML必须先用前端的安全库做净化处理。2.2 输出编码转义的时机比方式更重要我在 review 代码的时候发现很多团队对“什么时候转义”这件事没有统一的认识。有人在后端 Controller 里转义有人在 JSP/Thymeleaf 模板里转义有人在前端 JS 里转义结果就是同一条数据被转义了两次甚至三次页面上显示出一堆amp;lt;这样的乱码。正确的原则是在数据即将输出到目标媒介的那一刻进行转义且只转义一次。对于 HTML 页面来说这个“时刻”就是模板引擎渲染的时候。现代模板引擎大多默认开启了自动转义比如 Thymeleaf 的th:text、Jinja2 的{{ }}、React 的 JSX 表达式都会自动对变量做 HTML 实体转义。你需要做的是确认这些自动转义没有被意外关闭而不是自己再手动转一遍。如果你用的是 JSP 的% %或者 FreeMarker 的${}那就要特别小心因为这些默认是不转义的。JSP 需要用c:out标签或者fn:escapeXml()函数FreeMarker 需要配置output_format为 HTML 或者手动加?html内置函数。2.3 富文本场景下的两难转义还是净化纯文本内容的转义很简单全部转掉就行。但富文本场景就麻烦了——用户需要加粗、斜体、链接、图片这些都需要保留 HTML 标签。如果你全部转义富文本就变成了纯文本功能就废了如果你不转义XSS 就来了。这个问题的标准解法是“白名单净化”。也就是说不是简单地转义或不转义而是用一个 HTML 净化库比如 Java 的 OWASP Java HTML Sanitizer、JS 的 DOMPurify来解析用户提交的 HTML只保留白名单内的标签和属性把其他所有内容都删掉或转义。白名单的配置需要根据业务需求来定。比如一个博客评论系统可能只允许b、i、a、code、pre这几个标签a只允许href属性且必须是http://或https://开头不允许javascript:协议。img标签如果允许的话要特别注意onerror事件和src属性中的data:URI。提示净化库的版本一定要保持更新。XSS 绕过手法层出不穷老版本的白名单可能已经被研究透了。我在实际项目里遇到过因为净化库版本太旧导致svg标签的某些属性绕过过滤的情况。2.4 Spring Boot 项目中的全局 XSS 过滤器实践在 Spring Boot 项目里比较常见的做法是写一个全局过滤器或者拦截器对所有请求参数做 XSS 清洗。但这里有一个很大的坑不要对请求参数做转义而应该做净化或标记。为什么因为请求参数可能在多个地方被使用——有的输出到 HTML有的输出到 JSON有的存数据库有的发邮件。如果你在过滤器里统一做了 HTML 实体转义那么输出到 JSON 接口时就会变成lt;这样的字符串前端拿到之后还得再反转义一次非常别扭。更合理的做法是过滤器只做危险字符的检测和拦截或者用净化库把明显的恶意标签删掉但不做实体转义。实体转义留给输出层去做。如果团队技术栈统一也可以考虑用 Spring Security 的HtmlUtils.htmlEscape()在需要的地方手动调用但一定要控制好调用点避免重复转义。对于文件上传场景比如上传 PDF 文件如果 PDF 内容会被解析并显示在网页上那就要特别小心。PDF 本身可以嵌入 JavaScript如果解析库没有做好隔离可能导致 XSS。这种情况下除了对解析后的文本做转义还要确保 PDF 解析库本身是安全的并且解析过程在沙箱环境中进行。3. 实体转义的完整实操从手工实现到框架集成3.1 手工实现一个可靠的转义函数虽然大多数时候我们用框架自带的转义功能就够了但理解手工实现的细节有助于排查问题。下面是一个 Java 版本的 HTML 实体转义函数覆盖了文本节点和属性值两种场景public class HtmlEscapeUtil { public static String escapeForText(String input) { if (input null) { return ; } StringBuilder sb new StringBuilder(input.length() 16); for (int i 0; i input.length(); i) { char c input.charAt(i); switch (c) { case : sb.append(amp;); break; case : sb.append(lt;); break; case : sb.append(gt;); break; default: sb.append(c); } } return sb.toString(); } public static String escapeForAttribute(String input) { if (input null) { return ; } StringBuilder sb new StringBuilder(input.length() 16); for (int i 0; i input.length(); i) { char c input.charAt(i); switch (c) { case : sb.append(amp;); break; case : sb.append(lt;); break; case : sb.append(gt;); break; case : sb.append(quot;); break; case \: sb.append(#39;); break; default: sb.append(c); } } return sb.toString(); } }这个实现的关键点在于先处理再处理其他字符。如果顺序反了被转成lt;之后又被转成amp;结果就变成了amp;lt;页面上会显示成lt;而不是。3.2 前端 JavaScript 中的转义与反转义前端场景下如果你需要手动转义可以用 DOM API 来实现比手写字符串替换更可靠function escapeHtml(text) { const div document.createElement(div); div.appendChild(document.createTextNode(text)); return div.innerHTML; } function unescapeHtml(html) { const div document.createElement(div); div.innerHTML html; return div.textContent || div.innerText || ; }escapeHtml的原理是利用createTextNode把文本作为纯文本节点插入然后读取innerHTML浏览器会自动把特殊字符转义成实体。unescapeHtml则相反把实体字符串作为 HTML 解析然后读取textContent拿到纯文本。但要注意unescapeHtml如果用在不可信的输入上是有 XSS 风险的因为innerHTML会解析并执行脚本。所以反转义只应该用在你自己完全可控的、已经确认安全的字符串上。3.3 模板引擎的自动转义配置清单不同模板引擎的自动转义行为差异很大我整理了一个对照表方便你快速确认自己项目里的配置是否正确模板引擎默认是否转义关闭转义的方式手动转义的方式Thymeleaf是th:utextth:textJSP EL否默认不转义c:out或fn:escapeXml()FreeMarker否需配置?html关闭${value?html}Velocity否默认不转义$esc.html($value)Jinja2是|safe过滤器{{ value }}Handlebars是{{{ }}}{{ }}React JSX是dangerouslySetInnerHTML{value}Vue是v-html{{ value }}这张表里最需要警惕的是 JSP EL 和 FreeMarker因为它们的默认行为是不转义的很多老项目迁移过来的时候容易忽略这一点。Thymeleaf 和 React 的默认转义做得比较好但也要注意不要滥用th:utext和dangerouslySetInnerHTML。3.4 邮件模板中的转义陷阱HTML 邮件的转义是一个容易被忽视的领域。邮件客户端对 HTML 的解析规则和浏览器不完全一样有些客户端会过滤掉style标签有些会限制外部资源加载有些甚至会把整个邮件内容当作纯文本显示。在邮件模板里做转义除了标准的、、、引号之外还要注意换行符的处理。HTML 里换行符默认会被折叠成空格如果你希望保留换行需要把\n转成br但br本身又需要是“可信的”标签不能被转义。所以邮件模板的转义策略通常是先对用户输入做实体转义然后再把转义后的换行符替换成br。另外邮件里的链接href属性要特别小心。如果用户输入的内容被拼接到href里必须确保协议是http或https并且对 URL 做编码。javascript:协议在邮件客户端里可能不会执行但某些 webmail 客户端会把它当作普通链接渲染点击后仍然有风险。4. 常见问题与排查技巧实录4.1 转义后显示异常的问题排查问题一页面上显示lt;而不是。这是最典型的“双重转义”问题。原因是你对已经转义过的字符串又转义了一次。排查方法是检查数据流经的每一个环节数据库里存的是什么后端返回给前端的是什么模板渲染时有没有再转一次浏览器控制台里看到的响应内容是什么一个实用的排查技巧是在浏览器里查看页面源代码不是审查元素搜索amp;lt;。如果找到了说明至少转义了两次。amp;lt;在页面上会显示成lt;而lt;在页面上会显示成。问题二属性值被截断页面布局错乱。这通常是因为属性值里的引号没有转义。比如value用户输入 onclickalert(1)如果用户输入里包含双引号属性值会被提前闭合后面的内容被解析成新属性。解决方法是在属性值场景下除了、、还要转义和。问题三JSON 接口返回的内容里包含lt;。这是因为在服务端做了 HTML 实体转义但接口是给前端 JS 消费的前端拿到lt;之后直接显示用户看到的就是lt;而不是。正确的做法是JSON 接口返回原始数据由前端在渲染到 HTML 时做转义。如果前端用的是 React/Vue模板里用{{ }}或{value}就会自动转义。4.2 XSS 过滤器绕过案例与加固建议我在测试自己写的过滤器时发现过几个典型的绕过手法这里分享出来方便你在做安全测试时参考。绕过一大小写混合。ScRiPtalert(1)/ScRiPt这种写法如果过滤器只匹配小写的script就会被绕过。加固方法是先把输入统一转成小写再匹配或者用正则的不区分大小写模式。绕过二标签嵌套。scrscriptiptalert(1)/script这种写法如果过滤器只做一次替换把中间的script删掉之后剩下的script又拼成了一个完整的标签。加固方法是循环替换直到没有匹配为止或者用净化库而不是简单的字符串替换。绕过三属性中的事件。img srcx onerroralert(1)这种不依赖script标签的攻击如果过滤器只过滤script就完全挡不住。加固方法是白名单净化只允许安全的标签和属性。绕过四编码变形。#60;script#62;这种实体编码形式如果过滤器在解码之前就做匹配可能匹配不到。加固方法是先解码再匹配或者直接用净化库处理。注意自己写 XSS 过滤器是一件吃力不讨好的事情。除非你有充足的安全测试资源否则建议直接使用成熟的净化库。OWASP Java HTML Sanitizer 和 DOMPurify 都是经过大量实战检验的选择。4.3 常见问题速查表现象可能原因排查方法解决方案页面显示lt;双重转义查看页面源代码搜索amp;lt;去掉一处转义脚本被执行未转义或转义不完整检查输出点是否用了自动转义补上转义或改用净化库属性值截断引号未转义检查属性值中是否包含引号转义和JSON 接口返回实体服务端做了 HTML 转义检查接口返回的原始字符串接口返回原始数据前端渲染时转义富文本标签被显示为文本全部转义了检查是否用了th:text而非th:utext改用净化库处理富文本邮件内容换行丢失换行符未转br检查邮件模板的换行处理转义后替换\n为br4.4 我踩过的几个坑第一个坑是在一个老项目里JSP 页面用% request.getParameter(name) %直接输出没有任何转义。我当时以为前端 JS 里做了处理结果前端只是把值赋给了innerHTML双重漏洞叠加一个简单的img srcx onerroralert(1)就能弹窗。后来改成c:out value${param.name} /才解决。第二个坑是在处理 PDF 上传时解析库把 PDF 里的文本提取出来之后我直接拼接到 HTML 里显示。PDF 里的文本可能包含script标签而且 PDF 解析库本身也可能有漏洞。后来加了两层防护解析过程在独立进程中运行解析结果做实体转义后再输出。第三个坑是邮件模板。我用 FreeMarker 写邮件模板忘了配置output_format结果用户昵称里的直接把邮件 HTML 结构搞乱了。后来在模板开头加了#ftl output_formatHTML才解决。5. 从转义到整体安全构建多层防御体系5.1 输入验证与输出转义的配合实体转义是输出层的防御手段但它不应该成为唯一的防线。在输入层做验证可以提前拦截掉大量明显恶意的请求减轻输出层的压力。输入验证的原则是“白名单优于黑名单”。比如用户名字段可以限制只允许中文、字母、数字、下划线长度不超过 20 个字符。这样即使输出层忘了转义攻击者也无法输入script这样的内容。但要注意输入验证不能替代输出转义因为有些字段比如评论内容本身就需要允许特殊字符输入验证只能做长度和格式的限制。5.2 Content-Security-Policy 的兜底作用CSP内容安全策略是一个 HTTP 响应头可以告诉浏览器只允许加载和执行来自特定来源的脚本。即使攻击者成功注入了script标签如果 CSP 配置了script-src self内联脚本也不会被执行。CSP 的配置需要根据项目实际情况来定。一个比较严格的配置是Content-Security-Policy: default-src self; script-src self; style-src self unsafe-inline; img-src self data:; object-src none这个配置的意思是默认只允许加载同源资源脚本只允许同源样式允许同源和内联图片允许同源和 data URI禁止加载插件对象。object-src none可以防御 Flash 等插件相关的攻击。CSP 不能替代实体转义但它是一个很好的兜底措施。即使转义出了问题CSP 也能挡住大部分 XSS 攻击。5.3 安全编码规范与代码审查要点最后我想强调一下团队规范的重要性。实体转义这件事靠个人自觉是不够的必须写进团队的编码规范并且在代码审查时重点检查。代码审查时我会重点关注这几个点有没有直接拼接 HTML 字符串的地方模板里有没有用不转义的输出语法前端有没有用innerHTML或dangerouslySetInnerHTML富文本处理有没有用净化库文件上传解析后的内容有没有做转义把这些检查点固化到 CI 流程里用静态代码分析工具比如 SonarQube 的 XSS 规则自动扫描可以大大降低遗漏的风险。我在实际项目中的体会是实体转义这件事知道的人很多但真正做对的人不多。问题往往不出在“不知道要转义”而是出在“转义错了地方”或者“转义了但没完全转义”。希望这篇文章里的这些细节和踩坑记录能帮你在下次遇到类似问题时少走一些弯路。如果你正在处理一个涉及用户输入输出的系统不妨现在就打开代码搜一下innerHTML和%看看有没有需要加固的地方。