Nx 迁移实战自动升级 Gradle 插件 dev.nx.gradle.project-graph 至 0.1.10【免费下载链接】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/nxNx 的nx/gradle插件通过迁移机制自动维护build.gradle(.kts)中dev.nx.gradle.project-graph插件的版本。本文以仓库中 22-2-0 版本迁移说明 为骨架深入解析这条迁移在何时触发、改动了哪些文件、如何兼容 Groovy/Kotlin DSL 与 Gradle Version Catalog 的多种写法并结合源码实现与测试用例给出可复现的验证方式。读完你既能理解nx migrate背后的自动升级原理也能独立完成该插件版本的手动升级与校验。一、这条迁移解决什么问题dev.nx.gradle.project-graph是 Nx 为 Gradle 工作区提供的官方插件负责将 Gradle 的项目与任务信息导出为 JSON供 Nx 构建项目图谱Project Graph使用。其安装方式如下引自 插件 README// build.gradle (Groovy DSL) plugins { id dev.nx.gradle.project-graph version }// build.gradle.kts (Kotlin DSL) plugins { id(dev.nx.gradle.project-graph) version() }插件版本会随 Nx 版本演进迭代。当 Nx 升级到 22.2.0 时需要把工作区中该插件的版本统一提升到0.1.10以保证项目图谱生成逻辑与新版 Nx 兼容。这一升级正是由 change-plugin-version-0-1-10 迁移 自动完成的。在 migrations.json 中这条迁移被注册为change-plugin-version-0-1-10: { version: 22.2.0-beta.4, cli: nx, description: Change dev.nx.gradle.project-graph to version 0.1.10 in build file, factory: ./dist/src/migrations/22-2-0/change-plugin-version-0-1-10, documentation: ./dist/src/migrations/22-2-0/change-plugin-version-0-1-10.md }也就是说当工作区从旧版本 Nx 迁移到22.2.0-beta.4 及以上版本时这条迁移会被纳入执行队列。二、迁移前后的文件变化官方迁移说明 给出了最直观的变更示例——在build.gradle的plugins块中把插件版本号从0.1.0提升为0.1.10。迁移前Beforeplugins { id dev.nx.gradle.project-graph version 0.1.0 }迁移后Afterplugins { id dev.nx.gradle.project-graph version 0.1.10 }注意这里展示的是Groovy DSL的写法。实际上迁移对Kotlin DSL同样生效最终效果等价于// build.gradle.kts 迁移后 plugins { id(dev.nx.gradle.project-graph) version(0.1.10) }两种 DSL 的差异引号风格、id是否带括号、version是否带括号都由底层实现的正则与分支逻辑分别处理详见下文源码解析。三、迁移实现解析它到底改了什么迁移入口实现 的核心逻辑非常清晰分三步执行export default async function update(tree: Tree) { const nxJson readNxJson(tree); if (!nxJson) { return; // 1. 无 nx.json直接跳过 } if (!hasGradlePlugin(tree)) { return; // 2. 未启用 nx/gradle直接跳过 } const gradlePluginVersionToUpdate 0.1.10; // 3a. 用 AST 方式更新 Version Catalog保留原格式 await updateNxPluginVersionInCatalogsAst(tree, gradlePluginVersionToUpdate); // 3b. 更新 build.gradle(.kts) 文件 await addNxProjectGraphPlugin(tree, gradlePluginVersionToUpdate); }1. 守卫条件只在合理的场景下执行迁移不是无条件执行的它先通过两个守卫条件判断当前工作区是否需要升级必须存在nx.json这是 Nx 工作区的标志性配置文件缺失说明这不是一个可被 Nx 管理的仓库。必须启用了nx/gradle插件判断逻辑在 has-gradle-plugin.ts 中即检查nx.json的plugins数组里是否包含nx/gradle支持字符串写法或{ plugin: nx/gradle }对象写法export function hasGradlePlugin(tree: Tree): boolean { const nxJson readNxJson(tree); return !!nxJson.plugins?.some((p) typeof p string ? p nx/gradle : p.plugin nx/gradle ); }这两个条件缺一不可测试用例也明确验证了无 nx.json与未启用 Gradle 插件两种场景下迁移应保持文件不动见 change-plugin-version-0-1-10.spec.ts。2. 两条升级路径Version Catalog 优先build.gradle 兜底迁移的升级动作分为两条并行的路径updateNxPluginVersionInCatalogsAst扫描工作区中所有**/gradle/*.versions.toml文件用 TOML AST 解析并精准替换版本号addNxProjectGraphPlugin定位每个settings.gradle(.kts)旁边的build.gradle(.kts)更新其中直接声明的插件版本。之所以先更新 Version Catalog 再更新 build.gradle是因为后者的逻辑需要感知前者——如果插件是通过 Catalog 别名alias引入的build.gradle 中就不该再出现内联版本号也就不需要也不应该追加allprojects传播块。3. 保持格式的 Version Catalog 更新Version Cataloglibs.versions.toml是 Gradle 集中管理依赖与插件版本的机制格式化要求较高。为此迁移没有采用简单的文本替换而是使用toml-eslint-parser将 TOML 解析为 AST只对版本值所在的区间做精确替换再按原文本重建内容见 version-catalog-ast-utils.ts 的reconstructTomlWithUpdates。这样注释、缩进、引号风格等格式都能原样保留。该工具函数支持三种 Catalog 中声明插件的方式见 version-catalog-ast-utils.ts 的findPluginConfigCatalog 写法示例迁移结果简单格式插件ID:版本nx-graph dev.nx.gradle.project-graph:0.0.1nx-graph dev.nx.gradle.project-graph:0.1.10内联对象直接写版本nx-graph { id dev.nx.gradle.project-graph, version 0.0.1 }version 0.1.10引用版本version.ref[versions]中nx-project-graph 0.0.1[plugins]中version.ref nx-project-graph[versions]中对应条目更新为0.1.10对于version.ref引用写法迁移会顺着引用链找到[versions]表中的真实版本条目并更新它而不是去改version.ref本身。上述三种写法在 change-plugin-version-0-1-10.spec.ts 中都有对应的测试覆盖。4. build.gradle(.kts) 中的版本更新对于直接内联声明插件的build.gradle(.kts)更新逻辑位于 gradle-project-graph-plugin-utils.ts。其核心是一个兼容两种 DSL 的正则// 兼容 id plugin version x 与 id(plugin) version(x) const regex /(id\s*\(?[]dev\.nx\.gradle\.project-graph[]\)?\s*version\s*\(?[])([^])([]\)?)/;命中后直接执行content.replace(regex,$1${newVersion}$3)只替换中间版本号部分若未命中例如插件是通过 Catalog 别名引入的则打印Please update plugin dev.nx.gradle.project-graph to 0.1.10警告不破坏文件。值得一提的还有 addNxProjectGraphPluginToBuildGradle 的幂等处理如果build.gradle已存在plugins块就直接补充声明不存在则新建plugins块同时会把插件通过allprojects { apply ... }传播到所有子项目且重复执行不会追加重复声明。四、如何运行这条迁移迁移本身不要求手动编辑任何文件而是随 Nx 的标准升级流程执行在 Nx 工作区根目录运行nx migrate nx/gradlelatest或指定目标版本Nx 会依据 migrations.json 计算出从当前版本到目标版本之间需要执行的全部迁移生成迁移计划后运行nx migrate --run-migrations执行它们其中就包含change-plugin-version-0-1-10执行完成后检查build.gradle/build.gradle.kts以及各gradle/libs.versions.toml中dev.nx.gradle.project-graph的版本已变为0.1.10。如果你不想等待下一次升级流程也可以完全手动升级按本文第二节的 Before/After 示例修改插件版本号或编辑libs.versions.toml中对应的版本条目。五、迁移后的验证升级是否成功可从两个层面验证。1. 直接查看文件内容迁移的核心断言在测试中体现得十分明确以 Groovy DSL 测试 为例迁移后文件必须包含version 0.1.10且不包含旧版本0.0.1。对 Kotlin DSL、多模块多build.gradle、Catalog 与 build.gradle 同时存在等场景spec.ts 中均有对应的断言可作为你人工核对文件时的参照。2. 运行插件验证功能升级只是手段最终目的是让项目图谱功能正常工作。按 插件 README 的说明可在工作区执行./gradlew nxProjectGraph正常输出类似 Task :nxProjectGraph your workspace /build/nx/add-nx-to-gradle.json该命令会在build/nx/add-nx-to-gradle.json生成一份包含nodes、dependencies、externalNodes的 JSON供 Nx 消费构建项目图谱。如果迁移后该命令仍能正常产出 JSON说明 0.1.10 插件版本已生效且与当前 Nx 版本匹配。六、版本演进一次常规但必须执行的升级从仓库的迁移目录packages/gradle/src/migrations可以看到dev.nx.gradle.project-graph的版本升级是一条反复出现的迁移主题从 21-1-2 的0.1.0、21-3-0 的0.1.2一路到 22-2-0 的0.1.10、23-2-0 的0.1.25。这说明了两个事实插件版本与 Nx 版本是强绑定关系Nx 每次发布都会同步推进 Gradle 插件的版本号当前仓库 versions.ts 中维护的期望版本为0.1.250.1.10只是 22.2.0 时间节点上的中间版本后续升级流程会继续沿用同一套迁移框架自动推进。理解0.1.10这条迁移等于掌握了整个插件版本迁移家族的通用原理守卫条件 AST 保格式的 Catalog 更新 幂等的 build.gradle 更新。下次遇到change-plugin-version-0-1-x系列迁移你都能用同样的方法分析和验证。相关文件索引迁移说明change-plugin-version-0-1-10.md迁移实现change-plugin-version-0-1-10.ts测试用例change-plugin-version-0-1-10.spec.ts迁移注册表migrations.json插件启用判断has-gradle-plugin.tsbuild.gradle 更新逻辑gradle-project-graph-plugin-utils.tsVersion Catalog AST 工具version-catalog-ast-utils.ts插件版本常量versions.tsGradle 插件安装与用法project-graph/README.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），仅供参考