ts-jest 处理流程(Processing Flow)深度解析:从 Jest 文件加载到 TypeScript 编译、缓存与 Source Map 修复

原创2026-10-06 19:12:051,913 阅读
文章标签:测试开发工具

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 流程:

  1. 当源码中执行 require('file') 时,Jest 判断该文件是否命中某个 transform 配置;
  2. 若命中,Jest 先询问转换器是否实现了 getCacheKey:
    • 实现 → 调用 transformer.getCacheKey(...) 计算缓存键;
    • 未实现 → 使用 Jest 内置的缓存键算法;
  3. 用缓存键查询 Jest 的转换缓存(文件系统级缓存):
    • 命中 → 直接使用缓存内容,跳过编译;
    • 未命中 → 调用 transformer.process(...) 完成转换,并更新缓存;
  4. 最终执行 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,
  })
}

要点有两个:

  1. babel-jest 拿到的是 TS 编译后的 JavaScript,因此 babelConfig 的典型用途是追加 TS 之外的自定义 Babel 插件(如 CSS 模块、装饰器等);
  2. 显式传入 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') 的完整旅程是:

  1. Jest 命中 transform 规则(^.+\.[tj]sx?$),调用 ts-jest 的 getCacheKey;
  2. getCacheKey 解析出(或复用缓存的)ConfigSet 与 TsJestCompiler,结合文件内容、配置串、依赖图的 mtime 计算出 SHA-1 缓存键;
  3. 缓存未命中 → 调用 process;
  4. processWithTs 判定 foo.ts 既非 stringify 目标也非 .d.ts,进入编译分支;
  5. 走 Language Service 路径:_updateMemoryCache 喂入内容 → getEmitOutput 产出 JS + source map → 收集诊断(有问题则按配置抛出 TSError)→ updateOutput 修复 source map;
  6. 更新内存缓存与持久缓存;
  7. 无 Babel、无 hook,直接返回 { code } 给 Jest;
  8. 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 命中过期产物。

五、相关资源速查

登录后查看全文
ts-jest