ts-jest isolatedModules 选项详解:按文件独立编译、关闭类型检查以提升 Jest 测试性能

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

ts-jest isolatedModules 选项详解:按文件独立编译、关闭类型检查以提升 Jest 测试性能

isolatedModules 是 ts-jest 中用于切换编译模式的核心选项:默认(false)时 ts-jest 在整个项目上下文中运行 TypeScript 编译器,保留完整的类型检查与语言特性;设为 true 后则改为逐文件独立编译(TypeScript 所称的 "isolated module"),放弃类型检查能力与 const enum 等特性,换取在 jest --no-cache 等场景下显著更快的测试执行速度。本文基于 ts-jest 仓库中的 官方选项文档 及其源码实现,讲解该选项的配置方法、性能调优技巧与注意事项,帮助你按需在"完整类型检查"与"极速编译"之间做出选择。

一、背景:ts-jest 的两种编译模式

ts-jest 的定位是 "A Jest transformer with source map support",它默认使用 TypeScript 编译器在你项目的上下文中工作,即具备完整的类型检查(type-checking)和全部语言特性。这种模式的优点是与 tsc 行为一致,能在测试阶段就暴露类型错误;代价则是编译器需要维护整个项目的 Program / Language Service,处理文件间依赖关系,开销较大。

与此相对的是隔离模块(isolated module)模式:TypeScript 本身支持将每个文件视为一个独立单元单独编译(对应 tsc --isolatedModules 及 transpileModule API),ts-jest 的 isolatedModules 选项(默认 false)正是用来开启这一模式。开启后你会失去类型检查能力和部分特性(例如 const enum),但在计划使用 jest --no-cache(禁用 Jest 缓存)运行时,测试会快得多。

二、配置方式:三种入口,同一个开关

文档给出了三种配置入口,均通过 transform 配置中的 ts-jest 选项传递 isolatedModules: true。三种写法完全等价,可任选其一:

1. jest.config.js(CommonJS)

// jest.config.js
/** @type {import('ts-jest').JestConfigWithTsJest} */
module.exports = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process ts,js,tsx,jsx with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process ts,js,tsx,jsx,mts,mjs,mtsx,mjsx with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        isolatedModules: true,
      },
    ],
  },
}

2. jest.config.ts(TypeScript + ESM 导出)

// jest.config.ts
import type { JestConfigWithTsJest } from 'ts-jest'

const jestConfig: JestConfigWithTsJest = {
  // [...]
  transform: {
    // '^.+\\.[tj]sx?$' to process js/ts with `ts-jest`
    // '^.+\\.m?[tj]sx?$' to process js/ts/mjs/mts with `ts-jest`
    '^.+\\.tsx?$': [
      'ts-jest',
      {
        isolatedModules: true,
      },
    ],
  },
}

export default jestConfig

3. package.json 内嵌 jest 配置

// package.json
{
  // [...]
  "jest": {
    "transform": {
    // '^.+\\.[tj]sx?$' to process js/ts with `ts-jest`
      // '^.+\\.m?[tj]sx?$' to process js/ts/mjs/mts with `ts-jest`
      "^.+\\.tsx?$": [
        "ts-jest",
        {
          "isolatedModules": true
        }
      ]
    }
  }
}

注意三个示例中 transform 正则的注释:'^.+\\.[tj]sx?$' 覆盖 ts,js,tsx,jsx;'^.+\\.m?[tj]sx?$' 额外覆盖 mts,mjs,mtsx,mjsx。请根据项目实际需要匹配的文件类型选择。

三、源码视角:该选项在 ts-jest 内部如何生效

从源码可以确认 isolatedModules 并非只是把参数透传给 TypeScript,而是改变了 ts-jest 内部整个编译管线的工作方式。

1. 配置解析与默认值

在旧版配置体系 src/legacy/config/config-set.ts 中,ts-jest 会把 transform 选项中的 isolatedModules: true 合并进解析后的 tsconfig 编译选项,并最终归一化为 this.isolatedModules = this.parsedTsConfig.options.isolatedModules ?? false——即默认值为 false,与文档表述一致。

// src/legacy/config/config-set.ts
if (options.isolatedModules) {
  this.parsedTsConfig.options.isolatedModules = true
  // ...记录弃用警告
}
this.isolatedModules = this.parsedTsConfig.options.isolatedModules ?? false

同时,src/types.ts 的类型定义表明该选项属于 boolean 类型,并标注了其与 TsConfigCompilerOptionsJson.isolatedModules 的关系(详见下文"版本演进")。

2. 编译器的构建差异

在编译器实现 src/legacy/compiler/ts-compiler.ts 中可以看到,只有当 isolatedModules 为 false 时,ts-jest 才会:

  • 建立文件内容缓存(_fileContentCache)与文件版本缓存(_fileVersionCache);
  • 构造带缓存的模块解析宿主(_moduleResolutionHost);
  • 创建模块解析缓存(_moduleResolutionCache);
  • 最终调用 _createLanguageService() 创建完整的 Language Service。

也就是说,完整类型检查模式依赖一整套 Language Service / Program 基础设施来跟踪跨文件类型信息;而 isolatedModules: true 时这些设施被整体跳过,每个文件走独立的逐文件转译路径,这正是性能差异的根源。

3. 缓存键计算的差异

在 src/legacy/ts-jest-transformer.ts 的 getCacheKey 中,非隔离模式下 ts-jest 需要把文件递归解析出的所有依赖模块路径(getResolvedModules)加入缓存键,以保证任一依赖变化时缓存失效;而 isolatedModules: true 时由于不追踪依赖图(if (!configs.isolatedModules && configs.tsCacheDir) 分支被跳过),缓存键的计算大幅简化,这也是该模式配合 Jest 缓存机制时开销更低的原因之一。

4. 逐文件转译的实现

现代(非 legacy)路径下,逐文件转译由 src/transpilers/typescript/transpile-module.ts 承担,其 transpileWorker 基于 ts.transpileModule 的内核逻辑重写:为每个输入文件创建独立的 SourceFile,使用精简的 "barebones" lib.d.ts 作为全局环境,不生成声明文件(declaration = false),并允许挂载自定义 AST transformers。值得注意的是其中一行细节:

// src/transpilers/typescript/transpile-module.ts
if (options.verbatimModuleSyntax && new Set(['isolatedModules']).has(option.name)) {
  continue
}

即当用户显式开启 verbatimModuleSyntax 时,ts-jest 会避免重复设置 isolatedModules 的转译默认值,确保选项组合始终合法。

四、性能调优:收窄 tsconfig 的 include 范围

文档明确指出:使用 isolatedModules: false(完整类型检查)相比 true 是有性能代价的。如果你必须保留完整类型检查,可以通过调整 ts-jest 所读取的 tsconfig 中的 include 字段来提升性能——include 中列出的文件越少,测试运行能获得的性能提升越大。

// tsconfig.json
{
  // ...other configs
  "include": ["my-typings/*", "my-global-modules/*"]
}

原理在于:完整类型检查模式下,TypeScript Program 需要加载并解析 include 覆盖的全部文件(含全局类型声明、自定义模块声明等),文件越多,Program 构建与增量更新的开销越大。将 include 收窄到测试环境实际需要的声明文件与全局模块,即可显著减小 Program 体积。

仓库中的实践佐证

ts-jest 自身的端到端测试正是这样做的:所有 "transpiler" 系列的 tsconfig 都通过 extends 继承基础配置并单独叠加 isolatedModules: true,例如 e2e/enum/tsconfig-cjs-transpiler.spec.json:

{
  "extends": "./tsconfig-cjs.spec.json",
  "compilerOptions": {
    "isolatedModules": true
  }
}

同样的模式还出现在 e2e/presets/tsconfig-cjs-transpiler.spec.json、e2e/source-map/tsconfig-cjs-transpiler.spec.json、e2e/transform-js/tsconfig-cjs-transpiler.spec.json 等大量 e2e 目录中——这说明"用独立 tsconfig 组合出隔离编译模式"本身就是 ts-jest 项目验证性能与功能的重要手法,可以作为你配置项目的直接参考模板。

五、注意事项(Caveats)

通过 include 限制文件加载量可以大幅提升测试性能,但代价是:ts-jest 可能无法识别所有你打算交给 Jest 处理的文件,进而遇到自定义类型声明(custom typings)、全局模块(global modules)等解析问题。

文档给出的建议解决方案是:测试环境真正需要的内容应该全部被 include 中的 glob 模式覆盖到,这样才能同时获得性能提升并避免破坏现有行为。换言之,include 的收窄不是"越窄越好",而是要恰好囊括:

  • 测试文件本身依赖的源码文件(若其依赖不在 include 内,类型信息会缺失);
  • 项目自定义的全局类型声明(.d.ts);
  • 全局注册模块(global modules)的声明;
  • 任何测试运行期需要被 Program 感知的环境类型。

关于 const enum 的限制

由于隔离模式下每个文件独立编译、无法跨文件内联枚举常量,const enum 将不可用。这一点在仓库的 e2e/const-enum 端到端测试中得到印证:该目录同时提供了常规模式与 transpiler 模式两套 tsconfig(如 e2e/const-enum/tsconfig-cjs-transpiler.spec.json 同样开启 isolatedModules: true),并通过 e2e/const-enum/tests/const-enum.spec.ts 验证 const enum 在相应模式下的行为差异。如果你的代码大量使用 const enum 跨文件引用,切换到 isolatedModules: true 前需要评估迁移成本(如改用普通 enum 或常量对象)。

六、版本演进:从 ts-jest 选项到 tsconfig 选项

需要特别留意的是该选项正处于弃用过渡期。在仓库当前主版本文档 website/docs/getting-started/options/isolatedModules.md 中,页面顶部明确标注:

此页面现已 DEPRECATED,并将在下一个大版本中随配置选项 isolatedModules 一起移除,请改用 tsconfig.json 中的 isolatedModules 选项。

这一点与源码互相印证:在 src/utils/messages.ts 中定义了对应的弃用提示信息——当用户在 ts-jest 配置中设置 isolatedModules 时,会收到警告"该配置项已弃用,将在 v30.0.0 移除,请改用 tsconfig 中的 isolatedModules: true"。在 src/legacy/config/config-set.ts 中也能看到,同时存在 tsconfig 路径时 ts-jest 会记录带 tsconfigFilePath 的弃用警告。

因此,新项目建议直接在 tsconfig.json 中配置:

// tsconfig.json
{
  "compilerOptions": {
    "isolatedModules": true
  }
}

ts-jest 会读取该 tsconfig 选项并自动进入隔离编译模式;而老配置中的 globals.ts-jest.isolatedModules / transform 选项写法仅用于兼容旧项目,应逐步迁移。presets 系列文档(如 website/docs/getting-started/presets.md)也早已把 isolatedModules 列为可配置项并指向本页说明。

七、小结与选择建议

对比维度 isolatedModules: false(默认) isolatedModules: true
编译方式 项目上下文 + Language Service 完整编译 每个文件作为隔离模块独立编译
类型检查 完整保留 关闭
const enum 等跨文件特性 支持 不支持
模块依赖图/缓存键 追踪并纳入缓存键 不追踪,缓存键简化
测试运行性能 相对较慢 更快,尤其配合 jest --no-cache
适用场景 希望在测试阶段拦截类型错误 追求速度、已另行保证类型安全(如 CI 中跑 tsc)

推荐实践:日常开发若依赖 ts-jest 做类型检查,保持默认;若追求极致测试速度、且项目已有独立的 tsc --noEmit 类型检查环节,则开启 isolatedModules: true,并通过精心收窄的 include 列表(在 tsconfig 中配置)兼顾性能与稳定性。同时注意及时跟进 ts-jest 的弃用节奏,将配置迁移到 tsconfig 原生 isolatedModules 选项上,避免在下一个大版本升级时遇到配置失效问题。

登录后查看全文
ts-jest