ts-jest 故障排查完全指南:模块解析、node_modules 转换与性能卡顿三大问题实战解法
ts-jest 故障排查完全指南:模块解析、node_modules 转换与性能卡顿三大问题实战解法
ts-jest 是 Jest 生态中带源码映射(source map)支持的 TypeScript 转换器,用于让 Jest 直接测试 TypeScript 项目。但在实际开发与 CI 流水线中,开发者经常遇到"找不到模块""node_modules 中 ESM 语法报错""测试卡住不动"三类问题。本文基于 ts-jest 官方 Troubleshooting 指南(website/docs/guides/troubleshooting.md),逐条还原问题现象、给出可直接复制运行的 Jest 配置,并结合仓库源码说明每个配置项背后的底层机制,帮助你读完即可上手排障。
说明:如果你的问题与 Jest 本身(而非 ts-jest 转换层)相关,建议同时查阅 Jest 官方的 troubleshooting 指南;本文聚焦于 ts-jest 与 TypeScript/Jest 协作时产生的典型故障。
一、在 CI 工具上运行 ts-jest:Cannot find module "" from ""
问题现象
在本地开发环境测试一切正常,但提交代码后 CI 上运行 Jest 却报出:
Cannot find module "" from ""
错误信息中模块路径和来源文件路径均为空或异常,说明 Jest 在 CI 环境中的模块解析(module resolution)基准点与本地不一致,常见于以下四类原因。
方案 1:确认 rootDir 与 roots 配置正确
Jest 的模块解析依赖 rootDir(配置文件中相对路径的解析基准)。若项目结构或 CI 检出方式导致目录层级变化,需显式声明 roots,让 Jest 从 <rootDir> 开始查找测试与源码:
import type { Config } from 'jest'
const config: Config = {
//...
roots: ['<rootDir>'],
}
export default config
<rootDir> 是 Jest 内置变量,指向包含 Jest 配置文件的目录。将 roots 收窄到项目根目录,可避免 CI 环境因工作目录(working directory)不同导致模块搜索范围错位。
方案 2:声明 moduleDirectories 与 modulePaths
如果项目依赖放在非默认位置(例如 monorepo 中的 packages/*、自建 lib/ 目录),Jest 默认只扫描 node_modules,需要通过 moduleDirectories 显式加入自定义模块目录,用 modulePaths 指定模块的绝对搜索路径:
import type { Config } from 'jest'
const config: Config = {
//...
moduleDirectories: ['node_modules', '<module-directory>'],
modulePaths: ['<path-of-module>'],
}
export default config
其中 <module-directory> 替换为相对 <rootDir> 的模块目录(如 packages),<path-of-module> 替换为模块所在的绝对路径或基于 <rootDir> 的路径。这与 Jest 原生配置语义一致,ts-jest 不会改写这两项,配置后直接生效。
方案 3:使用 moduleNameMapper 建立别名映射
当源码以路径别名(path alias)或裸导入(bare import)方式引用模块,且 Jest 无法按 Node 默认规则解析时,可用 moduleNameMapper 将导入路径映射到真实物理路径:
import type { Config } from 'jest'
const config: Config = {
//...
moduleNameMapper: {
'<import-path>': '<rootDir>/<real-physical-path>',
},
}
export default config
例如 '^@shared/(.*)$': '<rootDir>/packages/shared/$1'。若你的项目依赖 TypeScript 的 paths 配置,还可以结合 ts-jest 的 pathsToModuleNameMapper 工具自动生成映射,相关实现可参考 src/config/paths-to-module-name-mapper.ts 及其测试 src/config/paths-to-module-name-mapper.spec.ts。
方案 4:检查 Git 仓库目录名大小写
一个经常被忽视的 CI 专属问题:GitHub 仓库中的文件夹名可能与本地重命名后的文件夹名不一致(GitHub 偶尔不会及时同步本地的大小写重命名)。若本地把 SomeDir 重命名为 somedir 但 GitHub 仍显示旧名,CI 上克隆下来的目录结构就与本地不一致,导致 Cannot find module。
解决方案:
- 在 GitHub 网页端手动重命名文件夹并提交;
- 或使用 Git 命令完成重命名并提交:
git mv <source> <destination>
git mv 会保留文件历史并正确记录大小写变更,随后 git commit 即可同步到远端。这是纯仓库操作层面的修复,与 ts-jest 配置无关,但却是 CI 排障中最高频的隐藏原因之一。
二、显式转换 node_modules 中的(Node)模块:SyntaxError: Cannot use import statement outside a module
问题现象
当某个 node_modules 中的依赖发布的是 ESM 语法(含 import/export),而 Jest 执行环境按 CommonJS 解释时,会抛出:
SyntaxError: Cannot use import statement outside a module
> 22 | import Component from "../../node_modules/some-module/lib";
| ^
错误信息通常会明确指出是哪个模块的哪一行,例如上面的 some-module/lib。根因是该 node 模块的语法不符合 Jest 执行步骤的要求,需要先经过转换(transform)。而 Jest 默认通过 transformIgnorePatterns 跳过 node_modules,因此需要显式把"肇事模块"纳入转换范围。
场景 A:违规文件是 .mjs 文件
当问题出在单个文件的扩展名(.mjs)而非包级配置时,不需要逐个列出包名,只需为 node_modules 中的 .mjs 文件添加一条专用 transform 规则,ts-jest 会自动把所有 .mjs 文件转译为 CommonJS:
import type { Config } from 'jest'
import { createDefaultPreset } from 'ts-jest'
const presetConfig = createDefaultPreset()
const config: Config = {
...presetConfig,
transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)'],
transform: {
...presetConfig.transform,
'^.+/node_modules/.+\\.mjs$': ['ts-jest', {}],
},
}
export default config
这段配置的关键点:
transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$)']使用负向前瞻,只有.mjs文件不命中忽略规则,其余 node_modules 文件继续被跳过;- 新增的
'^.+/node_modules/.+\\.mjs$': ['ts-jest', {}]让 ts-jest 处理 node_modules 下的.mjs文件; - 通过
createDefaultPreset()展开默认 preset,而不是手写 transform 正则,是当前 ts-jest 推荐的做法。
createDefaultPreset 的实现见 src/presets/create-jest-preset.ts:它返回 { transform: { '^.+\\.tsx?$': <a href="https://link.gitcode.com/i/ab4fdabeb1847516c9a003d6defa8c14" target="_blank">'ts-jest', options] } },其中 '^.+\\.tsx?$' 即 [src/constants.ts 中定义的 TS_TRANSFORM_PATTERN。展开 preset 可保证 .ts/.tsx 的默认转换规则不被遗漏。
场景 B:违规包在其 package.json 中声明了 "type": "module"
当某个包通过 "type": "module" 声明自身为 ESM,导致其 .js 文件被 Node 按 ESM 解释时,需要在 transformIgnorePatterns 中逐个点名受影响的包:
import type { Config } from 'jest'
const config: Config = {
//...
transformIgnorePatterns: ['node_modules/(?!(some-module|another-module))'],
}
export default config
some-module 和 another-module 将被 ts-jest 转换,其余 node_modules 依赖保持原样。
两种场景的选择依据:
| 违规形态 | 特征 | 配置策略 |
|---|---|---|
.mjs 扩展名文件 |
文件本身带 .mjs 后缀 |
按扩展名添加 transform 规则,无需列出包名 |
"type": "module" 包 |
包的 package.json 声明了 ESM |
在 transformIgnorePatterns 中显式列出包名 |
值得注意的是,ts-jest 对"哪些扩展名参与转换"有一套完整的常量体系,见 src/constants.ts:
export const TS_TRANSFORM_PATTERN = '^.+\\.tsx?$'
export const ESM_TS_TRANSFORM_PATTERN = '^.+\\.m?tsx?$'
export const TS_JS_TRANSFORM_PATTERN = '^.+\\.[tj]sx?$'
export const ESM_TS_JS_TRANSFORM_PATTERN = '^.+\\.m?[tj]sx?$'
export const JS_TRANSFORM_PATTERN = '^.+\\.jsx?$'
这些模式分别被 createDefaultPreset、createJsWithTsPreset、createJsWithBabelPreset 等工厂函数使用(见 src/presets/create-jest-preset.ts),也解释了为什么预设的 transform 正则形如 ^.+\\.<a href="https://link.gitcode.com/i/8adf7736149268351be958b01170dd78" target="_blank">tj]sx?$。如果你使用的是 legacy preset 的写法(preset: 'ts-jest/presets/js-with-babel' 等),可在 [presets/default/jest-preset.js 中看到其最终形态:module.exports = require('..').defaults。
三、导入依赖时测试卡住:Jest 处理文件极慢甚至像死锁
问题现象
在禁用缓存(如 jest --no-cache)的情况下,Jest 处理文件耗时极长,看起来像是卡死。仓库内性能相关的 e2e 用例位于 e2e/performance/tests/perf.spec.ts,正是用于守护这类性能回归。
根本原因
ts-jest 内部使用 TypeScript 编译器 API 把 ts/js 文件转换为 js 文件(转换核心是 src/transpilers/typescript/transpile-module.ts 中的 tsTranspileModule,它基于 ts.createProgram + program.emit 实现)。这意味着被转换的文件越多、参与类型检查的文件越多,耗时越长。因此第一原则是:只转换需要转换的内容。
最常见的原因是你让 ts-jest 同时处理了 JavaScript 文件(而不仅是 TypeScript 文件),导致加载的文件数量激增,某些情况下甚至会耗尽机器资源("blow up the machine")。
修复步骤 1:检查 tsconfig 中的 allowJs
在 tsconfig.json 中确认 compilerOptions.allowJs 未开启(或显式设为 false):
{
"compilerOptions": {
"allowJs": false
}
}
allowJs: true 会允许 TypeScript 编译器加载 .js 文件,配合 Jest 的 transform 规则,可能把大量 JS 文件拖入转换与类型检查范围。ts-jest 的 createJestPreset 工厂函数也专门以 allowJs 参数决定是否把 js 文件纳入转换正则,见 src/presets/create-jest-preset.ts:
[allowJs ? (supportESM ? '^.+\\.m?[tj]sx?$' : '^.+\\.[tj]sx?$') : '^.+\\.tsx?$']
即:allowJs 为 false 时,ts-jest 的默认 transform 只覆盖 ^.+\\.tsx?$,不处理 .js 文件。
修复步骤 2:收窄 jest 配置中的 transform 正则
检查 jest 配置的 transform 属性,确保 ts-jest 只匹配 .ts 文件。如果当前是同时匹配 ts/js 的写法,改为只匹配 ts:
module.exports = {
...
'transform': {
- '^.+\\.(t|j)s$': ['ts-jest', {}],
+ '^.+\\.ts$': 'ts-jest',
},
};
如果确实需要处理 .js 文件(例如项目混合 ts/js),应显式选择 createJsWithTsPreset(对应 ^.+\\.[tj]sx?$)等预设,而不是让默认预设无意中吞掉所有 JS 文件。
修复步骤 3(可选):开启 isolatedModules 使用转译模式
在 tsconfig 中启用 isolatedModules: true,可以让 ts-jest 走单文件转译(transpilation)模式,行为类似 Babel / SWC / Esbuild 等纯转译器:
{
"compilerOptions": {
"isolatedModules": true
}
}
从源码看,src/legacy/config/config-set.ts 会在 transformer 选项传入 isolatedModules 时把它合并进解析后的 tsconfig(this.parsedTsConfig.options.isolatedModules = true),而 src/legacy/compiler/ts-compiler.ts 则在 isolatedModules 为 true 时走 tsTranspileModule 快速路径,跳过完整程序的类型检查。
代价与收益需要权衡:
- 收益:禁用完整类型检查,测试运行显著提速,特别适合
jest --no-cache场景; - 代价:失去类型检查能力,且部分依赖跨文件信息的特性(如
const enum)将不可用。
仓库配套文档 website/docs/getting-started/options/isolatedModules.md 进一步补充了性能建议:使用完整类型检查模式时,通过收窄 tsconfig 的 include 减少参与检查的文件量可以明显提速,例如:
{
// ...other configs
"include": ["my-typings/*", "my-global-modules/*"]
}
但要注意权衡:include 收得太窄可能导致 ts-jest 无法识别某些本应参与测试的文件(自定义类型声明、全局模块等),建议用 glob 精确覆盖测试环境所需文件,兼顾性能与正确性。ts-jest 单文件转译的底层细节可继续阅读 src/transpilers/typescript/transpile-module.ts 与测试 src/transpilers/typescript/transpile-module.spec.ts。
四、总结:三大问题的排查路径速查表
| 问题 | 根因方向 | 首选配置修复 |
|---|---|---|
Cannot find module "" from ""(CI) |
模块解析基准点错位 / 别名未映射 / Git 目录名大小写不一致 | 配置 roots、moduleDirectories/modulePaths、moduleNameMapper;用 git mv 修正目录名 |
Cannot use import statement outside a module(node_modules) |
node 模块含 ESM 语法且被 transformIgnorePatterns 跳过 |
.mjs 文件:添加专用 transform 规则;"type": "module" 包:在 transformIgnorePatterns 中列出包名 |
| 导入依赖时测试卡住 / 极慢 | 转换与类型检查范围过大 | allowJs: false;transform 正则收窄到 .ts;按需开启 isolatedModules |
排查时请记住 ts-jest 的核心工作原理:ts-jest 通过 TypeScript 编译器 API 完成转换,转换与类型检查的覆盖面直接决定性能,因此"只转换需要的内容"既是性能原则,也是避免 ESM/CommonJS 语法冲突的出发点。更多预设与配置选项可参考 website/docs/getting-started/presets.md 与 website/docs/getting-started/options.md,完整的转换流程说明见 website/docs/processing.md。