Laravel富文本HTML净化与XSS防御实践

1. 先把问题说清楚：为什么富文本入库前必须过一道净化

做过内容型产品的人大概都遇到过这样的场景：后台编辑器里好好的文章，前台一展示就冒出莫名其妙的弹窗，或者页面某个角落突然多出一块来路不明的区域。追查下去，十有八九是用户提交的富文本里混进了不该有的标签和属性。HTML 净化这件事，平时不起眼，一旦出事就是整站级别的麻烦。这篇内容我想把 Purifier for Laravel 这套组合从头到尾讲透——它是什么、能解决哪一类问题、配置怎么写、坑在哪里。适合已经用过 Laravel 一段时间、正在做内容审核或富文本存储的开发者，也适合刚接手一个老项目、发现富文本字段直接原样输出而睡不着的朋友。

先明确一点：HTML 净化不是简单的“把尖括号转义掉”。转义是输出层的编码手段，净化是输入层的白名单裁剪，两者解决的是不同层面的问题。Purifier 属于后者，它基于 HTMLPurifier 这个老牌库，做的事情是：给你一段包含任意标签的 HTML 字符串，它按照你预先定义的白名单，逐元素、逐属性地判断哪些该留、哪些该扔，最后返回一段符合标准、结构完整的 HTML。注意是“符合标准”，它会顺手修复嵌套错误、补全缺失的闭合标签，这一点在做内容展示时尤其有用，因为用户从 Word 或者某些编辑器里粘过来的 HTML，嵌套关系经常是一团乱麻。

1.1 XSS 的三个典型入口，富文本只是其中之一

聊净化绕不开跨站脚本。很多团队的安全意识停在“用户输入要转义”，但真正出问题的往往是那些“我们以为已经处理过”的地方。第一个入口是富文本字段本身，正文允许一部分 HTML，这时候不能用转义，因为一转义排版全废，只能用白名单裁剪。第二个入口是属性值，比如href里塞一段javascript:开头的伪协议，或者src里指向一个会执行脚本的地址，光过滤标签名没用，属性值必须单独管。第三个入口是标签名的大小写和畸形写法，比如大小写混写、标签内插入注释、嵌套断裂等，正则匹配在这种场景下几乎必挂，因为 HTML 的容错解析规则远比正则能表达的复杂。

这也是我不建议手写正则做净化的原因。有人写个preg_replace('/<script.*?<\/script>/is', '', $html)就上线了，结果遇到<scr<script>ipt>这种嵌套写法直接被绕过。浏览器在解析时会把内层标签剥掉，剩下的拼成一个完整的<script>，而你的正则一次扫描做完就不再复查了。HTMLPurifier 的做法是先按规范把 HTML 解析成 DOM 树，再对树上的每个节点做白名单判定，最后重新序列化输出。这个流程天然免疫上面那类嵌套绕过，因为解析和判定是两趟，判定看的是解析后的真实节点。

1.2 存储型与反射型的差别，决定了净化该放在哪一层

反射型的问题出在“数据回显到页面”这一步，防御点在输出层，做转义就够了。存储型不一样，恶意内容先进数据库，之后被任何页面读取都可能触发，防御点必须在入库前。有人会问：那我输出的时候再净化行不行？技术上可行，但代价很大。一是每次读取都要跑一遍净化，列表页一屏几十条内容，性能会明显吃紧；二是历史数据永远是脏的，你没法保证所有读取路径都记得调用净化；三是有些场景（比如导出发给别人、推送到第三方系统）根本不在你的渲染链路上，输出层拦不住。

所以我的习惯是：入库前净化一次，落库的是干净数据；输出时该转义的地方照常转义。两层各司其职，不互相替代。有人担心净化会丢内容，导致用户投诉，这个顾虑合理，解决办法是把白名单配得宽一点、把被过滤的内容记日志，而不是干脆不做。后面配置章节我会给几套不同严格程度的配置集，分别对应文章正文、评论、简介摘要这三种场景。

1.3 净化解决什么、不解决什么，边界要清楚

必须说清楚边界，否则容易产生虚假的安全感。HTML 净化能管住的：标签与属性的白名单、伪协议链接、内联样式里的危险表达式、非法嵌套导致的解析歧义、部分畸形编码绕过。它管不住的：纯文本字段里的语义风险、图片链接指向外部不可信资源导致的信息泄露、CSS 里通过外部资源加载产生的请求、以及业务层面的内容合规判断。还有一点常被忽略：净化只处理 HTML 字符串，如果你的接口同时接受 Markdown，那 Markdown 转 HTML 的那一步必须在净化之前完成，顺序反了等于白做。

另外一个实际边界是富媒体。HTMLPurifier 的标签体系相对保守，video、audio、source这些 HTML5 标签它原生不认识，你在白名单里写上去也会被丢掉。要支持得走自定义配置或者换思路，这部分我在进阶章节会展开。先把基础链路搭稳，再谈扩展，顺序别反。

2. 方案选型：为什么最后落到 HTMLPurifier 上

在 Laravel 生态里做 HTML 净化，能选的其实不多。我把常见的几种做法列一下，顺便说说各自的问题。第一种是strip_tags配合手工白名单，PHP 原生函数，快是真快，但它只处理标签名，属性一概保留，<a href="javascript:...">照样能过，而且它不修复结构，输出可能是残缺的。第二种是正则替换，前面已经说过问题。第三种是前端净化，比如在提交前用浏览器的 DOM API 清洗一遍，问题在于前端校验永远可以被绕过，直接调接口就跳过了。

第四种是各类 HTML Sanitizer 库，有的基于 HTML5 解析器，速度快、支持新标签，但配置项相对少，遇到需要精细控制属性的场景会捉襟见肘。第五种就是 HTMLPurifier，它的定位是“严格、可配置、符合规范”，代价是慢和配置复杂。在 Laravel 里最省事的接入方式是mews/purifier这个包，它把 HTMLPurifier 包了一层，提供配置文件、Facade、Blade 指令和容器绑定，省掉自己写 ServiceProvider 的功夫。

2.1 横向对比：四种做法的取舍

方案	标签控制	属性控制	结构修复	性能	新标签支持
strip_tags+ 手工白名单	支持	基本不支持	不支持	极快	好
正则替换	不可靠	不可靠	不支持	快	好
前端 DOM 清洗	支持	支持	部分	快	好
HTMLPurifier	精细	精细	支持	较慢	需扩展

这张表不是要贬低谁。如果你的场景是“只允许<b>、<i>、<p>三个标签，属性全部不要”，那strip_tags($html, '<b><i><p>')完全够用，没必要上重武器。真正需要 HTMLPurifier 的是那种“正文要保留排版、要允许链接和图片、要控制样式、还得修复用户粘贴带来的结构错乱”的场景。判断标准很简单：只要你的白名单里出现了带属性的标签，就该考虑上它。

2.2 白名单模型强在哪：默认拒绝，而不是默认放行

黑名单模型的问题在于“你不知道的东西就漏过去了”。浏览器每年都在增加新标签、新属性，攻击面是不断扩张的，黑名单永远追不上。HTMLPurifier 走的是白名单：只认配置里列出来的，其余一律丢弃；属性的处理更细，一个标签下允许哪些属性、属性值要满足什么格式，全部显式声明。这种模型的好处是稳定，即使将来浏览器支持了什么奇怪的新特性，只要你的白名单没加，它就不会出现在输出里。

我特别看重它对 URI 的处理。配置里有一组URI.AllowedSchemes，默认只放行http、https、mailto等少数几个，javascript:、data:这类默认被拦。这个默认值很关键，因为链接和图片是最容易夹带私货的地方，很多手写净化方案恰恰在这块失守。另外它会做二次编码检查，把实体编码、百分号编码还原后再判断协议，防止用编码绕过。

2.3 代价要认：慢、重、配置门槛高

说优点也要说代价。HTMLPurifier 的单次净化耗时跟文本长度基本线性相关，一段几千字的文章，在没有缓存命中的情况下，几十毫秒到上百毫秒都有可能。这个数字放在单条保存上无所谓，放在批量导入一万条的脚本里就要命了。所以缓存配置不是可选项，是必选项，后面单独讲。

第二个代价是配置复杂。它的配置项有成百上千个，命名风格还是HTML.Allowed、CSS.AllowedProperties这种点号分层，第一次看文档会有点懵。好消息是常用的就那么十几个，把这十几个吃透，剩下的遇到再查。第三个代价是新标签支持滞后，HTML5 的一些标签它不认识，需要打补丁或者绕路。这三点在选型时都要掂量。

3. 装起来：Laravel 集成落地的完整步骤

从零开始，一步步来。假设环境是 PHP 8.1 以上、Laravel 9 或 10，Composer 正常可用。第一步装包，命令很简单，在项目根目录执行composer require mews/purifier。这个包会连带把ezyang/htmlpurifier拉下来，不用单独装。装完检查一下php -m，确认mbstring和iconv两个扩展是开着的，HTMLPurifier 处理多字节字符依赖它们，缺了会报错，而且报错信息不太直观，容易误判成配置问题。

第二步发布配置文件，命令是php artisan vendor:publish --provider="Mews\Purifier\PurifierServiceProvider"。执行完会在config/下生成purifier.php。这个文件建议直接提交进版本库，不要放进 gitignore，因为它是净化策略的唯一事实来源，不同环境必须一致，不然会出现“本地测试没问题、线上一上线内容全空了”的经典事故。

第三步是确认自动发现。Laravel 5.5 之后包会自动注册服务提供者和 Facade 别名，一般不用手动改config/app.php。如果你的项目关掉了自动发现，那需要手动加：providers 数组里加Mews\Purifier\PurifierServiceProvider::class，aliases 数组里加'Purifier' => Mews\Purifier\Facades\Purifier::class。加完执行php artisan config:clear清一下配置缓存，这一步很多人忘，改完配置不生效十有八九是缓存没清。

3.1 配置文件骨架：先理解结构再改内容

打开生成的purifier.php，结构大概是这样的：顶层有encoding、finalize、precache、cachePath、cacheFileMode这几个通用项，下面一个settings数组，里面默认有一个default键，值是真正的 HTMLPurifier 配置数组。调用时传第二个参数就能切换到别的配置集。这个设计很实用，意味着你可以为不同业务场景准备多套白名单，而不是全站共用一套宽白名单。

// config/purifier.php 的骨架示意 return [ 'encoding' => 'UTF-8', 'finalize' => true, 'ignoreNonStrings' => false, 'cachePath' => storage_path('app/purifier'), 'cacheFileMode' => 0755, 'settings' => [ 'default' => [ 'HTML.Doctype' => 'HTML 4.01 Transitional', 'HTML.Allowed' => 'div,b,strong,i,em,u,a[href|title],ul,ol,li,p[style],br,span[style],img[width|height|alt|src]', 'CSS.AllowedProperties' => 'font,font-size,font-weight,font-style,text-decoration,padding-left,color', 'AutoFormat.AutoParagraph' => false, 'AutoFormat.RemoveEmpty' => true, ], ], ];

几个通用项的取舍：finalize建议保持true，它会在净化结束后再做一轮收尾清理，能处理掉一些边界情况。precache是预编译配置，开启后第一次运行会把配置编译成缓存文件，之后直接读缓存，对性能有好处，但改配置后记得清缓存。cachePath指向storage/app/purifier，这个目录必须可写，容器化部署时容易被漏掉。cacheFileMode设0755就够，不用给更高权限。

3.2 多配置集拆分：一套宽白名单走天下是事故源头

我见过不少项目全站就一套default，后台富文本、前台用户评论、商品简介全走它。结果是要么评论框能贴进来一堆花里胡哨的样式，要么商品简介里的换行全被吃掉。正确做法是按“谁提交、提交到哪、展示在哪”三个维度拆分。我的常规拆法是三套：article给后台编辑用，允许图片、表格、样式；comment给普通用户用，只留基础排版和链接；plain给摘要、标题这类纯文本字段用，标签全部不允许。

'settings' => [ 'article' => [ 'HTML.Allowed' => 'p[style],br,strong,em,u,h2,h3,h4,ul,ol,li,blockquote,a[href|title|target|rel],img[src|alt|width|height],table,thead,tbody,tr,th,td,code,pre,hr', 'CSS.AllowedProperties' => 'text-align,font-weight,font-style,text-decoration,color,background-color', 'AutoFormat.RemoveEmpty' => true, 'URI.AllowedSchemes' => ['http' => true, 'https' => true, 'mailto' => true], ], 'comment' => [ 'HTML.Allowed' => 'p,br,strong,em,a[href|rel]', 'AutoFormat.RemoveEmpty' => true, 'HTML.Nofollow' => true, ], 'plain' => [ 'HTML.Allowed' => '', 'AutoFormat.RemoveEmpty' => true, ], ],

调用时第二个参数写配置名：clean($html, 'comment')。这里有个细节要注意，HTML.Allowed为空字符串时不是“什么都不允许”，而是“使用默认白名单”。想彻底清空标签，得用HTML.AllowedElements配合空数组，或者干脆在净化前先strip_tags。这个坑我踩过，当时以为配了空就万事大吉，结果评论里还是能出<p>。

3.3 目录权限与首次运行的验证

配置改完，写个最简的验证脚本跑一下，别急着往业务里接。可以在php artisan tinker里直接试：Purifier::clean('<p onclick="alert(1)">test<script>alert(2)</script></p>', 'comment')。期望输出是<p>test</p>，onclick和script都该消失。如果输出为空，八成是缓存目录不可写；如果报错说找不到配置，检查配置缓存是否清过；如果script标签还在，说明配置根本没生效，回头看看调用时配置名有没有拼错。

第一次运行会在storage/app/purifier下生成缓存文件，这个目录的属主必须和 PHP 进程一致。本地开发一般没问题，容器里就经常翻车，因为构建镜像时目录是用 root 建的，运行时进程是 www-data。稳妥做法是在 Dockerfile 里显式chown，或者在容器启动脚本里跑一次chmod -R 775 storage加chown。这个问题排查起来很费时间，因为表现是“净化返回空字符串”，很难第一时间联想到权限。

4. 配置参数逐个啃：决定净化效果的那些开关

配置项看着多，真正天天打交道的不超过二十个。我按重要程度排一下，先讲最影响结果的几个。HTML.Allowed是白名单核心，格式是“标签名[属性1|属性2]”，多个用逗号分隔。注意属性必须显式写出来，不写就等于该标签下所有属性都不允许。这一点和很多人的直觉相反，以为写了标签就默认带常用属性，结果发现链接的href被吃掉了，其实是因为没在方括号里声明。

HTML.ForbiddenElements是黑名单补充，在白名单基础上再排除特定标签，一般用于临时封禁某个标签而不用改整个白名单。HTML.ForbiddenAttributes同理，格式是标签名.属性名。这两个我用得不多，因为白名单配好了基本不需要，但做灰度或者应急时挺方便。Core.Encoding一般不用改，保持 UTF-8，除非你的历史数据是别的编码。

4.1 HTML.Allowed 的写法细节与常见误配

属性写法里有个容易忽略的点：有些属性需要额外的配置项配合才能生效。比如target属性，你写在白名单里了，但输出里可能还是没有，因为 HTMLPurifier 默认会移除target，需要配Attr.AllowedFrameTargets。再比如rel属性，想让所有外链自动加nofollow，要开HTML.Nofollow而不是指望用户自己写。

'Attr.AllowedFrameTargets' => ['_blank'], 'HTML.Nofollow' => true, 'HTML.TargetBlank' => true,

HTML.TargetBlank这个开关很实用，开了之后所有带href的链接都会自动补上target="_blank"，不用依赖编辑器输出。配合HTML.Nofollow一起用，外链的 SEO 和体验问题一次解决。但要注意，如果你的站内链接也被加了_blank，体验会很怪，这时候得靠自定义过滤器按域名判断，标准配置做不到这么细。

还有一个误配高发区是style属性。你写了p[style]，以为样式就保住了，其实还需要CSS.AllowedProperties明确列出允许的 CSS 属性，没列的会被剥掉。很多人配完发现字体大小没了、颜色没了，就是这里漏了。CSS 属性的白名单建议宁少勿多，position、z-index、behavior这类涉及布局和脚本的坚决不给。

4.2 URI 与链接：最容易出事的一块

链接相关的配置是安全重灾区，值得单独说。URI.AllowedSchemes控制允许的协议，默认只放http、https、mailto、ftp、news、nntp、tel、urn这些。如果你的业务需要站内相对路径，那不用管，相对路径不涉及协议判定。如果允许用户填data:开头的图片（比如 base64 内联），那就得显式加，但我不建议加，data:协议在部分场景下有被滥用的风险。

图片域名这块，标准配置没有“只允许某几个域名”的开关。想实现这个，要么用自定义过滤器，要么在净化后过一遍正则校验src。我倾向于后者，实现简单、维护成本低。写个方法遍历输出里的img标签，逐个解析src的 host，不在白名单里的整条替换成占位图或者直接删掉。这个逻辑放在净化之后、入库之前，顺序别搞反。

URI.Base这个配置项一般不用改，它影响的是相对路径的解析基准，只在特定场景（比如把内容渲染到邮件里）才有意义。URI.DisableExternalResources倒是值得知道，开启后所有指向外部的资源引用会被清掉，适合对安全性要求极高、完全不允许外链资源的场景。

4.3 CSS 过滤：样式保真的边界在哪

富文本编辑器输出的内容，样式通常有两种形式：内联style和<style>标签。后者必须禁止，因为<style>标签会影响整页渲染，是个大隐患。HTMLPurifier 默认也不允许<style>标签，这点可以放心。内联样式则由CSS.AllowedProperties控制，只保留列出来的属性，其他一律剥掉。

我的建议是白名单尽量窄。排版类属性可以给：text-align、font-weight、font-style、text-decoration、color、background-color、line-height、margin、padding。涉及定位和层叠的一律不给：position、top、left、z-index、float、display。涉及外部资源加载的也不给：background-image、list-style-image。理由很直接，这几类属性要么能用来做点击劫持，要么能用来发起外部请求泄露信息。

配色还有个细节，color允许之后，用户能设成和背景同色，把内容“藏”起来，做内容审核时容易漏。如果产品对这块敏感，可以在净化后做一次对比度检查，或者干脆在展示层统一覆盖颜色。这是业务层面的取舍，不是净化库该管的事，但做内容型产品的人最好心里有数。

4.4 缓存配置：不配这个，性能会很难看

缓存相关的配置有两条路。一条是 HTMLPurifier 自己的定义缓存，Cache.DefinitionImpl控制，默认就是文件缓存，存在cachePath下。另一条是序列化缓存，Cache.SerializerPath指定路径，需要可写。mews/purifier的cachePath实际上同时服务于这两个，所以只要目录可写，基本就自动生效了。

如果发现净化特别慢，先看缓存目录里有没有生成文件。目录空的说明缓存没起作用，检查两件事：路径对不对、权限够不够。还有一种情况是每次请求都重新编译配置，原因是precache关了或者配置对象每次都是新建的。在 Laravel 里用 Facade 调用通常是单例，不太会遇到，但如果你在某个地方自己new了 Purifier 实例，那就等于每次都从头来一遍。

缓存文件里存的是编译后的配置定义，不是净化结果。所以改配置之后必须清缓存，否则新配置不生效。清的方式是php artisan config:clear加上手动删storage/app/purifier下的文件，两个都要做。

5. 落到代码里：入库、输出、校验三条链路

配置调好之后，接入业务的方式有三种，我按推荐程度排。最推荐的是在表单请求（FormRequest）的passedValidation或者控制器里净化，位置明确、链路短、好调试。次推荐是在模型层用访问器或者观察者做兜底，防止有别的地方绕过控制器直接写库。最不推荐的是在 Blade 模板里净化，因为那样每次渲染都要跑一遍，而且容易被忘掉。

5.1 表单请求里净化：位置明确，最好维护

在一个专用的 FormRequest 里做，能保证所有走这个请求类的入口都被覆盖。写法上可以覆写passedValidation方法，在验证通过之后、控制器拿到数据之前处理。好处是不动控制器代码，职责清晰。

class StoreArticleRequest extends FormRequest { public function rules(): array { return [ 'title' => ['required', 'string', 'max:120'], 'content' => ['required', 'string', 'max:200000'], ]; } protected function passedValidation(): void { $this->merge([ 'content' => clean($this->input('content'), 'article'), ]); } }

用clean()这个全局辅助函数比用 Facade 少一行 use，读起来也顺。但要注意merge之后validated()拿到的才是净化后的值，如果控制器里用的是$request->input()，那拿到的也是新值，因为merge会覆盖。这里有个小陷阱：如果同一个请求里还有别的字段需要原始值比对（比如做变更日志），记得在merge之前先存一份。

5.2 模型层兜底：防止绕过控制器直接写库

有些项目会有命令行脚本、队列任务、后台导入这些不走 HTTP 的入口，光在请求层做净化会漏。稳妥做法是在模型上再挂一层，用观察者的saving事件处理。这样无论从哪进来，落库前都会过一遍。代价是可能重复净化（请求层已经处理过，模型层又跑一遍），所以要在模型层判断一下内容是否已经处理过，或者干脆只保留模型层这一道。

protected static function booted(): void { static::saving(function (Article $article) { if ($article->isDirty('content')) { $article->content = clean($article->content, 'article'); } }); }

只处理脏字段这一句很关键，不然每次保存都会重跑一遍全部内容，长文章上性能差别明显。用访问器（Accessor）也行，但访问器是在读取时生效，入库的还是脏数据，不符合“脏数据不进库”的原则。所以观察者比访问器更合适，除非你的场景是历史数据不想动，只在读取时净化。

5.3 输出环节：转义和净化不是二选一

净化之后，输出时该转义的地方还是要转义。Blade 的{{ }}会自动转义，但对于已经净化过的富文本，你得用{!! !!}才能保留标签。这时候的风险点是：万一某条历史数据没经过净化，直接{!! !!}输出就出事了。所以我的做法是给富文本字段统一走一个自定义 Blade 指令或者组件，在组件内部做一次轻量校验，确认内容里没有危险标签再输出。

{{-- 推荐：统一入口，便于将来加逻辑 --}} <x-rich-text :content="$article->content" /> {{-- 不推荐：散落在各处的裸输出 --}} {!! $article->content !!}

组件里可以顺手做一些展示层的事，比如给所有图片加loading="lazy"、给外链加rel="noopener"。这些在净化阶段做也行，但放在展示层更灵活，改起来不用动配置。原则是：净化管安全，展示管体验，别混在一起。

6. 性能与稳定性：大文本、批量导入与缓存调优

净化慢不慢，取决于三个变量：文本长度、配置复杂度、缓存是否命中。一段五百字、配置简单的评论，命中缓存后单次耗时通常在个位数毫秒。一段两万字、带表格和样式的文章，配置复杂、缓存没命中，上百毫秒也正常。这个量级在单个保存请求里完全可接受，问题出在批量和列表场景。

6.1 单次请求的耗时构成与优化顺序

拆开看，耗时主要花在三块：解析 HTML、逐节点做白名单判定、重新序列化。配置编译的耗时被缓存吃掉了，所以优化空间主要在文本本身。文本越长，三块都线性增长。能做的优化有限，但有几个点值得注意。第一，净化前先做一次长度校验，超过上限的直接拒绝，别让它进净化流程，两万字以上的富文本本身就是异常。第二，不要在循环里反复调用同一套配置，虽然配置是复用的，但每次调用仍会新建内部对象，量大了有开销。第三，能用简单方案的地方别用重武器，比如摘要字段，直接strip_tags加截断就够了，没必要上净化。

6.2 批量导入的处理策略

后台导入历史数据、迁移老站内容这类场景，一次几千上万条，逐条净化会跑很久。我的做法是分片加队列。把待处理数据按五百条一批切分，每批丢进队列任务，任务里逐条净化、批量更新。这样既不占请求线程，也能控制内存。分片大小不是拍脑袋定的，要看你单条内容的平均长度和 PHP 的memory_limit，一般五百到一千条一批比较稳。

还有一个细节：批量导入时要不要走模型观察者？如果走，那队列任务里就不用再调一次净化；如果不走（比如用DB::table()->insert()直接插），那必须在任务里手动调。两条路选一条，别混着来，混着来就是重复净化，耗时翻倍还不说，还可能因为二次净化把某些边缘内容吃掉。

6.3 缓存目录的运维问题

缓存目录最常出的两个问题：权限和清理。权限问题前面说过，这里补一个现象：净化返回空字符串，日志里没有明显报错，这时候先去看storage/logs/laravel.log，通常会有 HTMLPurifier 抛出的警告，提示某个路径不可写。清理问题指的是缓存文件越积越多，尤其是有多套配置集的时候，每个配置集一份缓存，改配置后旧文件不会自动删。定期清一下没坏处，加到部署脚本里，一条命令的事。

容器化部署还有一点要留心：不要把storage/app/purifier打进镜像里，因为镜像构建时的缓存文件属主和运行时不一定一致，容易踩权限坑。正确做法是运行时创建、运行时写入缓存的机制，权限跟着进程走。这一点在小项目里不明显，一旦上了多副本、滚动更新，问题就会冒出来。

7. 常见问题排查速查表

下面这些是我在实际项目里遇到过、或者帮人看过的问题，按现象整理成表，方便对照。

现象	可能原因	排查动作
净化后内容是空字符串	缓存目录不可写	检查storage/app/purifier属主与权限
标签全被剥掉，只剩纯文本	HTML.Allowed没配或配错	确认调用时传入的配置名存在
样式全丢	没配CSS.AllowedProperties	补上需要的 CSS 属性
链接的href消失	白名单里没写a[href]	补属性声明
target不生效	缺Attr.AllowedFrameTargets	显式配置允许的 target
图片不显示	src域名被规则拦截或协议不在白名单	检查URI.AllowedSchemes与图片域名
视频、音频标签被吃	HTML5 标签不被原生支持	走自定义配置或换方案
改了配置不生效	配置缓存未清	config:clear加删缓存文件
长文章净化超时	无分片、无缓存	拆分处理、确认缓存命中

7.1 内容被吃光这类问题怎么快速定位

“净化后变空”是最让人慌的现象，但原因往往很单纯。按顺序排查三步：第一步，直接跑一个最小用例，clean('<p>hello</p>')，如果这个也返回空，问题在环境不在配置，十有八九是缓存目录。第二步，如果最小用例正常，把真实内容截一半再试，二分定位是哪段内容触发的。第三步，找到触发段后看它有什么特征，常见的是超大文本、异常字符、未闭合标签嵌套过深。

还有一种少见情况：某些控制字符会让解析器提前终止。从 Word 或者 PDF 复制的文本里偶尔会带这类字符，肉眼看不见，但在十六进制里能看到。处理办法是在净化前先做一次字符清洗，把不可见控制字符剔掉。这个步骤建议常备，成本很低，能避免很多莫名其妙的排查。

7.2 富媒体支持的现实做法

video、audio、iframe这三类是绕不开的需求。iframe相对好办，有官方支持的配置：开HTML.SafeIframe，再配URI.SafeIframeRegexp限定只能嵌入指定域名。注意正则要写严，别写成宽松匹配，否则等于开了个后门。

'HTML.SafeIframe' => true, 'URI.SafeIframeRegexp' => '%^//player\.example\.com/embed/%',

video和audio就没这么顺，因为 HTMLPurifier 的标签定义里没有它们。有两条路：一是自定义标签定义，通过扩展机制注册新元素和属性，工作量中等，需要读一下库的扩展文档；二是在净化之后单独处理，先净化再把你信得过的视频标签用占位符还原回去。第二条路简单粗暴，但安全性依赖你还原逻辑写得够严，我只在小范围、内容来源可控的场景下用。

7.3 升级兼容：版本变化带来的行为差异

mews/purifier和底层库都在维护，升级后行为可能有细微变化。我印象比较深的是几个大版本之间，配置项命名和默认值调整过，升级后原来的白名单可能少生效几个属性。稳妥的升级流程是：先在测试环境升级，跑一遍典型的净化用例，对比升级前后的输出差异，确认没有意外再上线。用例不用多，覆盖文章、评论、纯文本三套配置各三五条就行，重点看标签和属性有没有被多删。

另外，PHP 版本升级也可能带来影响，主要是多字节处理和正则引擎的细微差异。如果项目里有自定义过滤器，升级 PHP 大版本后一定要回归测试，因为过滤器里通常有自己的字符串处理逻辑，容易受这些差异影响。

8. 一些进阶玩法

基础链路跑稳之后，可以做一些提升。这些不是必须的，但用好了能省不少事。

8.1 自定义过滤器注入

HTMLPurifier 支持注册自定义过滤器，在净化流程的特定阶段插入自己的逻辑。典型用途是给所有外链统一加rel="noopener noreferrer"、给图片统一补loading="lazy"、或者把特定域名的图片替换成占位图。注册方式是在配置里挂HTML.DefinitionID和自定义的 URI 过滤器，或者通过包提供的扩展点实现。这块的门槛在于要理解库内部的处理阶段划分，建议先把官方扩展文档过一遍再动手。

一个实用的用法是内容统计。在过滤器里顺手数一下被删掉了多少标签、多少属性，落个日志。时间长了你能看出用户都在提交什么、白名单是不是配窄了，比拍脑袋调整靠谱得多。我们之前就是靠这个日志发现某个编辑器会输出一个不在白名单里的标签，导致用户排版老是乱，加上之后投诉明显减少。

// 自定义过滤器的思路示意，不是完整实现 class LinkRelFilter { public function handle($html): string { return preg_replace_callback( '/<a\s+[^>]*href="([^"]+)"[^>]*>/i', function ($m) { $host = parse_url($m[1], PHP_URL_HOST); $rel = $host && $host !== request()->getHost() ? ' rel="noopener noreferrer nofollow"' : ''; return rtrim($m[0], '>') . $rel . '>'; }, $html ); } }

这种后处理式过滤器写起来简单，但要注意它是在净化之后跑的，处理的是已经干净的 HTML，不要再引入新的风险。正则只做属性追加这种低风险操作，别用它做标签删除。

8.2 中文与全角字符的处理细节

中文场景有两个小坑。第一个是全角空格和特殊空白字符，用户从某些地方粘贴过来会带这些字符，净化后可能被保留下来，导致排版出现莫名缩进。处理办法是在净化前统一替换成普通空格。第二个是编码声明，如果输入内容的编码和配置的Core.Encoding不一致，可能出现乱码或者内容被截断。统一在入口处做编码转换，代价很小。

还有一个容易被忽略的点：中文内容里的标点符号如果被包在标签里，净化时可能因为标签边界判断出问题。比如一段话被错误地拆成多个span，净化后可能变成多个段落。这属于源头编辑器的问题，净化只能尽量修复，根治要靠规范编辑器输出。

8.3 和编辑器输出格式对齐

不同富文本编辑器的输出风格差别很大，有的输出大量嵌套span和行内样式，有的输出干净的语义标签。净化配置要和编辑器对齐，否则要么白名单太宽导致样式混乱，要么太窄导致排版丢失。我的建议是选一个输出风格克制的编辑器，然后在保存时做一次格式归一化，把无意义的嵌套span合并掉，把行内样式里重复的声明去重。

这个归一化步骤放在净化之后做比较合适，因为净化已经保证了标签集合是受控的，归一化只需要处理结构。实现上可以用 DOM 遍历，逐节点判断，逻辑不复杂但要注意性能，大文本上遍历两遍会有感知。如果流量大，可以考虑放到异步任务里做，保存时先入库，稍后异步归一化。

9. 我个人踩坑后的几条经验

最后说几条纯经验的东西，都是踩过之后才记住的。第一条，配置一定要进版本库，而且要写注释说明每套配置给哪个场景用。我见过配置文件被某个人临时改宽然后忘了改回来，结果评论框里能贴表格，前端样式直接崩。第二条，净化之后要有一个“内容长度预警”，如果某条内容净化前一万字、净化后只剩几百字，说明白名单漏了重要标签，这种要能在日志里看到，而不是等用户来投诉。

第三条，历史数据的净化要单独规划。老项目里往往有一批从来没净化过的内容，直接全量跑一遍风险不小，可能把正常排版洗掉。稳妥做法是先抽样跑、人工比对、调整配置，再分批全量。跑的时候保留原始内容副本，万一出问题能回滚。第四条，别指望一套配置解决所有场景，也别搞出十几套配置没人记得住。三到五套是比较舒服的区间，每套有明确的适用场景和负责人。

第五条，也是最重要的一条：净化只是防线之一，不是全部。输出转义、内容安全策略、图片域名白名单、审核流程，这些要一起上。把全部希望压在一个库上，早晚会失望。真正稳的做法是多层防御，每层都简单可靠，任何一层失守还有其他层兜着。我在实际项目里就是这么干的，净化管入库，转义管输出，白名单管外链，各管一段，互不越界，出问题时定位也快，看一眼是哪层没拦住就知道该改哪里。