DOMPurify v3.2.x 版本与 Angular 应用的兼容性问题解析

问题背景

近期 DOMPurify 项目升级到 3.2.x 版本后，部分 Angular 开发者在构建应用时遇到了类型检查错误。这些错误主要涉及 Trusted Types 相关的类型定义缺失，导致编译失败。本文将深入分析问题原因，并提供解决方案。

错误表现

开发者在构建 Angular 应用时遇到的主要错误包括：

1. Cannot find name 'TrustedTypePolicy'
2. Cannot find name 'TrustedHTML'
3. Property 'trustedTypes' does not exist on type 'Window & typeof globalThis'

这些错误表明 TypeScript 编译器无法识别与 Trusted Types API 相关的类型定义。

根本原因分析

DOMPurify 3.2.x 版本开始内置类型定义，不再需要单独安装 @types/dompurify。这一变更带来了以下影响：

1. 类型定义依赖关系：DOMPurify 的类型定义现在直接依赖于 @types/trusted-types 中的类型
2. TypeScript 配置问题：某些 Angular 项目的 TypeScript 配置可能没有正确处理全局类型定义
3. 模块解析差异：不同构建工具对类型定义的解析方式存在差异

解决方案

临时解决方案

对于急需解决问题的开发者，可以考虑以下临时方案：

1. 降级到 3.1.7 版本：这是最直接的解决方案
2. 启用 skipLibCheck：在 tsconfig.json 中添加 "skipLibCheck": true 可以跳过库的类型检查

长期解决方案

1. 确保正确安装依赖：

   npm install @types/trusted-types @types/node
   

2. 检查 TypeScript 配置：

   • 确保 tsconfig.json 中包含 "lib": ["dom"]
   • 确认 "typeRoots": ["node_modules/@types"] 配置正确

3. 等待官方修复：DOMPurify 团队已经在处理相关问题，后续版本将提供更完善的解决方案

技术细节

Trusted Types 是浏览器安全 API 的一部分，用于防止 DOM XSS 攻击。DOMPurify 3.2.x 版本加强了对 Trusted Types 的支持，这导致：

1. 类型定义现在直接引用 TrustedTypePolicy 和 TrustedHTML 等全局类型
2. 这些类型定义需要通过 @types/trusted-types 提供
3. 某些构建环境可能无法自动解析这些全局类型

最佳实践建议

1. 保持依赖更新：定期更新 @types/trusted-types 和 @types/node
2. 检查构建环境：确保构建环境支持 Trusted Types 相关特性
3. 关注官方更新：DOMPurify 团队正在积极解决这些问题，建议关注项目更新

总结

DOMPurify 3.2.x 版本的类型定义变更虽然带来了更完善的安全特性支持，但也导致了一些构建兼容性问题。通过理解问题本质并采取适当的解决方案，开发者可以顺利过渡到新版本。随着项目的持续改进，这些问题将得到更好的解决。