React19.3如何配CSP开启TrustedTypes防DOM型XSS？

一、核心机制：为什么 React 19.3 需要 Trusted Types？

在标准开发场景下，React 的虚拟 DOM 具有天然的 XSS 防御能力。当使用常规 JSX 插值如 <div>{userInput}</div> 时，React 底层会调用 document.createTextNode 生成安全的文本节点，自动对特殊字符进行实体编码，恶意脚本完全不会被浏览器 HTML 解析器执行。

然而，现代单页应用在实际业务中难免存在直接操作 HTML 或脚本注入的“汇聚点”（Sinks）：

• dangerouslySetInnerHTML 属性：业务渲染 CMS 富文本、Markdown 预览或服务端下发的 HTML 片段；
• 动态加载第三方 SDK：通过 document.createElement('script') 动态拼接 URL；
• 直接命令式 DOM 操作：通过 ref.current.innerHTML = data 或 element.outerHTML 绕开 React 虚拟 DOM 机制；
• 第三方依赖库隐患：图表库、富文本编辑器或旧版插件在内部悄悄向 DOM 注入拼接字符串。

在传统模式下，即使团队约定在输入前调用清洗库，一旦某位开发者疏忽、第三方库出现供应链漏洞、或者正则表达式被特异字符绕过，DOM 型 XSS 就会立即爆发。

Trusted Types（可信类型）彻底颠覆了这种脆弱的信任模型。当在内容安全策略（CSP）中开启该机制后，浏览器会直接封锁所有高危 DOM 汇聚点（包括 innerHTML、outerHTML、script.src、eval 等）。任何试图将纯原生字符串（string）赋值给汇聚点的操作，都会被浏览器内核直接拦截并抛出 TypeError。汇聚点只接收由预设策略签发的特权对象：TrustedHTML、TrustedScript 或 TrustedScriptURL。

图 1：传统 DOM XSS 防护与 Trusted Types 内核级拦截机制深度对比

如上图所示，Trusted Types 的本质是将“散落在各处的代码审查”收缩为一个全局受控的安全策略中心。所有需要注入 DOM 的数据必须由经过白名单认证的策略函数处理后签发类型，任何绕过策略的直接赋值都会在源头被掐断。

二、实施路线与 CSP 响应头完整配置

在 React 19.3 中落地 Trusted Types 包含四个严谨的工程阶段。我们先通过流程图直观了解整体实施路径：

图 2：React 19.3 开启 Trusted Types 的四步落地工程流程

1. CSP 关键指令解析

开启 Trusted Types 需要在服务端的 HTTP 响应头中下发 Content-Security-Policy。核心涉及两条指令：

• require-trusted-types-for 'script'：告诉浏览器，所有可执行脚本或解析 HTML 的 DOM 汇聚点，均强制要求可信类型，拒绝原生字符串赋值。
• trusted-types <policy-names> 'allow-duplicates'：定义允许由 JavaScript 调用的策略名称白名单。只有白名单中声明的策略名，才能成功调用 window.trustedTypes.createPolicy()。
• 'allow-duplicates' 关键字：在单页应用的热重载（HMR）、微前端子应用或重复加载模块的场景下，同一个策略名可能会被多次初始化。声明该指令可避免抛出“策略名称已存在”的致命异常。

2. 服务端配置实操示例

推荐在网关层（如 Nginx）或 SSR 服务端（如 Next.js、Express）中直接下发 HTTP 响应头。以下是常用部署环境的具体配置：

Nginx 反向代理配置：

# nginx.conf
server {
    listen 443 ssl http2;
    server_name example.com;

    # 声明 CSP 策略：要求可信类型，并放行 react-app、dompurify 策略与重复创建
    add_header Content-Security-Policy "require-trusted-types-for 'script'; trusted-types react-app dompurify default 'allow-duplicates'; object-src 'none'; base-uri 'self';" always;

    location / {
        root /usr/share/nginx/html;
        try_files $uri $uri/ /index.html;
    }
}

Next.js 14/15/16+ 或全栈环境（next.config.mjs）：

// next.config.mjs
const nextConfig = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'Content-Security-Policy',
            value: [
              "require-trusted-types-for 'script'",
              "trusted-types react-app dompurify default 'allow-duplicates'",
              "object-src 'none'",
              "base-uri 'self'"
            ].join('; ')
          }
        ]
      }
    ];
  }
};

export default nextConfig;

Node.js / Express 生产中间件配置：

import express from 'express';
import helmet from 'helmet';

const app = express();

app.use(
  helmet.contentSecurityPolicy({
    directives: {
      requireTrustedTypesFor: ["'script'"],
      trustedTypes: ['react-app', 'dompurify', 'default', "'allow-duplicates'"],
      objectSrc: ["'none'"],
      baseUri: ["'self'"]
    }
  })
);

三、策略中心构建与 DOMPurify 净化集成

配置了 CSP 响应头之后，任何未经过策略处理的字符串都无法直接插入 DOM。我们需要建立一个受控的策略单例模块，用于对富文本进行安全清洗并颁发 TrustedHTML。

1. 安装必要依赖与 Polyfill

由于 Safari 与当前部分旧版 Firefox 尚未全量默认开启原生 Trusted Types API，必须引入官方 Polyfill 确保跨端环境表现一致：

npm install dompurify @w3c/trusted-types
npm install --save-dev @types/dompurify @types/trusted-types

2. 编写安全策略模块：src/security/trustedTypes.ts

创建一个全局单例，包含降级检查、策略创建与 DOMPurify 严格模式清洗：

// src/security/trustedTypes.ts
import DOMPurify from 'dompurify';

// 针对未原生支持的环境按需引入 Polyfill
if (typeof window !== 'undefined' && !window.trustedTypes) {
  // 生产环境可由 entry 文件导入 'trusted-types' Polyfill
  require('trusted-types');
}

// 定义全局策略对象引用
let appPolicy: TrustedTypePolicy | null = null;

/**
 * 初始化并获取 React 应用统一的 Trusted Types 策略
 */
export function getAppTrustedPolicy(): TrustedTypePolicy {
  if (appPolicy) {
    return appPolicy;
  }

  if (typeof window !== 'undefined' && window.trustedTypes) {
    try {
      // 策略名称必须与 CSP header 中 trusted-types 白名单完全一致
      appPolicy = window.trustedTypes.createPolicy('react-app', {
        createHTML: (input: string): string => {
          // 使用 DOMPurify 进行深度清洗，剔除 script、onerror、javascript: 伪协议等
          return DOMPurify.sanitize(input, {
            ADD_ATTR: ['target'],
            FORBID_TAGS: ['style', 'iframe', 'object', 'embed'],
            FORBID_ATTR: ['onerror', 'onload', 'onclick']
          });
        },
        createScriptURL: (url: string): string => {
          // 仅允许白名单域名下的脚本或同源静态资源
          const parsed = new URL(url, window.location.origin);
          if (parsed.origin === window.location.origin || parsed.hostname.endsWith('.trusted-cdn.com')) {
            return url;
          }
          throw new Error(`[Security] 阻止加载非受信第三方脚本 URL: ${url}`);
        },
        createScript: (scriptContent: string): string => {
          // 原则上禁止动态拼装可执行脚本字符串
          throw new Error('[Security] 严禁在客户端动态构建非受信脚本');
        }
      });
    } catch (err) {
      console.warn('[Security] 创建策略重名或被 CSP 拦截，回退到已有策略或安全透传:', err);
    }
  }

  // 在 SSR 环境或兜底降级处理
  if (!appPolicy) {
    return {
      name: 'fallback',
      createHTML: (s: string) => DOMPurify.sanitize(s),
      createScriptURL: (s: string) => s,
      createScript: (s: string) => s
    } as unknown as TrustedTypePolicy;
  }

  return appPolicy;
}

/**
 * 工具函数：将不可信字符串转换为经过净化的 TrustedHTML 或安全降级字符串
 */
export function sanitizeToTrustedHtml(rawHtml: string): TrustedHTML | string {
  const policy = getAppTrustedPolicy();
  return policy.createHTML(rawHtml);
}

四、React 19.3 运行态与组件工程化落地

在 React 19.3 内部，dangerouslySetInnerHTML 已经针对 Trusted Types 做了深度适配：它的 __html 属性既可以接收原生字符串，也能无缝接收标准 TrustedHTML 对象。

图 3：React 19.3 渲染引擎与 Trusted Types 运行时的底层交互与拦截逻辑

如上图所示，当应用开启了 require-trusted-types-for 'script' 后，如果直接向 dangerouslySetInnerHTML 传递未经验证的裸字符串（路径 B），浏览器会在挂载真实 DOM 节点时立刻阻断并抛出异常。正确的工程解法是统一走路径 C，将数据在组件层封装为受控类型。

1. 封装通用安全富文本组件：<SafeHtml />

为了避免各业务团队开发者直接书写 dangerouslySetInnerHTML，应在基础组件库中提供统一收口的展示组件：

// src/components/SafeHtml.tsx
import React, { useMemo } from 'react';
import { sanitizeToTrustedHtml } from '../security/trustedTypes';

interface SafeHtmlProps {
  content: string;
  className?: string;
  tag?: keyof JSX.IntrinsicElements;
}

/**
 * 生产级安全 HTML 渲染组件，严格兼容 React 19.3 与 CSP Trusted Types 策略
 */
export const SafeHtml: React.FC<SafeHtmlProps> = ({
  content,
  className = '',
  tag: Tag = 'div'
}) => {
  // 缓存净化与类型构造结果，避免无关渲染引起重复执行
  const trustedValue = useMemo(() => {
    if (!content) return '';
    return sanitizeToTrustedHtml(content);
  }, [content]);

  // React 19.3 原生支持将 TrustedHTML 直接传入 __html
  return (
    <Tag
      className={className}
      dangerouslySetInnerHTML={{ __html: trustedValue as unknown as string }}
    />
  );
};

2. 业务页面使用对比

五、平滑过渡：从 Report-Only 灰度到 Enforce 强制阻断

在已经有一定规模的成熟项目中，直接在生产开启 Content-Security-Policy 强制阻断往往会导致未预料到的界面白屏，因为引入的某个第三方埋点、统计或客服 SDK 可能在内部偷偷调用了 innerHTML。

平滑落地的最佳实践是采用“观察、修复、全量”三步走策略：

1. 第一阶段：开启仅报告模式（Report-Only）

首先通过 Content-Security-Policy-Report-Only 收集所有潜在的违规点，而不真正中断用户页面的功能渲染：

# Nginx 灰度环境配置示例
add_header Content-Security-Policy-Report-Only "require-trusted-types-for 'script'; trusted-types react-app dompurify default 'allow-duplicates'; report-uri /api/csp-report-sink;" always;

2. 分析违规日志 Payload

当浏览器检测到不合规的裸字符串注入时，会向 report-uri 异步发送 JSON 报告：

{
  "csp-report": {
    "document-uri": "https://example.com/editor",
    "violated-directive": "require-trusted-types-for 'script'",
    "effective-directive": "require-trusted-types-for",
    "original-policy": "require-trusted-types-for 'script'; ...",
    "disposition": "report",
    "blocked-uri": "trusted-types-sink",
    "sample": "Element.innerHTML",
    "line-number": 142,
    "source-file": "https://example.com/assets/legacy-analytics.js"
  }
}

通过报告中的 source-file 与 sample，运维和安全工程师可以迅速定位是哪个遗留组件或第三方 SDK 存在裸赋值问题，并在代码仓库中提前修复。

3. 审慎配置 default 策略作为托底防线

Trusted Types 规范允许定义一个特殊的策略名为 default。当有未经包装的纯字符串流入汇聚点时，如果声明了 default 策略，浏览器会自动调用该策略的清洗回调，而不会直接崩溃报错。

// 仅供过渡阶段兜底的 default 策略
if (typeof window !== 'undefined' && window.trustedTypes) {
  try {
    window.trustedTypes.createPolicy('default', {
      createHTML: (untrustedInput: string) => {
        console.warn('[Security Warn] 触发兜底 default 策略，存在未规范化的代码调用:', untrustedInput);
        return DOMPurify.sanitize(untrustedInput);
      }
    });
  } catch (e) {
    // 忽略重复创建
  }
}

六、常见报错排查与避坑指南

在联调与集成过程中，开发者常遇到以下典型异常，可按照下表迅速定位和排除：

七、生产落地核查清单与全景总结

在正式切换生产前，请逐项核对以下四项安全支柱，确保防御闭环无死角：

图 4：React 19.3 + Trusted Types 生产安全防护矩阵与最佳实践