ts-jest项目中ES Module与CommonJS模块混用的兼容性问题分析

问题背景

在Node.js生态系统中，ES Module(ESM)和CommonJS(CJS)两种模块系统的共存给开发者带来了不少挑战。特别是在测试环节，当使用ts-jest进行TypeScript代码测试时，模块系统的兼容性问题尤为突出。本文将以一个典型场景为例，深入分析ts-jest 29.2.4版本中出现的模块兼容性问题及其解决方案。

问题现象

在ts-jest 29.2.4版本中，当测试代码尝试通过动态import()导入ES Module时，会抛出错误"Must use import to load ES Module"。这个问题在29.2.3及更早版本中并不存在，表明这是29.2.4版本引入的回归问题。

技术分析

模块系统处理机制

ts-jest在处理TypeScript代码时，会根据配置决定如何编译模块语法。关键点在于：

1. 模块解析策略：ts-jest内部会强制设置moduleResolution为Node10风格
2. 模块转换逻辑：根据useESM配置和Jest运行时环境决定是否保留ESM语法
3. 类型系统兼容：TypeScript的模块类型检查与实际运行时行为可能存在差异

版本变更影响

29.2.4版本回退了对Node16/NodeNext模块解析策略的支持，这是导致问题的根本原因。回退后：

1. 无论tsconfig.json中如何配置module字段，都会被强制覆盖
2. 动态import()会被转换为require()调用
3. ESM模块无法被正确加载

解决方案

临时解决方案

对于必须使用29.2.4版本的项目，可以采用以下变通方案：

1. 分离导入逻辑：将动态import()调用封装到单独的CommonJS模块中
2. 类型声明适配：为封装函数提供类型声明，保持类型检查通过
3. 忽略类型错误：使用@ts-ignore绕过类型系统对模块类型的严格检查

示例实现：

// import-wrapper.js (CommonJS)
Object.defineProperty(exports, '__esModule', { value: true });

exports.default = function wrappedImport(packageName) {
    return import(packageName);
};

// import-wrapper.d.ts (类型声明)
export default function wrappedImport<T>(packageName: string): Promise<T>;

推荐方案

等待ts-jest后续版本恢复对Node16/NodeNext的支持，届时：

1. 将新增useModernModuleFormat配置选项
2. 可以保留tsconfig.json中的原始module配置
3. 实现更自然的ESM/CJS互操作

最佳实践建议

1. 明确模块边界：在混合模块项目中，清晰划分ESM和CJS的边界
2. 统一测试环境：确保测试配置与实际运行环境一致
3. 关注版本更新：及时跟进ts-jest的版本变更说明
4. 备选方案设计：为关键模块交互准备备用实现方案

总结

模块系统兼容性是Node.js生态中的长期挑战。通过理解ts-jest的内部处理机制和版本差异，开发者可以更好地应对测试中的模块交互问题。当前建议采用封装导入逻辑的临时方案，并期待ts-jest未来版本提供更完善的解决方案。