Jest 在 Node.js v23 环境下处理 TLA 配置时的崩溃问题分析

问题背景

Jest 作为 JavaScript 生态中广泛使用的测试框架，在最新版本的 Node.js 环境中遇到了一个与顶层 await (Top-Level Await, TLA) 相关的兼容性问题。当项目中的 jest.config.js 配置文件或其依赖模块包含 TLA 语法时，在 Node.js v23 环境下运行会导致 Jest 崩溃。

技术细节

这个问题的核心在于 Node.js v23 对 ESM 模块系统的实现变更。具体表现为：

1. 错误信息：当尝试通过 require() 加载包含 TLA 的 ESM 模块时，Node.js 会抛出错误："require() cannot be used on an ESM graph with top-level await. Use import() instead."

2. 触发条件：问题会在以下情况出现：

   • 项目使用 jest.config.js 作为配置文件
   • 该配置文件或其依赖链中的任何模块包含 TLA 语法
   • 运行环境为 Node.js v22.12 或更高版本

3. 根本原因：Jest 内部的 requireOrImportModule 函数没有正确处理 Node.js 新增的 ERR_REQUIRE_ASYNC_MODULE 错误码，这个错误码专门用于标识模块包含 TLA 的情况。

影响范围

这个问题影响到了许多大型项目，包括著名的代码格式化工具 Prettier。在 Prettier 的测试套件中，由于配置文件间接依赖了包含 TLA 的 temp-dir 模块，导致测试无法正常运行。

解决方案

Jest 团队在 v30.0.0-alpha.7 版本中修复了这个问题。修复方案主要包括：

1. 更新 requireOrImportModule 实现，使其能够识别并正确处理 ERR_REQUIRE_ASYNC_MODULE 错误码
2. 改进模块加载逻辑，确保在遇到 TLA 模块时能够使用正确的加载方式

临时应对措施

对于暂时无法升级 Jest 版本的项目，可以采用以下临时解决方案：

1. 降级 Node.js 到 v22.11.0 或更早版本
2. 检查并修改 jest.config.js，移除或替换包含 TLA 的依赖
3. 将配置文件改为使用 .cjs 扩展名，明确指定为 CommonJS 模块

最佳实践建议

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

1. 在项目中使用明确的模块类型声明（.mjs 或 .cjs）
2. 谨慎在配置文件中使用 TLA 语法
3. 保持 Jest 和 Node.js 版本的同步更新
4. 在 CI/CD 流程中加入多版本 Node.js 的兼容性测试

总结

这个问题凸显了 JavaScript 生态系统中模块系统演进带来的兼容性挑战。随着 ESM 和 TLA 的普及，工具链需要不断适应这些新特性。Jest 团队的快速响应确保了测试框架能够继续在现代 JavaScript 环境中稳定运行。