尧图网页设计 
Nx 23 迁移指南将nx/jest:jest的setupFile选项迁移至setupFilesAfterEnv【免费下载链接】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 及更高版本、仍依赖nx/jest:jestexecutor 中已废弃的setupFile选项的开发者。文章以官方迁移文档为主体结合 Nx 仓库中的迁移实现源码与完整测试用例系统讲解该自动化迁移的执行逻辑、支持与不支持的场景、nx.json目标默认值的处理方式以及迁移后可能触发警告时的手动修复方案。读完本文你将能够准确预判npx nx migrate在升级过程中会对你的 Jest 配置做什么、为什么这么做以及迁移失败时如何安全地补齐配置。迁移背景为什么废弃setupFile选项在 Nx 23 之前nx/jest:jestexecutor 支持一个名为setupFile的选项用来为每个项目的 Jest 测试指定初始化文件例如 Angular 项目中的test-setup.ts。这一选项在项目配置project.json与工作区默认配置nx.json的targetDefaults中声明由 executor 在运行时把路径注入到 Jest 的配置对象中。问题在于Jest 本身已经提供了标准的setupFilesAfterEnv配置项用来声明在每个测试文件所在的测试套件运行之前执行的初始化模块列表。executor 层再维护一份setupFile既与 Jest 原生机制重复又给配置解析、缓存和推断带来额外负担。因此Nx 23 将setupFile标记为废弃并提供了一条自动化迁移路径把 setup 文件路径追加到项目 Jest 配置的setupFilesAfterEnv数组中同时从project.json与nx.json的 target defaults 中删除废弃的setupFile选项。该迁移在 migrations.json 中注册版本号为23.0.0-beta.22描述为把nx/jest:jestexecutor 废弃的setupFile选项迁移到项目 Jest 配置中的setupFilesAfterEnv并从project.json和nx.jsontarget defaults 中移除该选项。升级时 Nx 会自动执行它无需手动干预。迁移的核心行为迁移逻辑的入口位于 migrate-jest-executor-setup-file.ts其主流程可以概括为三个步骤收集基线第一轮遍历使用forEachExecutorOptions扫描所有使用nx/jest:jestexecutor 的目标快照各目标基线的setupFile值供后续配置configuration继承判断使用。逐目标迁移第二轮遍历每个目标若其options.setupFile存在则解析出实际使用的 Jest 配置文件路径将 setup 文件路径以rootDir/...形式写入该配置的setupFilesAfterEnv数组随后从project.json的目标options或对应 configuration中删除setupFile。清理工作区默认值从nx.json的targetDefaults中删除setupFile并格式化所有改动过的文件。值得强调的是setupFile路径并不是简单照抄进 Jest 配置而是经过两步转换路径展开如果配置中使用{projectRoot}/{workspaceRoot}之类的 token会通过interpolate展开为工作区根目录下的真实相对路径对应源码中的expandWorkspaceRelativePathrootDir 相对化根据 Jest 配置中声明的rootDir未声明时取配置文件的目录计算相对路径统一写成rootDir/...形式对应源码中的toRootDirRelative。这一点至关重要因为rootDir是 Jest 官方语义中相对路径的锚点。典型迁移场景Before / After场景一无既有setupFilesAfterEnv直接写入这是最常见的情况project.json中声明了setupFile而 Jest 配置没有setupFilesAfterEnv。迁移后选项从project.json删除Jest 配置新增数组迁移前—apps/myapp/project.json{ targets: { test: { executor: nx/jest:jest, options: { jestConfig: apps/myapp/jest.config.ts, setupFile: apps/myapp/src/test-setup.ts } } } }迁移前—apps/myapp/jest.config.tsexport default { displayName: myapp, };迁移后—apps/myapp/project.json{ targets: { test: { executor: nx/jest:jest, options: { jestConfig: apps/myapp/jest.config.ts } } } }迁移后—apps/myapp/jest.config.tsexport default { displayName: myapp, setupFilesAfterEnv: [rootDir/src/test-setup.ts], };场景二已有setupFilesAfterEnv向后追加如果 Jest 配置里已经存在setupFilesAfterEnv数组迁移会追加新路径而不是覆盖迁移前—apps/myapp/project.json{ targets: { test: { executor: nx/jest:jest, options: { jestConfig: apps/myapp/jest.config.ts, setupFile: apps/myapp/src/test-setup.ts } } } }迁移前—apps/myapp/jest.config.tsexport default { displayName: myapp, setupFilesAfterEnv: [rootDir/src/existing-setup.ts], };迁移后—apps/myapp/project.json{ targets: { test: { executor: nx/jest:jest, options: { jestConfig: apps/myapp/jest.config.ts } } } }迁移后—apps/myapp/jest.config.tsexport default { displayName: myapp, setupFilesAfterEnv: [ rootDir/src/existing-setup.ts, rootDir/src/test-setup.ts, ], };迁移实现会保留原有数组的元素顺序与逗号风格只在末尾追加新条目如果新路径与既有条目解析后指向同一文件则跳过追加详见下文去重与幂等。场景三从nx.json的 target defaults 中移除setupFile也常被放在nx.json的targetDefaults中作为工作区级默认值。迁移会将其一并删除并输出警告提示手动处理。迁移前—nx.json按目标名test声明默认值{ targetDefaults: { test: { executor: nx/jest:jest, options: { jestConfig: {projectRoot}/jest.config.ts, setupFile: {projectRoot}/src/test-setup.ts } } } }迁移后—nx.json{ targetDefaults: { test: { executor: nx/jest:jest, options: { jestConfig: {projectRoot}/jest.config.ts } } } }迁移前—nx.json按 executornx/jest:jest声明默认值{ targetDefaults: { nx/jest:jest: { options: { jestConfig: {projectRoot}/jest.config.ts, setupFile: {projectRoot}/src/test-setup.ts } } } }迁移后—nx.json{ targetDefaults: { nx/jest:jest: { options: { jestConfig: {projectRoot}/jest.config.ts } } } }关于nx.json需要特别说明两点逐项目路径不适合作为工作区默认值所以该选项会直接从nx.json删除而不是被展开保留继承该默认值的目标不会丢失 setup 文件迁移会先对每个继承目标执行migrateInheritedSetupFile把继承到的路径展开成项目实际路径后写入各自项目的 Jest 配置行为等同于目标自己声明了该选项对应源码 migrateInheritedSetupFile。最后还会记录一条日志提示你nx.json中的setupFile默认值已被移除如依赖该默认值需要把路径补到各项目的 Jest 配置中。源码级原理迁移是如何安全改写 Jest 配置的表面看这只是删一个选项、加一个数组但实现上它是一套基于 TypeScript AST 的精确改写核心函数是pushSetupFileIntoJestConfigmigrate-jest-executor-setup-file.ts。理解它有助于你预判哪些配置能自动迁移、哪些不能。从 TS 源码中解析配置对象Jest 配置通常是export default { ... }TypeScript或module.exports { ... }JavaScript形式。迁移借助jestConfigObjectAst定义于 functions.ts把配置内容解析为 TypeScript 的ObjectLiteralExpression语法树从而在不执行配置代码的前提下安全定位、读取和改写属性。这也意味着如果配置不是静态对象字面量例如导出工厂函数export default async () ({...})解析就会失败。处理rootDir路径是算出来的不是拼出来的rootDir/...中的 rootDir 取决于 Jest 配置默认是配置文件所在目录也可由rootDir属性覆盖。迁移通过computeEffectiveRootDir读取配置对象中的rootDir节点未声明以配置文件所在目录为 rootDir这与 Jest 的默认语义一致字面量字符串如../../将其与配置文件目录做posix.join归一化后作为有效 rootDir再计算 setup 文件相对它的路径非字面量如rootDir: resolve(__dirname, ..)或path.join(...)无法在静态分析阶段确定值迁移放弃改写 Jest 配置仅删除废弃选项并告警custom-root-dir-non-literal分支。测试 migrate-jest-executor-setup-file.spec.ts 验证了字面量rootDir: ../../场景下路径会被正确换算为rootDir/apps/app1/src/test-setup.tsrootDir 指向工作区根目录而当配置不在项目根目录如apps/app1/config/jest.config.ts时换算结果会是rootDir/../src/test-setup.ts。处理既有数组与对象展开spread改写时需处理三类情况已有setupFilesAfterEnv数组在原数组内追加条目保留原格式若属性名带引号setupFilesAfterEnv同样能识别并原地追加见 spec 用例。配置中有对象展开如...nxPreset且无显式数组迁移会生成setupFilesAfterEnv: [...((nxPreset) as any)?.setupFilesAfterEnv ?? [], rootDir/src/test-setup.ts]形式的代码把 spread 源中可能存在的数组接续进新数组避免运行时被 spread 覆盖或丢失既有条目。显式数组之后还有 spread由于 spread 在运行时后写覆盖last-wins追加的条目会被 spread 覆盖迁移无法保证正确性此时放弃改写并告警返回unparseable保留 Jest 配置原样。多个 spread 的场景下迁移会按对象展开的 last-wins 语义用空值合并运算符??把多个 spread 源按后者优先的顺序串联对应源码pushSetupFileIntoJestConfig中spreadExpressions.length 1的分支测试见 spec 用例。去重与幂等追加前迁移会把数组中已有条目的多种写法rootDir/...、./...、../...、绝对路径统一解析为工作区根目录相对路径进行比较如果 setup 文件已经存在则返回already-present不会产生重复条目。这一机制同时保证了迁移的幂等性——重复运行不会重复追加测试见 spec 用例 与 ./ 形式去重用例。多目标共享配置与配置级configuration声明Jest 配置文件是按路径登记的rewrittenJestConfigs记录每个已改写的配置路径及其写入的 setup 文件。因此多个目标共享同一个 Jest 配置、但 setup 文件不同第一个目标写入成功后后续目标会发现该配置已被不同 setup 文件改写触发sharedConfigConflict告警不再写入——因为一份共享配置无法同时表达多个目标的私有 setup 文件需要每个目标各自独立的 Jest 配置或手动合并 setup 文件configuration 覆盖jestConfig且继承基线的 setupFile迁移会把继承的 setup 文件分别写入每个配置各自的 Jest 配置确保nx test app -c ci等带配置的调用在选项删除后仍能加载 setup 文件migrateInheritingConfigurations测试见 spec 用例configuration 同时覆盖jestConfig与setupFile两份 setup 文件各归其位互不泄漏测试见 spec 用例setup 文件仅声明在某个 configuration 下基线没有无法在不泄漏到基线运行的前提下写入共享 Jest 配置因此选项被删除但不迁移触发configurationOnly告警。无法自动迁移时的处理仍会删除选项并告警官方文档明确了一个安全底线无论能否自动迁移废弃的setupFile选项都会被删除因为在目标运行时它已不再生效区别只在于 setup 文件是否被写入了 Jest 配置。如果无法自动迁移迁移会收集受影响的目标并输出警告提示你手动把 setup 文件路径加入setupFilesAfterEnv。结合实现源码buildFollowUp以下情况会触发警告可按警告类别对号入座警告类别触发条件手动修复建议unparseableJest 配置无法被解析工厂函数、非静态对象字面量等手动把 setup 文件路径加入该配置的setupFilesAfterEnvcustom-root-dir-non-literalrootDir是非字面量值函数调用、导入变量以实际rootDir为基准手动写入正确的rootDir相对路径sharedConfigConflict多个目标共享同一 Jest 配置但 setup 文件不同为每个目标拆分独立的 Jest 配置或在共享配置中手动合并 setup 文件passthroughCollision同一作用域同时存在setupFile与setupFilesAfterEnv透传选项迁移前后两者优先级反转请手动合并到setupFilesAfterEnv目标 options 或 Jest 配置二选一configurationOnlysetup 文件仅声明在某个 configuration 下或值与基线不同写入配置专属的 Jest 配置或用process.env.NX_TASK_TARGET_CONFIGURATION做条件守卫noResolvableJestConfig目标有setupFile却解析不到任何jestConfig把路径补到该目标实际使用的 Jest 配置的setupFilesAfterEnvnx.json默认值提示从nx.jsontarget defaults 删除了setupFile将路径补到每个依赖该默认值的项目的 Jest 配置其中passthroughCollision是迁移前后行为差异最大的场景迁移前 executor 会用setupFile静默覆盖setupFilesAfterEnv透传值迁移后setupFilesAfterEnv透传优先可能与旧行为不同务必手动合并避免测试初始化逻辑意外变化。迁移的可信度23 个测试用例背书该迁移的实现伴随完整的单元测试 migrate-jest-executor-setup-file.spec.ts覆盖了module.exports与export default两种配置写法、已有数组追加、引号属性、字面量/非字面量rootDir、配置目录不在项目根目录、spread 单/多源 last-wins 语义、共享配置冲突、configuration 覆盖与继承、nx.jsontarget defaults 的对象形式与过滤数组形式targetDefaults中带filter的数组条目会逐条清理清空的条目被删除无关 executor 的条目保持不动、未声明setupFile的项目完全不受影响等边界情况。这些用例既验证了迁移的正确性也可以当作你评估我的工作区升级后会发生什么的参考清单。小结与升级建议一句话总结这条迁移Nx 23 把 setup 文件的声明位置从 executor 选项project.json/nx.json收敛到 Jest 原生配置setupFilesAfterEnv迁移会自动完成路径换算、数组追加、去重与默认值清理并对所有无法安全自动化的场景给出明确的警告与手动修复指引。升级前建议对照本文的警告类别清单提前检查工作区中是否存在共享 Jest 配置、configuration 级setupFile、setupFilesAfterEnv透传并存、非字面量rootDir等高风险模式升级后留意迁移输出的警告逐一确认 setup 文件已落入正确的setupFilesAfterEnv即可保证测试初始化行为与升级前一致。若需要深入了解迁移的完整实现与测试细节可继续阅读 迁移实现 与其单元测试。【免费下载链接】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），仅供参考 Nx 23 迁移指南：将 `@nx/jest:jest` 的 `setupFile` 选项迁移至 `setupFilesAfterEnv`
Nx 23 迁移指南将nx/jest:jest的setupFile选项迁移至setupFilesAfterEnv【免费下载链接】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 及更高版本、仍依赖nx/jest:jestexecutor 中已废弃的setupFile选项的开发者。文章以官方迁移文档为主体结合 Nx 仓库中的迁移实现源码与完整测试用例系统讲解该自动化迁移的执行逻辑、支持与不支持的场景、nx.json目标默认值的处理方式以及迁移后可能触发警告时的手动修复方案。读完本文你将能够准确预判npx nx migrate在升级过程中会对你的 Jest 配置做什么、为什么这么做以及迁移失败时如何安全地补齐配置。迁移背景为什么废弃setupFile选项在 Nx 23 之前nx/jest:jestexecutor 支持一个名为setupFile的选项用来为每个项目的 Jest 测试指定初始化文件例如 Angular 项目中的test-setup.ts。这一选项在项目配置project.json与工作区默认配置nx.json的targetDefaults中声明由 executor 在运行时把路径注入到 Jest 的配置对象中。问题在于Jest 本身已经提供了标准的setupFilesAfterEnv配置项用来声明在每个测试文件所在的测试套件运行之前执行的初始化模块列表。executor 层再维护一份setupFile既与 Jest 原生机制重复又给配置解析、缓存和推断带来额外负担。因此Nx 23 将setupFile标记为废弃并提供了一条自动化迁移路径把 setup 文件路径追加到项目 Jest 配置的setupFilesAfterEnv数组中同时从project.json与nx.json的 target defaults 中删除废弃的setupFile选项。该迁移在 migrations.json 中注册版本号为23.0.0-beta.22描述为把nx/jest:jestexecutor 废弃的setupFile选项迁移到项目 Jest 配置中的setupFilesAfterEnv并从project.json和nx.jsontarget defaults 中移除该选项。升级时 Nx 会自动执行它无需手动干预。迁移的核心行为迁移逻辑的入口位于 migrate-jest-executor-setup-file.ts其主流程可以概括为三个步骤收集基线第一轮遍历使用forEachExecutorOptions扫描所有使用nx/jest:jestexecutor 的目标快照各目标基线的setupFile值供后续配置configuration继承判断使用。逐目标迁移第二轮遍历每个目标若其options.setupFile存在则解析出实际使用的 Jest 配置文件路径将 setup 文件路径以rootDir/...形式写入该配置的setupFilesAfterEnv数组随后从project.json的目标options或对应 configuration中删除setupFile。清理工作区默认值从nx.json的targetDefaults中删除setupFile并格式化所有改动过的文件。值得强调的是setupFile路径并不是简单照抄进 Jest 配置而是经过两步转换路径展开如果配置中使用{projectRoot}/{workspaceRoot}之类的 token会通过interpolate展开为工作区根目录下的真实相对路径对应源码中的expandWorkspaceRelativePathrootDir 相对化根据 Jest 配置中声明的rootDir未声明时取配置文件的目录计算相对路径统一写成rootDir/...形式对应源码中的toRootDirRelative。这一点至关重要因为rootDir是 Jest 官方语义中相对路径的锚点。典型迁移场景Before / After场景一无既有setupFilesAfterEnv直接写入这是最常见的情况project.json中声明了setupFile而 Jest 配置没有setupFilesAfterEnv。迁移后选项从project.json删除Jest 配置新增数组迁移前—apps/myapp/project.json{ targets: { test: { executor: nx/jest:jest, options: { jestConfig: apps/myapp/jest.config.ts, setupFile: apps/myapp/src/test-setup.ts } } } }迁移前—apps/myapp/jest.config.tsexport default { displayName: myapp, };迁移后—apps/myapp/project.json{ targets: { test: { executor: nx/jest:jest, options: { jestConfig: apps/myapp/jest.config.ts } } } }迁移后—apps/myapp/jest.config.tsexport default { displayName: myapp, setupFilesAfterEnv: [rootDir/src/test-setup.ts], };场景二已有setupFilesAfterEnv向后追加如果 Jest 配置里已经存在setupFilesAfterEnv数组迁移会追加新路径而不是覆盖迁移前—apps/myapp/project.json{ targets: { test: { executor: nx/jest:jest, options: { jestConfig: apps/myapp/jest.config.ts, setupFile: apps/myapp/src/test-setup.ts } } } }迁移前—apps/myapp/jest.config.tsexport default { displayName: myapp, setupFilesAfterEnv: [rootDir/src/existing-setup.ts], };迁移后—apps/myapp/project.json{ targets: { test: { executor: nx/jest:jest, options: { jestConfig: apps/myapp/jest.config.ts } } } }迁移后—apps/myapp/jest.config.tsexport default { displayName: myapp, setupFilesAfterEnv: [ rootDir/src/existing-setup.ts, rootDir/src/test-setup.ts, ], };迁移实现会保留原有数组的元素顺序与逗号风格只在末尾追加新条目如果新路径与既有条目解析后指向同一文件则跳过追加详见下文去重与幂等。场景三从nx.json的 target defaults 中移除setupFile也常被放在nx.json的targetDefaults中作为工作区级默认值。迁移会将其一并删除并输出警告提示手动处理。迁移前—nx.json按目标名test声明默认值{ targetDefaults: { test: { executor: nx/jest:jest, options: { jestConfig: {projectRoot}/jest.config.ts, setupFile: {projectRoot}/src/test-setup.ts } } } }迁移后—nx.json{ targetDefaults: { test: { executor: nx/jest:jest, options: { jestConfig: {projectRoot}/jest.config.ts } } } }迁移前—nx.json按 executornx/jest:jest声明默认值{ targetDefaults: { nx/jest:jest: { options: { jestConfig: {projectRoot}/jest.config.ts, setupFile: {projectRoot}/src/test-setup.ts } } } }迁移后—nx.json{ targetDefaults: { nx/jest:jest: { options: { jestConfig: {projectRoot}/jest.config.ts } } } }关于nx.json需要特别说明两点逐项目路径不适合作为工作区默认值所以该选项会直接从nx.json删除而不是被展开保留继承该默认值的目标不会丢失 setup 文件迁移会先对每个继承目标执行migrateInheritedSetupFile把继承到的路径展开成项目实际路径后写入各自项目的 Jest 配置行为等同于目标自己声明了该选项对应源码 migrateInheritedSetupFile。最后还会记录一条日志提示你nx.json中的setupFile默认值已被移除如依赖该默认值需要把路径补到各项目的 Jest 配置中。源码级原理迁移是如何安全改写 Jest 配置的表面看这只是删一个选项、加一个数组但实现上它是一套基于 TypeScript AST 的精确改写核心函数是pushSetupFileIntoJestConfigmigrate-jest-executor-setup-file.ts。理解它有助于你预判哪些配置能自动迁移、哪些不能。从 TS 源码中解析配置对象Jest 配置通常是export default { ... }TypeScript或module.exports { ... }JavaScript形式。迁移借助jestConfigObjectAst定义于 functions.ts把配置内容解析为 TypeScript 的ObjectLiteralExpression语法树从而在不执行配置代码的前提下安全定位、读取和改写属性。这也意味着如果配置不是静态对象字面量例如导出工厂函数export default async () ({...})解析就会失败。处理rootDir路径是算出来的不是拼出来的rootDir/...中的 rootDir 取决于 Jest 配置默认是配置文件所在目录也可由rootDir属性覆盖。迁移通过computeEffectiveRootDir读取配置对象中的rootDir节点未声明以配置文件所在目录为 rootDir这与 Jest 的默认语义一致字面量字符串如../../将其与配置文件目录做posix.join归一化后作为有效 rootDir再计算 setup 文件相对它的路径非字面量如rootDir: resolve(__dirname, ..)或path.join(...)无法在静态分析阶段确定值迁移放弃改写 Jest 配置仅删除废弃选项并告警custom-root-dir-non-literal分支。测试 migrate-jest-executor-setup-file.spec.ts 验证了字面量rootDir: ../../场景下路径会被正确换算为rootDir/apps/app1/src/test-setup.tsrootDir 指向工作区根目录而当配置不在项目根目录如apps/app1/config/jest.config.ts时换算结果会是rootDir/../src/test-setup.ts。处理既有数组与对象展开spread改写时需处理三类情况已有setupFilesAfterEnv数组在原数组内追加条目保留原格式若属性名带引号setupFilesAfterEnv同样能识别并原地追加见 spec 用例。配置中有对象展开如...nxPreset且无显式数组迁移会生成setupFilesAfterEnv: [...((nxPreset) as any)?.setupFilesAfterEnv ?? [], rootDir/src/test-setup.ts]形式的代码把 spread 源中可能存在的数组接续进新数组避免运行时被 spread 覆盖或丢失既有条目。显式数组之后还有 spread由于 spread 在运行时后写覆盖last-wins追加的条目会被 spread 覆盖迁移无法保证正确性此时放弃改写并告警返回unparseable保留 Jest 配置原样。多个 spread 的场景下迁移会按对象展开的 last-wins 语义用空值合并运算符??把多个 spread 源按后者优先的顺序串联对应源码pushSetupFileIntoJestConfig中spreadExpressions.length 1的分支测试见 spec 用例。去重与幂等追加前迁移会把数组中已有条目的多种写法rootDir/...、./...、../...、绝对路径统一解析为工作区根目录相对路径进行比较如果 setup 文件已经存在则返回already-present不会产生重复条目。这一机制同时保证了迁移的幂等性——重复运行不会重复追加测试见 spec 用例 与 ./ 形式去重用例。多目标共享配置与配置级configuration声明Jest 配置文件是按路径登记的rewrittenJestConfigs记录每个已改写的配置路径及其写入的 setup 文件。因此多个目标共享同一个 Jest 配置、但 setup 文件不同第一个目标写入成功后后续目标会发现该配置已被不同 setup 文件改写触发sharedConfigConflict告警不再写入——因为一份共享配置无法同时表达多个目标的私有 setup 文件需要每个目标各自独立的 Jest 配置或手动合并 setup 文件configuration 覆盖jestConfig且继承基线的 setupFile迁移会把继承的 setup 文件分别写入每个配置各自的 Jest 配置确保nx test app -c ci等带配置的调用在选项删除后仍能加载 setup 文件migrateInheritingConfigurations测试见 spec 用例configuration 同时覆盖jestConfig与setupFile两份 setup 文件各归其位互不泄漏测试见 spec 用例setup 文件仅声明在某个 configuration 下基线没有无法在不泄漏到基线运行的前提下写入共享 Jest 配置因此选项被删除但不迁移触发configurationOnly告警。无法自动迁移时的处理仍会删除选项并告警官方文档明确了一个安全底线无论能否自动迁移废弃的setupFile选项都会被删除因为在目标运行时它已不再生效区别只在于 setup 文件是否被写入了 Jest 配置。如果无法自动迁移迁移会收集受影响的目标并输出警告提示你手动把 setup 文件路径加入setupFilesAfterEnv。结合实现源码buildFollowUp以下情况会触发警告可按警告类别对号入座警告类别触发条件手动修复建议unparseableJest 配置无法被解析工厂函数、非静态对象字面量等手动把 setup 文件路径加入该配置的setupFilesAfterEnvcustom-root-dir-non-literalrootDir是非字面量值函数调用、导入变量以实际rootDir为基准手动写入正确的rootDir相对路径sharedConfigConflict多个目标共享同一 Jest 配置但 setup 文件不同为每个目标拆分独立的 Jest 配置或在共享配置中手动合并 setup 文件passthroughCollision同一作用域同时存在setupFile与setupFilesAfterEnv透传选项迁移前后两者优先级反转请手动合并到setupFilesAfterEnv目标 options 或 Jest 配置二选一configurationOnlysetup 文件仅声明在某个 configuration 下或值与基线不同写入配置专属的 Jest 配置或用process.env.NX_TASK_TARGET_CONFIGURATION做条件守卫noResolvableJestConfig目标有setupFile却解析不到任何jestConfig把路径补到该目标实际使用的 Jest 配置的setupFilesAfterEnvnx.json默认值提示从nx.jsontarget defaults 删除了setupFile将路径补到每个依赖该默认值的项目的 Jest 配置其中passthroughCollision是迁移前后行为差异最大的场景迁移前 executor 会用setupFile静默覆盖setupFilesAfterEnv透传值迁移后setupFilesAfterEnv透传优先可能与旧行为不同务必手动合并避免测试初始化逻辑意外变化。迁移的可信度23 个测试用例背书该迁移的实现伴随完整的单元测试 migrate-jest-executor-setup-file.spec.ts覆盖了module.exports与export default两种配置写法、已有数组追加、引号属性、字面量/非字面量rootDir、配置目录不在项目根目录、spread 单/多源 last-wins 语义、共享配置冲突、configuration 覆盖与继承、nx.jsontarget defaults 的对象形式与过滤数组形式targetDefaults中带filter的数组条目会逐条清理清空的条目被删除无关 executor 的条目保持不动、未声明setupFile的项目完全不受影响等边界情况。这些用例既验证了迁移的正确性也可以当作你评估我的工作区升级后会发生什么的参考清单。小结与升级建议一句话总结这条迁移Nx 23 把 setup 文件的声明位置从 executor 选项project.json/nx.json收敛到 Jest 原生配置setupFilesAfterEnv迁移会自动完成路径换算、数组追加、去重与默认值清理并对所有无法安全自动化的场景给出明确的警告与手动修复指引。升级前建议对照本文的警告类别清单提前检查工作区中是否存在共享 Jest 配置、configuration 级setupFile、setupFilesAfterEnv透传并存、非字面量rootDir等高风险模式升级后留意迁移输出的警告逐一确认 setup 文件已落入正确的setupFilesAfterEnv即可保证测试初始化行为与升级前一致。若需要深入了解迁移的完整实现与测试细节可继续阅读 迁移实现 与其单元测试。【免费下载链接】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），仅供参考