12k
All articles

在 React 中使用 Trusted Types 阻断 DOM XSS

了解如何在React 19.3中启用Trusted Types防范DOM XSS,并配置DOMPurify策略、CSP标头及安全的仅报告模式部署。

OpenReplay Team
OpenReplay Team
在 React 中使用 Trusted Types 阻断 DOM XSS

React 19.3 会将 Trusted Types 对象直接传递给 DOM,因此 React 应用现在可以强制执行 require-trusted-types-for 'script',并让所有 dangerouslySetInnerHTML 标记都经过一个基于 DOMPurify 的策略(policy)处理。

在此版本之前,这套方案往往无法正常工作:你对 CMS 中的 HTML 做了净化,启用了 CSP 指令,结果 React 还是把你精心构造的类型化值转换回了字符串。

本文将介绍 React 的这项变更、CSP 响应头配置、一个在不支持该 API 的浏览器中同样可用的策略模块,以及一套从仅报告模式起步的上线流程。关于 XSS 的基础知识,请参阅防范用户生成内容中的 XSS。

要点速览

  • 在 React 19.3 之前,React 通过 '' + value 将值转换为字符串,因此传给 dangerouslySetInnerHTML 的 TrustedHTML 对象到达 innerHTML 时已变成普通字符串,处于强制模式的浏览器会拒绝该赋值。
  • 在 require-trusted-types-for 'script' 下,向 innerHTML 等注入接收点(sink)赋值普通字符串会抛出 TypeError。
  • Trusted Types 本身不做任何净化。它确保 HTML 必须经过你编写的策略才能到达接收点,真正的清理工作由策略内部的 DOMPurify 完成。
  • 先部署 Content-Security-Policy-Report-Only,修复所有被报告的接收点,再通过 trusted-types 将策略名称加入允许列表,最后开启强制模式。
  • 不支持 Trusted Types 的浏览器不会执行任何强制检查,因此策略中的净化器必须在每次调用时都运行。

React 19.3 有哪些变化?

React 19.3(于 2026 年 9 月 9 日发布)会将 TrustedHTML、TrustedScript 和 TrustedScriptURL 值原样传递给 DOM,不再进行类型强制转换。这样浏览器就能校验这些值是否由 Trusted Types 策略生成。

早期版本在将值交给 DOM API 之前,会先用 '' + value 将其字符串化。因此,传给 dangerouslySetInnerHTML 的 TrustedHTML 对象到达 innerHTML 时已是普通字符串,处于强制模式的浏览器会拒绝它。发布公告以 innerHTML 作为接收点示例,而写入 innerHTML 的 dangerouslySetInnerHTML 现在会保留该受信任对象。同一版本还让 Fragment refs 进入了稳定状态。

Trusted Types 如何阻断 DOM XSS?

Trusted Types API 会禁止原始字符串进入注入接收点。一旦启用强制模式,innerHTML 或脚本的 src 等接收点只接受由具名策略创建的类型化对象。

受信任类型接收点类别接收点示例
TrustedHTMLHTML 解析Element.innerHTML
TrustedScript脚本文本eval()
TrustedScriptURL脚本加载HTMLScriptElement.src

Trusted Types 本身不会清理任何标记。它所保证的是:每个到达接收点的值都经过了某个策略函数,而 DOMPurify 正是在这个函数中发挥作用。这改变了安全模型:净化不再依赖每位开发者在每个调用点都记得去做,而是由浏览器强制执行。

设置 Content-Security-Policy 响应头

Trusted Types 通过 CSP 指令 require-trusted-types-for 'script' 启用。首先,在 Content-Security-Policy-Report-Only 中发送该指令。在此模式下,浏览器会报告违规行为,但仍允许代码运行。

Content-Security-Policy-Report-Only: require-trusted-types-for 'script'

使用 report-to 指令添加报告端点,这样浏览器会将每个违规接收点发送到你的收集服务,而不只是在控制台中输出日志。待报告不再出现后,切换到强制模式的响应头:

Content-Security-Policy: require-trusted-types-for 'script'; trusted-types app-html

require-trusted-types-for 会让向接收点赋值字符串的操作抛出异常。trusted-types 列出允许使用的策略名称,如果调用 trustedTypes.createPolicy() 时使用的名称不在列表中,就会抛出异常。请以响应头的形式发送这些指令,因为浏览器不支持在 <meta> 标签中使用仅报告响应头或 report-to 指令。

创建封装 DOMPurify 的策略

在 React 应用中,应在模块作用域内只创建一次 Trusted Types 策略,并在需要的地方导入使用。除非 trusted-types 指令中包含 'allow-duplicates',否则 createPolicy() 在遇到重复名称时会抛出 TypeError。因此组件函数体并不适合放置这段代码,因为 React 会重新渲染组件,而 StrictMode 还会对组件进行双重调用。

// trusted-html.js
import DOMPurify from 'dompurify';

const factory = globalThis.trustedTypes ?? {
  createPolicy: (name, rules) => rules,
};

export const htmlPolicy = factory.createPolicy('app-html', {
  createHTML: (dirty) =>
    DOMPurify.sanitize(dirty, { TRUSTED_TYPES_POLICY: null }),
});

createHTML 返回净化后的字符串,浏览器再将其包装为 TrustedHTML。传入 TRUSTED_TYPES_POLICY: null 可阻止 DOMPurify 创建其内部的 dompurify 策略,这样允许列表中只需包含 app-html。不要在 createHTML 中使用 RETURN_TRUSTED_TYPE: true,因为该回调必须返回普通字符串。

这个回退对象借鉴了 MDN 的 tinyfill 思路,并改写为适用于 ES 模块的形式。在不支持该 API 的环境中,createPolicy 会原样返回你的规则对象,因此 htmlPolicy.createHTML() 依然会运行 DOMPurify 并返回字符串,所有环境下的代码路径都保持一致。由于回退对象是局部定义的,该模块在服务端渲染期间(此时 trustedTypes 未定义)也能正常导入而不报错。DOMPurify 在服务端执行净化需要一个 DOM 实现,相关配置可参阅其 README。

DOMPurify 还提供了一种快捷方式:不创建自己的策略,直接调用 DOMPurify.sanitize(dirty, { RETURN_TRUSTED_TYPE: true })。在受支持的浏览器中它会返回 TrustedHTML,此时需要将 dompurify 加入允许列表(trusted-types app-html dompurify)。

将策略与 dangerouslySetInnerHTML 配合使用

在 React 19.3 及更高版本中,将策略的输出放入 __html,React 就会把 TrustedHTML 对象原封不动地传递给 innerHTML。

// Before: under enforcement, the raw string throws a TypeError
<div dangerouslySetInnerHTML={{ __html: html }} />

在仅报告模式下,这行代码会产生一条违规报告;在强制模式下,它会直接抛出异常。

import { htmlPolicy } from './trusted-html';

export function RichText({ html }) {
  return <div dangerouslySetInnerHTML={{ __html: htmlPolicy.createHTML(html) }} />;
}

将所有 CMS、Markdown 和富文本输出都统一经由 RichText(或直接调用 htmlPolicy.createHTML())处理。之后如果用 grep 搜索 __html:,每一处匹配结果旁边都应当有策略调用。

安全地上线 Trusted Types

安全上线 Trusted Types 分为四个阶段:仅报告、修复所有被报告的接收点、将策略名称加入允许列表,最后开启强制模式。

  1. 部署 Content-Security-Policy-Report-Only: require-trusted-types-for 'script',并配置报告端点。
  2. 修复每个被报告的接收点:让其经由 htmlPolicy 处理,或替换为不需要受信任值的接收点,例如 textContent。
  3. 在 trusted-types 中列出你的代码及依赖所创建的每一个策略名称。
  4. 切换到强制模式的 Content-Security-Policy 响应头。

如果第三方代码仍在赋值字符串,而你暂时无法修复,可以使用名为 default 的策略作为临时过渡方案。在强制模式下,浏览器会把所有到达接收点的原始字符串交给该策略处理。MDN 建议仅在迁移遗留代码期间使用它。

// TEMPORARY: remove before you finish the migration.
import DOMPurify from 'dompurify';

if (globalThis.trustedTypes) {
  globalThis.trustedTypes.createPolicy('default', {
    createHTML(value) {
      console.warn('Untyped HTML reached a sink');
      return DOMPurify.sanitize(value, { TRUSTED_TYPES_POLICY: null });
    },
  });
}

特性检测可确保该模块在不支持该 API 的浏览器中以及服务端渲染期间不会抛出异常。

在该策略存在期间,需要将 default 加入 trusted-types。待其警告不再出现后,同时移除该策略和允许列表中的对应条目。

不支持 Trusted Types 的浏览器会怎样?

不支持 Trusted Types 的浏览器不会执行任何强制检查。在这些浏览器中,策略内部的净化器是不受信任的 HTML 与 DOM 之间唯一的屏障。MDN 将 window.trustedTypes 标记为 Baseline 2026,自 2026 年 2 月起新近可用,因此你的流量中较旧版本的浏览器并不支持它。

模块作用域中的回退方案正是为此而设。不受支持的浏览器会忽略该响应头,但每次调用时仍会运行 DOMPurify.sanitize()。正因如此,策略必须始终执行净化,绝不能原样返回输入。

总结

React 19.3 移除了过去会破坏 Trusted Types 的字符串强制转换,因此 dangerouslySetInnerHTML 现在可以承载由策略生成、并由浏览器强制校验的 HTML。先部署仅报告响应头,将每一处 __html 赋值都迁移到同一个基于 DOMPurify 的策略上,待报告不再出现后再开启强制模式。随后,可参考这些 API 安全最佳实践,在服务端贯彻同样严格的规范。

常见问题

如果 Trusted Types 的 default 策略返回 null 或 undefined,会发生什么?

浏览器会在接收点抛出 TypeError,赋值操作不会执行。返回 null 或 undefined 的 default 策略并不会放行原值,而是采取失败即关闭(fail closed)的方式,阻止写入,而不是让原始字符串通过。在迁移过程中,让 default 策略对所有输入都返回 null,也是查找残留字符串赋值的有效方法。

在 trusted-types 指令中使用通配符或 allow-duplicates 安全吗?

两者都不适合生产环境。将星号(*)作为策略名称会允许任意唯一的策略名称,这意味着注入的脚本可以注册自己的策略并创建受信任值。'allow-duplicates' 关键字允许代码创建多个同名策略,使得一个名称不再对应唯一的已知策略。正确的做法是逐一列出你的代码及依赖所创建的确切策略名称。

启用 Trusted Types 强制模式后,还能使用 eval() 吗?

可以。在 CSP 中添加 'trusted-types-eval' 关键字即可。它仅在支持并强制执行 Trusted Types 的浏览器中允许使用 eval() 及类似函数。与 'unsafe-eval' 不同,在不支持 Trusted Types 的浏览器中,这些函数仍会被阻止。在强制模式下,传给 eval() 的代码仍必须是 TrustedScript,或是由 default 策略转换为 TrustedScript 的原始字符串,否则调用会抛出异常。

DevTools for the frontend

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.

Star on GitHub12k

We use cookies to improve your experience. By using our site, you accept cookies.