ts-jest 处理流程深度解析:从 Jest Transformer 到 TypeScript 编译管线的完整链路
ts-jest 处理流程深度解析:从 Jest Transformer 到 TypeScript 编译管线的完整链路
ts-jest 的核心价值在于它作为 Jest 的 transformer,把 TypeScript 源码实时编译为可在 Node 环境直接运行的 JavaScript,并配套 source map、诊断检查与多层缓存。本文基于 ts-jest 仓库中 v29.4 版本的 Processing flow 文档,结合仓库源码逐步拆解 require() 一个文件时 Jest 与 ts-jest 两级流水线各自的决策分支,帮助读者完整掌握 getCacheKey、process、语言服务编译、隔离模块编译、AST transformer、Babel 接力与 afterProcess 钩子的真实调用顺序与底层实现。
两级流水线总览:Jest 进程与 ts-jest 进程
ts-jest 对每个待处理文件的流转可以分为两个层次:
- Jest 进程(Jest process):这是 Jest 运行时代理器的通用流程,发生在
ts-jest介入之前与之后。它决定某个文件是否需要 transform、是否需要读取缓存、最终如何被require()加载。 - ts-jest 进程(
ts-jestprocess):这是TsJestTransformer内部的专用流程,负责把 TypeScript 源码真正编译成 JavaScript,并完成字符串化、.d.ts处理、source map 修复、Babel 接力等一系列细分步骤。
两者以 ts-jest 实现的 Jest transformer 接口为交界。该接口在 src/index.ts 中暴露:createTransformer(tsJestConfig?) 返回 TsJestTransformer 实例,而核心类定义在 src/legacy/ts-jest-transformer.ts 中,实现了 Jest 的 SyncTransformer 接口的 process / getCacheKey 方法及其异步变体。
Jest 进程:require() 一个文件的完整决策链
原文档用一张 PlantUML 图概括了 Jest 层面的流程,其逻辑可归纳为如下决策链:
require('file'):测试或被测代码触发模块加载。- 是否存在对应的 transform? 即 Jest 配置中
transform字段的正则是否命中该文件(例如^.+\\.tsx?$命中.ts/.tsx文件)。若没有匹配的 transform,Jest 直接以原始内容require();若有,进入下一步。 - transformer 是否实现了
getCacheKey? 若实现,调用transformer.getCacheKey(...)生成缓存键;否则使用 Jest 内置的缓存键逻辑。 - 结果是否已在缓存中? 命中缓存则直接使用缓存内容;未命中则调用
transformer.process(...)执行编译并把结果写入缓存。 require():Jest 用最终得到的代码完成模块加载。
这一流程在 src/legacy/ts-jest-transformer.ts 的 getCacheKey 实现中有清晰的代码对应。它把以下元素按 \x00 分隔符拼接后做 SHA-1 哈希,生成缓存键:
this._transformCfgStr:序列化后的 Jest 配置与 ts-jest 的cacheSuffix组合,其中cacheSuffix由 TypeScript 版本、ts-jest 自身 digest、babel 配置、tsconfig 解析结果、isolatedModules、诊断配置以及所有 transformer 的name-version列表哈希而成(见 src/legacy/config/config-set.ts)。这意味着任何影响输出的配置变化都会自动使缓存失效。configs.rootDirinstrument:on|off:ts-jest 始终以instrument: false处理,避免重复插桩,注释明确"we do not instrument, ensure it is false all the time"。supportsStaticESM:on|off:反映当前是否处于静态 ESM 模式。- 文件内容与文件路径本身。
更关键的是:当未开启 isolatedModules 且存在 ts-jest 磁盘缓存目录时,getCacheKey 会把该文件依赖的全部解析模块(含嵌套依赖)及其 mtimeMs 一并纳入哈希。resolvedModuleNames 来自 this._compiler.getResolvedModules(...),其实现(src/legacy/compiler/ts-compiler.ts)通过 preProcessFile 收集直接 import,再对每个直接依赖递归收集嵌套 import,最终得到完整的依赖图。只要任何一个被依赖文件的修改时间变化,缓存键即改变,这正是 ts-jest 在 watch 模式下不会输出过期结果的保障。该依赖图同时被缓存在 _depGraphs 中,供下次运行时跳过重复解析。
ts-jest 进程:从 tsJest.process(source) 到 transformed source
原文档的第二张 PlantUML 图描绘了 TsJestTransformer.process() 内部的完整流程。对应源码中,process()(src/legacy/ts-jest-transformer.ts)的核心逻辑被拆成两个私有方法:processWithTs() 负责 TypeScript 侧编译,runTsJestHook() 负责事后钩子。其决策顺序如下:
第一步:是否需要字符串化(stringify)
ConfigSet.shouldStringifyContent(filePath)(src/legacy/config/config-set.ts)根据配置项 stringifyContentPathRegex 判断文件是否应按纯文本内容导出。若命中,processWithTs 直接返回 module.exports=${stringify(sourceText)},即把整个文件内容序列化为 JS 字符串导出,完全跳过 TypeScript 编译。这通常用于把 CSS、SVG 等静态资源当作字符串导入测试。
第二步:.d.ts 声明文件直接清空(wipe source)
源码通过 sourcePath.endsWith(DECLARATION_TYPE_EXT)(即 .d.ts,常量定义见 src/constants.ts)识别声明文件,直接返回空代码 code: '',并注释"no need to compile definition files"。声明文件只有类型信息、没有运行时实现,编译只会浪费性能甚至报错。
第三步:按 isolatedModules 选择编译路径
这是 ts-jest 处理流程的枢纽分支,两条路径差异巨大:
路径 A —— 隔离模块编译(isolatedModules: true):每个文件独立编译,不创建语言服务(constructor 中 if (!this.configSet.isolatedModules) 才会初始化 _fileContentCache、_moduleResolutionHost 与 _createLanguageService(),见 src/legacy/compiler/ts-compiler.ts)。编译走 this._ts.transpileModule(...) 或 tsTranspileModule(...)(ts-compiler.ts)。代价是失去跨文件类型检查与 const enum 等需要工程上下文的特性,但换来显著更快的速度——官方文档明确:配合 jest --no-cache 运行时收益最大。仓库中的 e2e/const-enum 与 e2e/performance 测试项目正是围绕这两条路径的行为差异设计的。
路径 B —— 语言服务编译(默认,isolatedModules: false):首次编译时创建并缓存 TypeScript Language Service,后续复用。_createLanguageService()(ts-compiler.ts)构造了一个精细的 LanguageServiceHost:getScriptSnapshot 按「内存缓存 → Jest 运行时 cacheFS → 文件系统」三级顺序读取文件内容;resolveModuleNames 使用 ts.resolveModuleName 并配合 _moduleResolutionCache 提升性能。编译时先 _updateMemoryCache 把最新文件内容写入内存缓存并递增 _projectVersion(ts-compiler.ts),再 getEmitOutput(fileName) 产出编译结果,同时通过 getSemanticDiagnostics + getSyntacticDiagnostics 获取诊断。注意只有 shouldReportDiagnostics(fileName) 返回真时才会计算诊断——这是 diagnostics.exclude 与 checkJs 等配置的落点(config-set.ts)。
另外,若编译前的文件是 JS/JSX 且 allowJs 未开启,路径 B 会直接警告并原样返回文件内容;若 output.emitSkipped(例如 .tsx 语法错误),会抛出 CannotProcessFile 错误。
第四步:应用自定义 AST transformers
无论走哪条编译路径,最终编译产物都要经过 AST transformer 阶段(图中"custom AST transformers"分支)。ts-jest 把 transformer 分为 before(TS 语法阶段,看到的是 import 而非 require)、after(转译后阶段)与 afterDeclarations(d.ts 生成阶段)三类,配置方式见 astTransformers 文档。源码中 _makeTransformers(ts-compiler.ts)将用户配置的 transformer 工厂注入 CustomTransformers。
其中最重要的内建 transformer 是 hoist-jest(src/transformers/hoist-jest.ts),它被默认注册在 before 位置(config-set.ts)。其职责是把 jest.mock、jest.unmock、jest.enableAutomock、jest.disableAutomock、jest.deepUnmock 调用提升到文件顶部,并正确识别从 @jest/globals 导入的别名形式(命名导入、别名导入、命名空间导入)。它通过 sortStatements 按「@jest/globals 导入 → 可提升的 jest 调用 → 其余语句」的优先级稳定排序(hoist-jest.ts)。这是 jest.mock 在 jest 官方 babel-jest 中也能生效的等价机制,e2e 测试 e2e/tests/hoist-jest.test.ts 与 e2e/hoist-jest 示例项目对其进行了覆盖验证。
第五步:修复 source maps
编译完成后进入"fix source maps"环节。updateOutput(src/legacy/compiler/compiler-utils.ts)把 TypeScript 生成的 source map 改写为 base64 编码的内联 data URI:将 sources 与 file 指向原始文件路径、删除 sourceRoot,然后替换输出末尾 sourceMappingURL= 之后的内容。这样 Jest 的报错堆栈可以精确定位到 .ts 源文件的行列。
第六步:更新缓存
编译成功后依次更新两层缓存:
- 内存缓存(mem cache):写入
_fileContentCache,避免同一文件在多次编译间重复读取磁盘; - 持久化缓存(persistent cache):写入由
cacheSuffix决定的磁盘目录cacheDirectory/ts-jest/<前缀>/<剩余>(config-set.ts)。下一次运行时,若getCacheKey命中(见上文 Jest 进程),直接从持久化缓存恢复编译结果并同步进内存缓存,图中"in persistent cache? → update mem cache from persistent cache"即此分支。
Babel 接力:should use babel? 分支
ts-jest 默认不使用 Babel,但通过 babelConfig 配置项可以开启(详见 babelConfig 文档)。该配置支持三种形态:
false(默认):完全禁用 Babel;true:自动查找项目的.babelrc、.babelrc.js、babel.config.js或package.json中的babel字段;- 对象或路径字符串:内联 Babel 选项,或指向配置文件(支持
.js/.cjs直接 require,其余按 JSON5 解析),也可传{}让 Babel 使用默认配置。
在 processWithTs 完成 TS 编译后,process() 会检查 configs.babelJestTransformer 是否存在(ConfigSet 在构造时通过 importer.babelJest(...).createTransformer(this.babelConfig) 创建,见 config-set.ts),若存在则调用 babelJest.process(result.code, sourcePath, { ...transformOptions, instrument: false }),把 TS 编译产物交给 babel-jest 处理器进行插件级转换。传入 instrument: false 是为了避免与 Jest 后续自身的插桩重复。图中"calls babel-jest processor"即此环节。
事后钩子:afterProcess
流程的最后一步是 runTsJestHook(src/legacy/ts-jest-transformer.ts)。它读取环境变量 TS_JEST_HOOKS 指向的模块,若该模块导出了 afterProcess 函数,则在最终返回前调用它,传入 [sourceText, sourcePath, transformOptions.config, transformOptions] 与当前编译结果;若钩子返回了值,该值将作为新的编译结果。原文档特别注明这是内部 API("not supposed to be a public API but we keep it as some people use it"),源码注释同样强调这一点。
配置项与流程分支速查
下表把原文档流程图中每个分支与对应的 ts-jest 配置项、源码落点对应起来,方便读者在排查问题时快速定位:
| 流程分支 | 配置项 | 默认值 | 源码位置 |
|---|---|---|---|
| 是否需要字符串化 | stringifyContentPathRegex |
未设置(不生效) | config-set.ts |
是否清空 .d.ts |
无(按扩展名自动判定) | .d.ts 清空 |
ts-jest-transformer.ts |
| 是否隔离模块编译 | isolatedModules(tsconfig 或选项) |
false |
config-set.ts |
| 是否做类型诊断 | diagnostics |
true |
config-set.ts |
| 是否运行 Babel | babelConfig |
false(禁用) |
config-set.ts |
| 自定义 AST transformer | astTransformers.before/after/afterDeclarations |
仅内建 hoist-jest(before) | config-set.ts |
| 是否使用磁盘持久化缓存 | Jest cache / cacheDirectory |
启用 | config-set.ts |
是否调用 afterProcess 钩子 |
环境变量 TS_JEST_HOOKS |
未设置(不调用) | ts-jest-transformer.ts |
从源码验证处理链路:e2e 与测试证据
仓库的 e2e 测试项目为上述流程提供了可运行验证:
- e2e/tests/hoist-jest.test.ts:在 compiler(语言服务)与 transpiler(隔离模块)两种模式下分别运行 e2e/hoist-jest 示例,验证
jest.mock提升在两条编译路径下都正确生效; - e2e/tests/extend-ts-jest.test.ts:验证 CJS / ESM × compiler / transpiler 四种组合下,自定义扩展 transformer 均能正常执行;
- e2e/const-enum:对比两种编译路径对
const enum的支持差异——语言服务路径可正确解析跨文件const enum,隔离模块路径则不支持,这与原文档"you'll lose ... some features such asconst enum"的描述一致; - e2e/source-map:验证 source map 修复环节在 compiler / transpiler 与 CJS / ESM 各组合下的正确性。
结语
ts-jest 的处理流程是一套精心设计的「先决策、后缓存、再编译」管线:Jest 层通过 getCacheKey 把配置、依赖图与文件 mtime 折叠进缓存键,最大限度复用编译结果;ts-jest 层则依据文件类型、isolatedModules 与 babelConfig 在字符串化、声明文件跳过、语言服务 / transpileModule 双路径、AST transformer、source map 修复与持久化缓存之间精准分流。理解这条链路的每一个分支及其对应源码(ts-jest-transformer.ts、ts-compiler.ts、config-set.ts),既能帮助你在遇到缓存失效、诊断缺失或性能瓶颈时快速定位根因,也能为自定义 AST transformer 或事后处理钩子的正确接入提供清晰的落点。