MSWJS 项目中关于 Headers 只读属性的 TypeError 问题解析

问题背景

在 MSWJS 项目的使用过程中，部分开发者遇到了一个关于 Headers 只读属性的 TypeError 错误。这个错误通常发生在 Node.js 环境下运行测试时，特别是在调用 server.listen() 方法时触发。错误信息明确指出无法对对象的只读属性 'Headers' 进行赋值操作。

错误表现

开发者报告的错误堆栈显示问题出现在 interceptors 模块的 recordRawHeaders.ts 文件中。具体表现为当尝试修改 Headers 对象时，系统抛出 TypeError，指出目标属性是只读的，无法进行赋值操作。

技术分析

深入分析问题根源，我们发现这与 MSWJS 的拦截器机制有关。拦截器在处理 HTTP 请求时需要记录原始头信息，这一过程涉及对全局 Headers 对象的修改。问题主要出现在两个关键操作上：

1. 对 headers 对象定义 kRawHeaders 属性
2. 对 Headers 类本身定义 kRestorePatches 属性

在 Node.js v18 和 v20 环境中测试通过，但在某些特定环境下（如使用了 JSDOM 或其他 polyfill 的环境）会出现问题。这是因为这些环境可能对 Request 和 Headers 等对象实施了更严格的保护措施。

解决方案

项目维护团队迅速定位并修复了这个问题。修复方案主要涉及：

1. 修改了全局 Headers 对象的重新赋值方式
2. 调整了拦截器恢复原始补丁的逻辑

修复后的版本 v2.4.7 已经发布，建议所有用户升级到最新版本以获得修复。

环境兼容性说明

值得注意的是，这个问题在某些特定环境下可能仍然存在，特别是：

1. 使用 JSDOM 作为测试环境
2. 手动添加了 Request/Headers 等 polyfill
3. 某些 Node.js 版本的特殊配置

对于使用 JSDOM 的开发者，团队建议考虑迁移到 happy-dom 等替代方案，因为这些环境对现代 Web API 的实现更加完善和稳定。

最佳实践建议

为了避免类似问题，建议开发者：

1. 保持 MSWJS 和相关依赖项的最新版本
2. 在 Node.js 官方支持的版本上运行测试
3. 谨慎使用 polyfill，确保其实现与原生 API 行为一致
4. 考虑使用推荐的环境替代方案（如 happy-dom 替代 jsdom）

通过理解问题的根源和解决方案，开发者可以更好地在项目中集成和使用 MSWJS，避免遇到类似的兼容性问题。