ts-jest 处理流程(Processing Flow)深度解析:从 Jest 文件加载到 TypeScript 编译、缓存与 Source Map 修复
ts-jest 处理流程(Processing Flow)深度解析:从 Jest 文件加载到 TypeScript 编译、缓存与 Source Map 修复
导读:本文以 ts-jest 官方内部技术文档 processing.md 为骨架,结合当前仓库的源码实现,完整拆解一条测试文件从 require() 到产出最终 JavaScript 代码的完整链路。你将理解 Jest 的转换器缓存协议(getCacheKey → process)、ts-jest 内部的四大处理阶段(stringify / .d.ts 处理 / 编译 / Babel 与 Hook 后处理)、isolatedModules 与 Language Service 两种编译路径的取舍,以及 source map 修复与双级缓存的底层原理。
:::note
本文对应的官方文档定位为“内部技术文档”(internal technical documents),主要面向 ts-jest 贡献者与对实现机制感兴趣的进阶用户。普通使用者若只关心配置用法,可优先阅读 getting-started/options.md 及其子页面;本文则深入讲解“文件到底是怎么被转换出来的”。
:::
一、总览:Jest 转换器协议下的两段式处理
ts-jest 本质上是一个实现 Jest SyncTransformer 接口的转换器,核心类为 TsJestTransformer(见 src/legacy/ts-jest-transformer.ts)。Jest 在运行时对每个匹配 transform 规则的文件都会调用它,调用时序严格遵循官方文档中的 Jest process 流程:
- 当源码中执行
require('file')时,Jest 判断该文件是否命中某个transform配置; - 若命中,Jest 先询问转换器是否实现了
getCacheKey:- 实现 → 调用
transformer.getCacheKey(...)计算缓存键; - 未实现 → 使用 Jest 内置的缓存键算法;
- 实现 → 调用
- 用缓存键查询 Jest 的转换缓存(文件系统级缓存):
- 命中 → 直接使用缓存内容,跳过编译;
- 未命中 → 调用
transformer.process(...)完成转换,并更新缓存;
- 最终执行
require()加载转换后的模块。
这段流程在源码中对应 TsJestTransformer.getCacheKey。它的缓存键由以下要素拼接后经 SHA-1 哈希生成:
- 序列化后的 Jest 配置与
ts-jest配置(this._transformCfgStr,由 ConfigSet.cacheSuffix 参与组成); - 项目
rootDir; - 插桩开关(
instrument:on/off)与 ESM 支持状态(supportsStaticESM:on/off); - 文件内容、文件路径;
- 依赖图:非
isolatedModules模式下,还会递归解析该文件直接与间接导入的模块路径,并把每个依赖文件的mtimeMs一并纳入哈希。
也就是说,只要 tsconfig、Babel 配置、AST transformer 版本、依赖文件修改时间中任何一个发生变化,缓存键就会失效,从而保证 Jest 不会复用过期的编译产物。这一点是官方文档“Jest process”流程图背后最重要的设计动机,正如 ConfigSet 顶部注释所写:“Fast jest relies on correct cache keys depending on all settings that could affect the generated output.”
二、ts-jest 内部处理流程:一次 process() 的完整旅程
官方文档的第二张流程图(ts-jest process)详细刻画了 TsJestTransformer.process 的内部逻辑。对照源码 process 与 processWithTs,整个处理链可分为五个有序阶段:
tsJest.process(source)
├─ ① stringify 阶段:匹配 stringifyContentPathRegex 的文件直接导出自身内容
├─ ② .d.ts 阶段:声明文件跳过编译,输出空代码
├─ ③ 编译阶段:
│ ├─ isolatedModules = true → transpileModule(单文件转译,不做类型检查)
│ └─ isolatedModules = false → Language Service(全项目类型检查 + 编译)
│ └─ 应用自定义 AST transformers(含 jest.mock 提升)
│ └─ 修复 source map → 更新内存缓存 → 更新持久缓存
├─ ④ Babel 阶段:若配置了 babelConfig,调用 babel-jest 二次处理
└─ ⑤ Hook 阶段:调用 afterProcess 钩子(若设置)输出最终源码
下面逐阶段展开。
阶段 ①:Stringify —— 把文件“变成”自己的字符串
当文件路径命中 stringifyContentPathRegex 配置时(判断逻辑见 ConfigSet.shouldStringifyContent),ts-jest 不编译该文件,而是把它导出为一个“返回自身内容”的模块:
// 源码:src/legacy/ts-jest-transformer.ts
result = {
code: `module.exports=${stringify(sourceText)}`,
}
例如官方配置文档 stringifyContentPathRegex.md 中的例子:若 foo.ts 内容为 export default "bar",且 stringifyContentPathRegex 匹配 foo\.ts$,则最终模块导出的将是字符串 "export default \"bar\"",而非编译后的代码。
该选项主要为兼容旧的 __HTML_TRANSFORM__ 行为而保留,典型用途是把 HTML、SVG 等资源文件转成字符串模块。配置示例(来自官方文档):
import type { Config } from 'jest'
const jestConfig: Config = {
// [...]
moduleFileExtensions: ['html'],
transform: {
// [...]
'\\.html$': [
'ts-jest',
{
stringifyContentPathRegex: /\.html$/,
},
],
},
}
export default jestConfig
注意(官方文档明确强调):使用该选项时,必须保证 Jest 的 transform 配置确实把匹配到的文件交给 ts-jest 处理,并且可能需要把这些扩展名加入 moduleFileExtensions,否则 Jest 根本不会把文件路由到该转换器。
阶段 ②:.d.ts 文件 —— 跳过编译,直接清空源码
官方流程图在 stringify 之后紧接着一个分支:如果文件名以 .d.ts 结尾,则“wipe source”,并注释说明“无需编译声明文件”。源码中的实现对应 processWithTs:
const isDefinitionFile = sourcePath.endsWith(DECLARATION_TYPE_EXT) // '.d.ts'
if (isDefinitionFile) {
// do not try to compile declaration files
result = { code: '' }
}
声明文件(.d.ts)只有类型信息、没有可执行代码,因此直接输出空代码即可。反过来,如果某个路径被判定为“其他未知类型文件”(既不是 .d.ts,也不是 <a href="https://link.gitcode.com/i/69c39128248cdedd780849498535d608" target="_blank">cm]?[jt]sx? 家族),ts-jest 会记录一条警告日志,并把源码原样返回,因为 TypeScript 本身无法编译这类文件——此时如果用户需要处理它们,应在 Jest 配置中为对应扩展名单独指定 babel-jest 之类的转换器(见 [ts-jest-transformer.ts 的注释说明)。
阶段 ③:核心编译 —— 两条路径的分水岭:isolatedModules
这是整个处理流程的心脏。官方流程图用两个分支刻画了 ts-jest 的编译策略,判断依据是是否开启 isolatedModules 选项,该开关对应官方选项文档 isolatedModules.md(禁用类型检查)。两条路径分别由 TsCompiler 在构造时(L100-L136)与运行时(getCompiledOutput)决定。
路径 A:isolatedModules: true —— transpileModule 单文件快速转译
- 每个文件独立交给
ts.transpileModule(或仓库内定制的tsTranspileModule,见 src/transpilers/typescript/transpile-module.ts)进行语法级转译; - 不做跨文件的类型检查,因此速度更快,但类型错误不会被发现(官方文档在图中注释:“files will be compiled as isolated modules”);
- 官方配置文档明确指出它禁用类型检查,适合对编译速度敏感、或类型检查交由 IDE / 独立
tsc流程负责的项目; - 源码层面,该模式还会产生一条弃用提示(config-set.ts),并跳过 Language Service 与文件版本缓存的创建。
路径 B:isolatedModules: false(默认)—— 缓存化的 TypeScript Language Service
- 首次遇到项目时,
ts-jest基于解析后的 tsconfig 创建并缓存一个 TypeScript Language Service(官方流程图注明 “create and cache ts lang service”); - Language Service 的宿主(service host)在 TsCompiler._createLanguageService 中构建:它维护文件内容缓存与文件版本缓存(
_fileContentCache/_fileVersionCache),读取文件时优先走内存缓存 → Jest 运行时缓存(runtimeCacheFS)→ 兜底再走磁盘(getScriptSnapshot的读取顺序,见 ts-compiler.ts); - 每次编译一个文件前,会先通过
_updateMemoryCache把最新内容喂给 Language Service,并在内容变化时递增_projectVersion(ts-compiler.ts),确保 TypeScript 不会复用陈旧的程序(Program); - 编译产物的同时,通过
getSemanticDiagnostics+getSyntacticDiagnostics收集诊断(getDiagnostics),并按diagnostics配置决定是抛出TSError还是仅记录警告(ConfigSet.raiseDiagnostics)。官方流程图中的 “mem cache is used when reading files” 即指这一整套内存缓存机制。
自定义 AST Transformers:jest.mock 提升的发生地
无论走哪条编译路径,编译阶段都会挂载 自定义 AST transformers(官方流程图注释:“here is where hoisting of jest.mock is done, as well as user-defined transformations based on config”)。在 config-set.ts 中,resolvedTransformers.before 默认内置了 hoist-jest 转换器,用户还可通过 astTransformers 配置追加 before / after / afterDeclarations 三类转换器(详见 astTransformers.md):
before:在 TS 自带转换之前运行,拿到的是原始 TS 语法(import尚未变成require);after:在 TS 转换之后运行,拿到转译后的语法;afterDeclarations:在.d.ts生成阶段运行,可改写输出的类型声明。
内置的 hoist-jest 转换器(src/transformers/hoist-jest.ts)会把 jest.mock / jest.unmock / jest.enableAutomock / jest.disableAutomock / jest.deepUnmock 等调用提升到文件顶部(连同 @jest/globals 的导入语句一起按优先级重排,见 sortStatements,hoist-jest.ts),这是 Jest mock 在测试文件中能够“先于导入生效”的关键实现。它导出的 version = 4 也会参与缓存键计算——转换器内容变更时版本号递增,从而强制 Jest 放弃旧缓存。
转换器通过 TsCompiler._makeTransformers 被组装进 TypeScript 的 CustomTransformers,分别映射到 before / after / afterDeclarations 三个插槽。
修复 Source Map:把映射指向真实源文件
编译完成后,官方流程图进入 “fix source maps” 阶段。对应的实现是 compiler-utils.ts 中的 updateOutput / updateSourceMap:
const updateSourceMap = (sourceMapText: string, normalizedFileName: string): string => {
const sourceMap = JSON.parse(sourceMapText)
sourceMap.file = normalizedFileName
sourceMap.sources = [normalizedFileName]
delete sourceMap.sourceRoot
return stringify(sourceMap)
}
TypeScript 生成的 source map 默认指向虚拟的 module.ts / module.tsx 等内部文件名,ts-jest 会将其重写为真实的原始文件路径,并把 map 以 data:application/json;charset=utf-8;base64,... 的 data URI 形式内联回编译产物末尾(替换掉原有的 //# sourceMappingURL= 后缀)。这样当测试断言失败时,Jest 的栈信息能准确映射回 .ts 源文件的行列,这正是项目描述中 “source map support” 的具体实现。仓库内的 e2e/source-map 用例专门验证了这一行为。
双级缓存:内存缓存 + 持久缓存
官方流程图中编译完成后依次出现 “update mem cache” 与 “update persistent cache”:
- 内存缓存:Language Service 的
_fileContentCache/_fileVersionCache保证同一测试会话内反复读取文件不走磁盘; - 持久缓存:
ConfigSet._resolveTsCacheDir(config-set.ts)基于“TypeScript 版本 + ts-jest digest + Babel 配置 + tsconfig 选项 + isolatedModules + diagnostics 配置 + 转换器名称/版本”计算cacheSuffix,并把缓存目录落在cacheDirectory/ts-jest/<suffix前2位>/<剩余suffix>。官方流程图开头的 “if (in persistent cache?)” 分支,正是 Jest 在调用process前用getCacheKey的 SHA-1 键去命中这层缓存的体现。
阶段 ④:Babel 后处理 —— babelConfig 开启时的接力
编译出 TS 产物后,如果配置了 babelConfig(默认禁用),ts-jest 会把结果交给 babel-jest 的 transformer 再处理一遍(官方流程图注释:“calls babel-jest processor”)。源码实现见 process:
if (babelJest) {
// do not instrument here, jest will do it anyway afterwards
result = babelJest.process(result.code, sourcePath, {
...transformOptions,
instrument: false,
})
}
要点有两个:
babel-jest拿到的是 TS 编译后的 JavaScript,因此babelConfig的典型用途是追加 TS 之外的自定义 Babel 插件(如 CSS 模块、装饰器等);- 显式传入
instrument: false,避免 Babel 提前插桩——覆盖率插桩由 Jest 在转换之后统一完成(源码注释明确说明)。
对应的配置解析在 config-set.ts:babelConfig 可以是字符串路径(.js/.cjs 用 require 加载,其他格式按 JSON5 解析)、内联对象或布尔值。
阶段 ⑤:afterProcess Hook —— 非公开的扩展点
流程图的最后一步是判断是否存在 afterProcess 钩子。它并非公开 API,但被社区广泛使用(源码注释原话:“This is not supposed to be a public API but we keep it as some people use it”,ts-jest-transformer.ts)。
实现逻辑(runTsJestHook):通过环境变量 TS_JEST_HOOKS 指向一个模块文件,若该模块导出 afterProcess 函数,则在 Babel 处理之后调用它:
const newResult = hooks.afterProcess(
[sourceText, sourcePath, transformOptions.config, transformOptions],
compiledOutput,
)
钩子接收(原始源码、文件路径、Jest 配置、转换选项)与当前编译产物,如果返回值非空,将作为最终源码。单测中通过 process.env.TS_JEST_HOOKS = __filename 注入 fake hook 验证了该路径(见 ts-jest-transformer.spec.ts)。
三、把流程串起来:一个文件的完整旅程
综合以上两段流程,以最典型的默认配置(非 isolatedModules、无 Babel、开启 diagnostics)为例,一次 require('./foo.ts') 的完整旅程是:
- Jest 命中
transform规则(^.+\.[tj]sx?$),调用ts-jest的getCacheKey; getCacheKey解析出(或复用缓存的)ConfigSet与TsJestCompiler,结合文件内容、配置串、依赖图的mtime计算出 SHA-1 缓存键;- 缓存未命中 → 调用
process; processWithTs判定foo.ts既非 stringify 目标也非.d.ts,进入编译分支;- 走 Language Service 路径:
_updateMemoryCache喂入内容 →getEmitOutput产出 JS + source map → 收集诊断(有问题则按配置抛出TSError)→updateOutput修复 source map; - 更新内存缓存与持久缓存;
- 无 Babel、无 hook,直接返回
{ code }给 Jest; - Jest 将结果写入自身转换缓存,最终
require()加载。
若 isolatedModules: true,第 5 步替换为 transpileModule 单文件转译,跳过类型检查,速度更快但诊断更少;若配置了 babelConfig,第 7 步之前会插入 babel-jest 处理。
四、性能与正确性的设计取舍
理解这张流程图后,可以提炼出 ts-jest 处理流水线中几组核心权衡:
| 维度 | 默认(Language Service) | isolatedModules: true(transpileModule) |
|---|---|---|
| 类型检查 | 完整语义 + 语法诊断 | 不做类型检查 |
| 编译单位 | 以项目为整体,跨文件感知 | 单文件独立转译 |
| 速度 | 首次较慢,会话内缓存复用 | 更快 |
| 适用场景 | 需要 ts-jest 报出类型错误 | 类型检查交给独立 tsc / IDE |
缓存键设计的核心思想(config-set.ts):“配置即缓存键” —— 所有影响输出内容的配置(compiler 模块、tsconfig、Babel、AST transformer、diagnostics、isolatedModules)都被序列化进 cacheSuffix,任何一处变更都会自然导致缓存失效,避免 Jest 命中过期产物。
五、相关资源速查
- 官方内部流程文档:website/docs/processing.md
- 转换器主体实现:src/legacy/ts-jest-transformer.ts
- 编译器实现(Language Service / transpileModule 双路径):src/legacy/compiler/ts-compiler.ts
- 配置解析与缓存目录计算:src/legacy/config/config-set.ts
- source map 修复:src/legacy/compiler/compiler-utils.ts
jest.mock提升转换器:src/transformers/hoist-jest.tstranspileModule定制实现:src/transpilers/typescript/transpile-module.ts- 各选项使用文档:website/docs/getting-started/options.md、stringifyContentPathRegex、astTransformers、isolatedModules
- 端到端验证用例:e2e/source-map、e2e/hoist-jest