Trusted Types 重构 DOM 操作安全指南

Trusted Types 并非简单的安全补丁，而是一套从 HTTP 响应头（CSP）强制启始、贯穿策略定义与 DOM 调用全链路的深度防御机制——必须在服务端配置 `require-trusted-types-for 'script'` 且策略名严格匹配，所有高危 DOM 操作（如 `innerHTML`、`insertAdjacentHTML`）只能接收 `TrustedHTML` 等可信类型实例，彻底禁用 `eval` 和 `document.write`；第三方库需显式兼容或代理封装，策略设计严禁“万能通配”和运行时判断，必须基于静态、语义明确的净化规则（如 UGC 白名单、模板隔离），否则不仅无效，还会导致白屏崩溃——真正落地 Trusted Types，本质是重构前端信任模型，而非给旧代码套一层外壳。

Trusted Types 不是加个策略就能生效的补丁，它是一套必须从 CSP 响应头开始、贯穿策略定义与 DOM 调用链的强制校验机制。没配对的 HTTP 头，JS 里写一百个 createPolicy 都等于零。

Content-Security-Policy 响应头必须提前部署

浏览器只在收到含 require-trusted-types-for 'script' 的 CSP 响应头后，才会拦截非法 DOM 赋值。本地开发时用 meta 标签或 JS 注入 CSP 完全无效。

• 生产环境必需头：Content-Security-Policy: require-trusted-types-for 'script'; trusted-types default
• default 是硬性策略名——如果代码里调用 trustedTypes.createPolicy("my-policy", {})，但 CSP 写的是 trusted-types default，会直接抛 TypeError: Policy name mismatch
• 策略名不匹配时不会降级，而是整个页面高危 API（如 innerHTML）调用失败，表现为白屏或功能中断

所有高危 DOM 操作必须只接收 TrustedHTML/TrustedScriptURL 实例

重构不是“包装一下字符串”，而是切断原始字符串流向 DOM 的路径。以下操作一旦接收到非可信类型，浏览器立即报错：

• element.innerHTML = rawString → 必须改为 element.innerHTML = policy.createHTML(rawString)
• element.insertAdjacentHTML('beforeend', rawString) → 同样需经 policy.createHTML() 包装
• document.write(rawString) 和 eval() 类操作，在启用 Trusted Types 后已彻底禁用，不可绕过
• 模板引擎（如 Handlebars）输出不能直接赋值，必须显式调用策略封装：例如 policy.createHTML(template(data))

第三方库集成必须验证其 Trusted Types 兼容性

未适配的库会直接崩在 innerHTML 调用上；部分主流库已有支持，但行为不一致：

• jQuery 3.5+ 支持自动识别 TrustedHTML：传入 $('
  ').html(policy.createHTML(html)) 可正常工作
• React 和 Vue 在 SSR 或 DOM 更新路径中不直接暴露 innerHTML，但自定义指令或 v-html 仍需手动封装，v-html 不接受 TrustedHTML，必须用 render 函数或 dangerouslySetInnerHTML + 策略代理
• 未适配库（如旧版 Bootstrap JS 插件）需包裹一层代理：重写其内部 DOM 写入方法，强制走策略创建流程

避免“万能策略”——策略粒度决定审计有效性

用一个 createPolicy('default', { createHTML: s => s }) 就等于没做任何事。现代审计要求策略能体现语义边界：

• 用户生成内容（UGC）策略应仅允许白名单标签：

  ，禁止