ts-jest 项目中的 TypeScript 5.6+ 模块解析问题解析

问题背景

在 TypeScript 5.6 版本发布后，使用 ts-jest 进行测试的开发者遇到了一个关于 ES6 模块解析的兼容性问题。当项目中引用了以 ES6 模块形式发布的第三方库（如 OpenLayers）时，TypeScript 5.6+ 会识别这些库的 type: module 声明，导致生成的代码保持 ES6 模块语法，而 Jest 默认无法直接解析这种语法。

问题表现

开发者通常会配置 ts-jest 来转换 TypeScript 和 ES6 模块：

transform: {
    '\\.[tj]sx?$': [
        'ts-jest',
        {
            tsconfig: {
                outDir: './.ts-jest'
            }
        }
    ],
},
transformIgnorePatterns: [
    '/node_modules/(?!(ol|txml|geotiff|quick-lru|color-|rbush|earcut|pbf|quickselect))'
],

在 TypeScript 5.6 之前，这种配置可以正常工作。但从 5.6 版本开始，TypeScript 会识别第三方库的模块类型声明，导致生成的代码保留 ES6 模块语法（如 import/export），而 Jest 默认期望的是 CommonJS 格式的代码。

技术原因

TypeScript 5.6 引入了一个重要变化：它会根据 package.json 中的 type 字段和文件扩展名（如 .mjs）更准确地判断模块系统类型。这一改进虽然提高了准确性，但也带来了与 Jest 默认配置的兼容性问题，因为：

1. Jest 默认使用 Node.js 的 CommonJS 模块系统
2. TypeScript 5.6+ 会保留第三方库的 ES 模块语法
3. 即使配置了 transformIgnorePatterns 来转换特定 node_modules，生成的代码仍可能是 ES 模块格式

解决方案

方案一：启用 isolatedModules

最简单的解决方案是在 ts-jest 配置中启用 isolatedModules：

transform: {
    '\\.[tj]sx?$': [
        'ts-jest',
        {
            isolatedModules: true
        }
    ],
}

这个选项会告诉 TypeScript 以隔离模式编译每个文件，不进行完整的类型检查，但会确保输出为 Jest 可识别的格式。

方案二：通过 Babel 转换模块

对于更复杂的情况（特别是涉及 .mjs 文件时），可以配置 Babel 来将 ES 模块转换为 CommonJS：

const presetConfig = createJsWithTsPreset({
  babelConfig: {
    plugins: [['@babel/plugin-transform-modules-commonjs']],
  },
});

这种方法提供了更大的灵活性，可以处理各种模块格式的转换。

方案三：调整模块解析策略

对于 Angular 项目或使用类似工具链的项目，可以参考 jest-preset-angular 中的配置示例，专门处理 .mjs 文件的转换。

最佳实践建议

1. 优先尝试 isolatedModules：这是最简单的解决方案，适用于大多数场景
2. 复杂场景考虑 Babel：当遇到特殊文件扩展名或复杂模块结构时，Babel 转换更可靠
3. 保持工具链更新：定期检查 ts-jest 和 TypeScript 的更新，了解新的配置选项
4. 测试环境隔离：考虑为测试环境使用单独的 tsconfig，避免影响生产构建

总结

TypeScript 5.6+ 对模块系统的更严格处理虽然提高了准确性，但也带来了与测试工具链的兼容性挑战。通过理解这些变化背后的原理，开发者可以灵活选择最适合自己项目的解决方案，确保测试流程的顺畅运行。