Nx 23.1 迁移指南ts-jestisolatedModules迁移后的 typecheck 验证与故障修复【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx导读Nx 23.1 的set-ts-jest-isolated-modules迁移会为受影响的 ts-jest 项目在tsconfig.spec.json中启用isolatedModules以解决 TypeScript 6 下 ts-jest 无法解析 exports-only 工作区库的 TS2307 问题。本文以该迁移自带的验证文档packages/jest/src/migrations/update-23-1-0/verify-typecheck.md为主线完整讲解迁移背景、nx run-many -t typecheck验证流程、TS1205/TS2748 等故障的诊断与修复策略并结合仓库源码说明迁移的触发条件与底层原理帮助你安全完成本次升级。迁移背景为什么 ts-jest 需要isolatedModulesNx 23.1 的 jest 迁移路径将 ts-jest 提升到 29.4.x。在 CommonJS jest 路径下ts-jest 29.2 在 TypeScript 6 时当bundler与强制设定的module: commonjs组合无效时会回退使用moduleResolution: node10。而node10解析模式不读取包的exports映射exports map因此一个仅通过exports暴露类型的 ts-solution 工作区库在 ts-jest 类型检查期间会解析失败报出如下错误error TS2307: Cannot find module my-org/some-lib or its corresponding type declarations.这正是仓库内部工单 NXC-4591 所跟踪的问题。修复思路是迁移把isolatedModules: true写入每个受影响的tsconfig.spec.json让 ts-jest 逐文件独立转译跳过此前失败的跨文件类型解析。这一设定与全新的 ts-solution 工作区在tsconfig.base.json中已经设置的isolatedModules: true保持一致而每个项目自身的 typecheck 仍然由各自专属的 typecheck target 承担类型检查能力并未因此丢失。迁移的精确触发条件源码视角从迁移实现 set-ts-jest-isolated-modules.ts 可以看到迁移只在同时满足以下条件时才会真正写入配置TypeScript 6isTypescriptVersionAtLeast(tree, 6.0.0)为真时直接返回。TypeScript 6 及以上能够在bundlercommonjs下正确解析exports因此这些工作区不会被改动ts-solution 工作区isUsingTsSolutionSetup(tree)为假即基于paths的 path-based 工作区时直接返回因为 path-based 工作区通过 tsconfigpaths而非exports解析不受影响根 tsconfig 未开启该选项如果tsconfig.base.json中已经启用了isolatedModulesrootEnablesIsolatedModules检测到true迁移跳过——新工作区本来就有这个配置该项目确实使用 ts-jestgetTsJestSpecTsconfig会先找到项目的 jest 配置若其内容命中以下任一标记则跳过swc/jest、babel-jest、jest-preset-angular、getJestProjectsAsync。这些项目走 swc/babel/angular 转译链路不属于 ts-jest根聚合配置也被排除。写入时迁移使用jsonc-parser的modify/applyEdits以keepLines方式精确插入compilerOptions.isolatedModules true从而保留原有注释与格式测试用例 set-ts-jest-isolated-modules.spec.ts 专门验证了这一点。迁移完成后会通过formatFiles统一格式化并在日志中输出NXC-4591: set isolatedModules: true in N tsconfig.spec.json file(s)...的统计信息。迁移产生的配置变更对于受影响的项目tsconfig.spec.json的改动前后对比如下改动前{ extends: ../../tsconfig.base.json, compilerOptions: { types: [jest, node] } }改动后{ extends: ../../tsconfig.base.json, compilerOptions: { isolatedModules: true, types: [jest, node] } }值得一提的是迁移元数据注册在 packages/jest/migrations.json版本为23.1.0-beta.4并带有requires: { ts-jest: 29.2.0 }前置条件。其中prompt字段指向的正是本文依据的验证文档 verify-typecheck.md它会在迁移执行后作为提示引导用户完成验证而documentation字段指向更完整的迁移说明 set-ts-jest-isolated-modules.md。迁移后的第一步验证运行 typecheck迁移会修改多个项目的测试类型检查配置因此迁移本身正确运行不等于工作区仍然健康。验证流程的第一步是对整个工作区执行类型检查nx run-many -t typecheck执行后请逐一检查输出修复所有因isolatedModules而暴露出来的项目。注意此处的验证对象是每个项目独立的 typecheck target而不是 ts-jest 在转译时的轻量类型检查——正如迁移文档所说“Type checking stays on each projects dedicated typecheck target”isolatedModules只影响 ts-jest 的逐文件转译项目自身的完整类型检查依然由 typecheck target 负责这也是本验证步骤存在价值的原因。理解故障症状两类问题isolatedModules开启后可能引入两类问题验证时需要分别识别第一类typecheck 阶段直接失败。典型错误码有两个TS1205—— 再导出的类型需要显式使用export type。因为逐文件转译无法确定一个再导出的标识符到底是类型还是值TypeScript 要求你明确标注TS2748—— 跨文件的const enum访问。const enum的值在编译期内联逐文件转译时看不到其他文件的枚举定义因此无法正确内联。第二类typecheck 通过但项目测试在运行时被破坏。这类问题更隐蔽根因是某个包既通过module.exports又通过 ESM 的export再导出同一个值例如以const enum暴露类型的 napi 绑定。逐文件转译无法完整保留这种双重导出形态导致该const enum的消费者在运行时同样受损。换句话说isolatedModules的破坏力可能完全绕开类型检查只在测试执行阶段爆发。修复策略先回退再判断归属面对一个被迁移改坏的项目标准修复流程如下尝试回退从该项目的tsconfig.spec.json中移除isolatedModules然后重新运行 typecheck观察 TS2307 是否回归如果移除后一切正常没有重新出现TS2307: Cannot find module错误说明该项目其实不需要isolatedModules保持移除后的状态即可如果移除后针对某个工作区库的TS2307: Cannot find module错误再次出现说明该项目恰恰依赖isolatedModules来绕过 ts-jest 的node10解析缺陷——此时应当保留isolatedModules改为修复源码修复源码当需要保留isolatedModules时避免在同一包中混用module.exports与 ESM 的export来导出同一实体避免跨文件使用const enum改用普通enum或显式类型导出。反复执行“运行 typecheck → 修复 → 再运行”的循环直到本次迁移触及的所有项目都通过类型检查为止。源码级原理Nx 插件如何感知isolatedModules理解插件侧的行为有助于判断修复方向。在 packages/jest/src/plugins/plugin.ts 中Nx jest 插件通过resolveIsolatedModules沿 tsconfig 的extends链向上解析compilerOptions.isolatedModules的生效值判定规则包括链上任一 tsconfig 显式设置isolatedModules即取其值并停止verbatimModuleSyntax: true视为等价于isolatedModules: trueTypeScript 5.0也是 Nx 支持的最低版本因为它隐含了逐文件安全转译的语义。插件据此决定测试缓存的输入范围当 ts-jest未开启isolatedModules时它会创建 TypeScript Language Service 并读取依赖项目的.d.ts文件因此插件会把这些声明文件声明为dependentTasksOutputFiles见 plugin.ts确保依赖类型声明的变更能正确使测试缓存失效。这从侧面印证开启isolatedModules后 ts-jest 放弃跨文件解析正是消除这一系列耦合的关键。此外新项目生成器在创建 ts-solution 工作区的 ts-jest 项目时也已经按同样的判断逻辑默认写入isolatedModules: true见 create-files.ts 与模板 tsconfig.spec.json__tmpl__即“ts-solution ts-jest moduleResolution: node10”三者同时成立时才生成该选项。这说明本次迁移并非临时补丁而是与插件推断、生成器默认值保持一致的长期策略。验证清单与最终状态确认完成上述修复后建议按以下清单做最终确认全量运行nx run-many -t typecheck输出无任何TS1205、TS2748、TS2307错误检查被迁移改动过的tsconfig.spec.json保留isolatedModules: true的项目其源码中不存在module.exports与 ESMexport混用、不存在跨文件const enum运行相关项目的测试任务如nx run-many -t test确认运行期行为正常特别是对 napi 绑定或const enum有依赖的库若工作区同时包含 swc/babel/angular 的 jest 项目确认它们未被迁移改动迁移已通过标记符跳过此类项目测试见 set-ts-jest-isolated-modules.spec.ts。迁移的判定与写入逻辑、测试用例以及插件的isolatedModules解析实现都已在上述源码文件中给出你可以对照仓库进一步深入迁移实现见 set-ts-jest-isolated-modules.ts完整测试见 set-ts-jest-isolated-modules.spec.ts迁移注册与说明见 migrations.json 与 set-ts-jest-isolated-modules.md。【免费下载链接】nxThe Monorepo Platform that amplifies both developers and AI agents. Nx optimizes your builds, scales your CI, and fixes failed PRs automatically. Ship in half the time.项目地址: https://gitcode.com/GitHub_Trending/nx/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考