尧图网页设计 
Nx 21 迁移指南nx/gradle 插件选项 ciTargetName 更名为 ciTestTargetName【免费下载链接】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 21 中nx/gradle插件的 CI 原子化测试目标Atomized CI Test Targets配置选项由ciTargetName更名为ciTestTargetName。本文以 迁移说明文档 为核心完整讲解该迁移的触发版本、手动改法、自动迁移机制并结合nx.json、TypeScript 迁移实现、Kotlin 端插件实现与单元测试帮助你在升级 Nx 21 时准确完成配置收敛理解新选项在底层如何生成ci--TestClassName系列 CI 目标。迁移背景选项改名语义更精确在旧版nx/gradle即nx/gradle/plugin-v1中ciTargetName被用来为 Gradle 的test任务批量生成原子化的 CI 测试目标。例如配置值为ci时插件会按测试类生成形如ci--ExampleTest的多个独立 Nx 目标从而支持 Nx Cloud 的分片与失败重跑。在 Nx 21 中nx/gradle插件默认入口迁移到基于 Kotlin Gradle 插件的 v2 实现dev.nx.gradle.project-graph其选项读取、目标生成逻辑全部由 Kotlin 侧完成。此时原ciTargetName选项被统一更名为ciTestTargetName语义上明确为「CI 测试目标名前缀」避免与ciCheckTargetName、ciBuildTargetName等其他 CI 系列选项混淆。该更名由 Nx 的自动迁移migration机制在升级时完成注册版本为21.0.0-beta.13见 packages/gradle/migrations.json。迁移后的配置变化原迁移文档给出了最核心的配置对比。以下为迁移前Before{ plugins: [ plugin: nx/gradle, options: { ciTargetName: ci } ] }迁移后After插件对象内的ciTargetName键被重命名为ciTestTargetName值保持不变{ plugins: [ plugin: nx/gradle, options: { ciTestTargetName: ci } ] }需要注意迁移只针对以对象形式带options声明的nx/gradle插件条目若plugins中仅以字符串形式声明nx/gradle未配置任何选项则不需要也不应该做任何改动若声明的是nx/gradle/plugin-v1迁移同样不会触碰旧版入口的兼容选项在 v1 实现中仍然保留。自动迁移升级时由 Nx 完成该迁移由 Nx 的版本升级机制触发无需手工执行。迁移实现位于 packages/gradle/src/migrations/21-0-0/change-ciTargetName-to-ciTestTargetName.ts在migrations.json中注册为版本21.0.0-beta.13的生成器generator声明为Change nx/gradle option from ciTargetName to ciTestTargetName。其执行流程可以概括为四个守卫 一步改写读取nx.json调用readNxJson(tree)若文件不存在则直接返回检查插件存在性调用 packages/gradle/src/utils/has-gradle-plugin.ts 中的hasGradlePlugin只有nx.json的plugins中存在nx/gradle字符串形式或对象形式才会继续定位插件条目findIndex匹配p.plugin nx/gradle并确认该条目是带options的对象读取旧选项从gradlePlugin.options中取出ciTargetName改写先delete掉ciTargetName键再写入同值的ciTestTargetName最后updateNxJson(tree, nxJson)落盘。从源码结构看该迁移采用了「无选项则不改、非目标插件不动」的保守策略只有确实配置了ciTargetName且使用nx/gradle默认入口的工作区才会被改写避免对其他插件的plugins配置造成误伤。迁移测试覆盖的行为边界配套的单测 packages/gradle/src/migrations/21-0-0/change-ciTargetName-to-ciTestTargetName.spec.ts 用五个用例明确了迁移的行为边界可作为你升级后校验工作区状态的行为清单场景输入nx.json迁移结果未配置nx/gradle插件{ namedInputs: {} }保持不变字符串形式声明插件、无 options{ plugins: [nx/gradle] }保持不变使用 v1 入口{ plugins: [nx/gradle/plugin-v1] }保持不变对象形式但未配置ciTargetName{ plugin: nx/gradle, options: { testTargetName: test } }testTargetName原样保留配置了ciTargetName{ plugin: nx/gradle, options: { ciTargetName: test } }更名为ciTestTargetName: test新选项 ciTestTargetName 在插件中的实际作用改名后的选项在nx/gradlev2 实现Kotlin Gradle 插件dev.nx.gradle.project-graph中被真正消费用于生成原子化 CI 测试目标。选项读取与生效条件在 packages/gradle/project-graph/src/main/kotlin/dev/nx/gradle/utils/ProjectUtils.kt 中插件从targetNameOverrides[ciTestTargetName]读取前缀并判断val ciTestTargetBaseName targetNameOverrides[ciTestTargetName]?.let { applyPrefix(it) } val testTargetName applyPrefix(targetNameOverrides.getOrDefault(testTargetName, test)) val hasCiTestTarget ciTestTargetBaseName ! null testTasks.isNotEmpty() atomized即只有当ciTestTargetName已配置、项目存在Test类型任务且启用了原子化atomized模式时才会生成 CI 测试目标。日志中也会输出ciTestTargetName的解析结果便于排障。目标命名规则在 packages/gradle/project-graph/src/main/kotlin/dev/nx/gradle/utils/CiTargetsUtils.kt 的processTestFiles中插件遍历测试源文件解析出每个测试类名然后生成形如以下命名的 Nx 目标ciTestTargetName--TestClassName例如ciTestTargetName: ci时会产生ci--AppTest、ci--UserServiceTest等目标每个目标对应 Gradle 命令test --tests TestClassName的封装v2 实现中测试任务名同样支持testTargetName覆盖。同时这些原子化目标会被收集到对应的 target group并由一个父级 CI 目标ensureParentCiTarget通过dependsOn串联实现「一条命令触发全部原子测试、按类分片并行」的效果。如果项目存在多个非默认名称的测试任务如test之外的集成测试任务ProjectUtils.kt中还会生成ciTestTargetName-taskName形式的目标名避免命名冲突。手动迁移步骤适用于无法自动升级的场景若因版本管理方式无法走 Nx 自动迁移可按下述步骤手工迁移打开工作区根目录下的nx.json定位plugins数组中的nx/gradle条目若该条目是对象且options中存在ciTargetName将键名改为ciTestTargetName值保持不变检查所有 CI 工作流配置如.github/workflows/ci.yml或nx.json中的 targetDefaults中引用的原子化目标名确保它们基于新前缀生成运行npx nx show projects --with-target ci或直接运行npx nx run-many --targetci --dry-run验证目标是否正常生成与识别。新旧实现并存关于 plugin-v1 的说明在 packages/gradle/src/plugin-v1/nodes.ts 中v1 的GradlePluginOptions接口仍保留ciTargetName字段其getTestCiTargets逻辑见 nodes.ts会生成ciTargetName -- testName形式的目标。该入口在源码注释中被明确标记为已弃用deprecated计划在 Nx 24 移除因此仍在使用nx/gradle/plugin-v1的旧工作区本次迁移不会修改其配置升级到nx/gradle默认入口v2的工作区请务必使用ciTestTargetName建议将目标前缀统一为ci保持原值即可无需因为改名而改动 CI 脚本中依赖的目标名语义。小结本次ciTargetName→ciTestTargetName的更名是nx/gradle插件向 v2 Kotlin 实现迁移的一部分选项语义更精确读取与目标生成逻辑全部下沉到 Kotlin 侧CiTargetsUtils.kt、ProjectUtils.kt并由注册于21.0.0-beta.13的自动迁移在升级时安全改写nx.json。迁移行为对「非目标插件、字符串声明、无该选项」的场景零侵入其边界由 spec 测试 完整锁定。升级后只需确认nx.json中的键名已更新并通过ci目标族验证原子化测试仍按类正常分片即可无缝衔接 Nx 21 的 Gradle CI 能力。【免费下载链接】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 21 迁移指南：@nx/gradle 插件选项 ciTargetName 更名为 ciTestTargetName
Nx 21 迁移指南nx/gradle 插件选项 ciTargetName 更名为 ciTestTargetName【免费下载链接】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 21 中nx/gradle插件的 CI 原子化测试目标Atomized CI Test Targets配置选项由ciTargetName更名为ciTestTargetName。本文以 迁移说明文档 为核心完整讲解该迁移的触发版本、手动改法、自动迁移机制并结合nx.json、TypeScript 迁移实现、Kotlin 端插件实现与单元测试帮助你在升级 Nx 21 时准确完成配置收敛理解新选项在底层如何生成ci--TestClassName系列 CI 目标。迁移背景选项改名语义更精确在旧版nx/gradle即nx/gradle/plugin-v1中ciTargetName被用来为 Gradle 的test任务批量生成原子化的 CI 测试目标。例如配置值为ci时插件会按测试类生成形如ci--ExampleTest的多个独立 Nx 目标从而支持 Nx Cloud 的分片与失败重跑。在 Nx 21 中nx/gradle插件默认入口迁移到基于 Kotlin Gradle 插件的 v2 实现dev.nx.gradle.project-graph其选项读取、目标生成逻辑全部由 Kotlin 侧完成。此时原ciTargetName选项被统一更名为ciTestTargetName语义上明确为「CI 测试目标名前缀」避免与ciCheckTargetName、ciBuildTargetName等其他 CI 系列选项混淆。该更名由 Nx 的自动迁移migration机制在升级时完成注册版本为21.0.0-beta.13见 packages/gradle/migrations.json。迁移后的配置变化原迁移文档给出了最核心的配置对比。以下为迁移前Before{ plugins: [ plugin: nx/gradle, options: { ciTargetName: ci } ] }迁移后After插件对象内的ciTargetName键被重命名为ciTestTargetName值保持不变{ plugins: [ plugin: nx/gradle, options: { ciTestTargetName: ci } ] }需要注意迁移只针对以对象形式带options声明的nx/gradle插件条目若plugins中仅以字符串形式声明nx/gradle未配置任何选项则不需要也不应该做任何改动若声明的是nx/gradle/plugin-v1迁移同样不会触碰旧版入口的兼容选项在 v1 实现中仍然保留。自动迁移升级时由 Nx 完成该迁移由 Nx 的版本升级机制触发无需手工执行。迁移实现位于 packages/gradle/src/migrations/21-0-0/change-ciTargetName-to-ciTestTargetName.ts在migrations.json中注册为版本21.0.0-beta.13的生成器generator声明为Change nx/gradle option from ciTargetName to ciTestTargetName。其执行流程可以概括为四个守卫 一步改写读取nx.json调用readNxJson(tree)若文件不存在则直接返回检查插件存在性调用 packages/gradle/src/utils/has-gradle-plugin.ts 中的hasGradlePlugin只有nx.json的plugins中存在nx/gradle字符串形式或对象形式才会继续定位插件条目findIndex匹配p.plugin nx/gradle并确认该条目是带options的对象读取旧选项从gradlePlugin.options中取出ciTargetName改写先delete掉ciTargetName键再写入同值的ciTestTargetName最后updateNxJson(tree, nxJson)落盘。从源码结构看该迁移采用了「无选项则不改、非目标插件不动」的保守策略只有确实配置了ciTargetName且使用nx/gradle默认入口的工作区才会被改写避免对其他插件的plugins配置造成误伤。迁移测试覆盖的行为边界配套的单测 packages/gradle/src/migrations/21-0-0/change-ciTargetName-to-ciTestTargetName.spec.ts 用五个用例明确了迁移的行为边界可作为你升级后校验工作区状态的行为清单场景输入nx.json迁移结果未配置nx/gradle插件{ namedInputs: {} }保持不变字符串形式声明插件、无 options{ plugins: [nx/gradle] }保持不变使用 v1 入口{ plugins: [nx/gradle/plugin-v1] }保持不变对象形式但未配置ciTargetName{ plugin: nx/gradle, options: { testTargetName: test } }testTargetName原样保留配置了ciTargetName{ plugin: nx/gradle, options: { ciTargetName: test } }更名为ciTestTargetName: test新选项 ciTestTargetName 在插件中的实际作用改名后的选项在nx/gradlev2 实现Kotlin Gradle 插件dev.nx.gradle.project-graph中被真正消费用于生成原子化 CI 测试目标。选项读取与生效条件在 packages/gradle/project-graph/src/main/kotlin/dev/nx/gradle/utils/ProjectUtils.kt 中插件从targetNameOverrides[ciTestTargetName]读取前缀并判断val ciTestTargetBaseName targetNameOverrides[ciTestTargetName]?.let { applyPrefix(it) } val testTargetName applyPrefix(targetNameOverrides.getOrDefault(testTargetName, test)) val hasCiTestTarget ciTestTargetBaseName ! null testTasks.isNotEmpty() atomized即只有当ciTestTargetName已配置、项目存在Test类型任务且启用了原子化atomized模式时才会生成 CI 测试目标。日志中也会输出ciTestTargetName的解析结果便于排障。目标命名规则在 packages/gradle/project-graph/src/main/kotlin/dev/nx/gradle/utils/CiTargetsUtils.kt 的processTestFiles中插件遍历测试源文件解析出每个测试类名然后生成形如以下命名的 Nx 目标ciTestTargetName--TestClassName例如ciTestTargetName: ci时会产生ci--AppTest、ci--UserServiceTest等目标每个目标对应 Gradle 命令test --tests TestClassName的封装v2 实现中测试任务名同样支持testTargetName覆盖。同时这些原子化目标会被收集到对应的 target group并由一个父级 CI 目标ensureParentCiTarget通过dependsOn串联实现「一条命令触发全部原子测试、按类分片并行」的效果。如果项目存在多个非默认名称的测试任务如test之外的集成测试任务ProjectUtils.kt中还会生成ciTestTargetName-taskName形式的目标名避免命名冲突。手动迁移步骤适用于无法自动升级的场景若因版本管理方式无法走 Nx 自动迁移可按下述步骤手工迁移打开工作区根目录下的nx.json定位plugins数组中的nx/gradle条目若该条目是对象且options中存在ciTargetName将键名改为ciTestTargetName值保持不变检查所有 CI 工作流配置如.github/workflows/ci.yml或nx.json中的 targetDefaults中引用的原子化目标名确保它们基于新前缀生成运行npx nx show projects --with-target ci或直接运行npx nx run-many --targetci --dry-run验证目标是否正常生成与识别。新旧实现并存关于 plugin-v1 的说明在 packages/gradle/src/plugin-v1/nodes.ts 中v1 的GradlePluginOptions接口仍保留ciTargetName字段其getTestCiTargets逻辑见 nodes.ts会生成ciTargetName -- testName形式的目标。该入口在源码注释中被明确标记为已弃用deprecated计划在 Nx 24 移除因此仍在使用nx/gradle/plugin-v1的旧工作区本次迁移不会修改其配置升级到nx/gradle默认入口v2的工作区请务必使用ciTestTargetName建议将目标前缀统一为ci保持原值即可无需因为改名而改动 CI 脚本中依赖的目标名语义。小结本次ciTargetName→ciTestTargetName的更名是nx/gradle插件向 v2 Kotlin 实现迁移的一部分选项语义更精确读取与目标生成逻辑全部下沉到 Kotlin 侧CiTargetsUtils.kt、ProjectUtils.kt并由注册于21.0.0-beta.13的自动迁移在升级时安全改写nx.json。迁移行为对「非目标插件、字符串声明、无该选项」的场景零侵入其边界由 spec 测试 完整锁定。升级后只需确认nx.json中的键名已更新并通过ci目标族验证原子化测试仍按类正常分片即可无缝衔接 Nx 21 的 Gradle CI 能力。【免费下载链接】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），仅供参考