DOMPurify 完整介绍

一、一句话定义

DOMPurify 是业界最主流、安全可靠的 JS HTML 清洗库，专门用来过滤脏 HTML、防御 XSS 跨站脚本攻击，把用户输入的危险代码清理干净，输出可安全插入页面的纯净 HTML，同时支持 SVG、MathML 清洗npm。

二、核心作用（解决什么问题）

网页最常见漏洞：XSS 攻击 当你直接把用户输入 / 后端富文本用 innerHTML、Vue v-html、React dangerouslySetInnerHTML 渲染时，恶意用户会注入：

xml 复制代码

<!-- 攻击代码示例 -->
<img src=x onerror="窃取cookie、劫持账号">
<a href="javascript:盗号脚本">点我</a>
<svg onload="恶意代码"></svg>
<script>木马</script>

DOMPurify 会自动删除 / 清空所有可执行代码，只保留安全标签与属性。

清洗效果示例

scss 复制代码

// 脏内容
const dirty = '<img src=x onerror=alert(1)><script>stealCookie()</script>'
// 清洗后
DOMPurify.sanitize(dirty)
// 输出：<img src="x">

三、工作原理（比正则过滤强在哪）

不用正则匹配：正则很容易被攻击者绕过；
调用浏览器原生 DOM API，把 HTML 解析成真实 DOM 树；
遍历所有节点，对照内置安全白名单：
- 删除危险标签：<script>、<iframe>、<svg onxxx>
- 清除事件属性：onclick、onerror、onload
- 拦截危险协议：javascript:、data:、vbscript:
把过滤后的干净 DOM 转回 HTML 字符串返回DOMPurify。

四、适用场景（前端必用场景）

富文本编辑器（评论、发帖、公告、工单）
Vue v-html / React dangerouslySetInnerHTML 渲染内容
展示后端返回的自定义 HTML、Markdown 转 HTML
渲染用户上传 SVG、富文本邮件内容
读取 URL 参数、localStorage 内容插入页面（防 DOM-XSS）

五、关键特性

跨环境：浏览器全兼容、Node.js（搭配 jsdom）、SSR、Electron；
可自定义白名单：允许 / 禁用指定标签、属性、图片协议；
体积小：压缩后约 15KB，性能极高；
持续更新安全规则，能防御各种变形绕过 XSS；
支持钩子函数，自定义清洗逻辑。

六、极简使用示例

1. 安装

bash 复制代码

npm install dompurify
# 配套类型提示（TS项目）
npm install @types/dompurify -D

2. 基础调用

javascript 复制代码

import DOMPurify from 'dompurify'

// 清洗用户输入
const unsafeHtml = '<p>内容<img src=x onerror=alert(1)></p>'
const safeHtml = DOMPurify.sanitize(unsafeHtml)

// 安全渲染到页面
document.body.innerHTML = safeHtml

3. Vue v-html 标准写法

xml 复制代码

<template>
  <div v-html="safeContent"></div>
</template>
<script setup>
import DOMPurify from 'dompurify'
const rawHtml = ref(后端返回的富文本)
const safeContent = computed(() => DOMPurify.sanitize(rawHtml.value))
</script>

4. 自定义配置（允许 iframe、自定义属性）

php 复制代码

// 允许iframe、允许data图片
const clean = DOMPurify.sanitize(html, {
  ADD_TAGS: ['iframe'],
  ADD_ATTR: ['allow'],
  ALLOWED_DATA_URI_IMAGES: true
})

七、常见误区

只后端过滤，前端不用 DOMPurify前端 DOM-XSS（URL 参数、本地存储）后端拦截不到，必须前端再清洗一层；
自己写正则过滤 script/onerror攻击者有上百种绕过写法，正则防不住；
清洗一次永久安全 每次渲染动态 HTML 都要重新走 sanitize；
以为框架自带防护：Vue/React 只转义文本，v-html /dangerouslySetInnerHTML 完全不防 XSS，必须搭配 DOMPurify。

八、功能

但凡页面需要动态渲染不受信任的 HTML，DOMPurify 是行业标准安全方案，是防御存储型、DOM 型 XSS 最通用、最低成本的手段。