Nx 22.5.0 Gradle 插件升级实战：将 dev.nx.gradle.project-graph 迁移至 0.1.12

Nx 22.5.0 Gradle 插件升级实战：将 dev.nx.gradle.project-graph 迁移至 0.1.12

【免费下载链接】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 仓库中 22-5-0 版本的迁移文档，系统讲解如何将 Gradle 项目中的dev.nx.gradle.project-graph插件版本升级到 0.1.12。你将理解该迁移产生的背景、Nx 自动迁移机制的源码实现、版本目录（version catalog）的三种写法兼容方案，并掌握手动升级与验证的完整步骤。

迁移背景：为什么 Nx 需要固定这个 Gradle 插件版本

dev.nx.gradle.project-graph是 Nx 官方发布的 Gradle 插件，其作用是生成 Nx 项目图（project graph）所需的 JSON 报告文件。从仓库内的插件定义（build.gradle.kts）可以看到，它的插件 ID 为dev.nx.gradle.project-graph，实现类为dev.nx.gradle.NxProjectGraphReportPlugin，职责是"生成包含 nodes、dependencies、externalNodes 的 JSON 文件供 Nx 消费"。

{ "nodes": { "app": { "targets": {} } }, "dependencies": [], "externalNodes": {} }

由于该插件与 Nx 的 Gradle 集成（@nx/gradle）通过约定的 JSON 格式协同工作，Nx 官方在每次发布新版本时，都会同步推进 Gradle 插件的小版本更新。这也就是为什么 Nx 的迁移体系里存在一整条"升级链"——从 0.1.0 一路升级到 0.1.25，本次讨论的 0.1.12 只是其中的一环。查看 migrations.json 可以确认，这条迁移注册在 Nx 版本22.5.0-beta.5上，描述为：

Change dev.nx.gradle.project-graph to version 0.1.12 in build file

迁移文档的核心内容：Before / After

原迁移文档给出了最直观的变更说明——把build.gradle中的插件版本从 0.1.11 提升到 0.1.12：

Before

plugins { id "dev.nx.gradle.project-graph" version "0.1.11" }

After

plugins { id "dev.nx.gradle.project-graph" version "0.1.12" }

表面上看这只是改动一个版本号，但在这份文档背后，Nx 的自动化迁移会为你处理远比这复杂的工作：除了 Groovy DSL 的build.gradle，还有 Kotlin DSL 的build.gradle.kts，以及越来越主流的 Gradle 版本目录libs.versions.toml。下面逐一展开。

自动化迁移：一行命令完成升级

Nx 的迁移机制会在升级 Nx 版本时自动执行这类"插件版本同步"。在真实工作区中，升级到 Nx 22.5.0 后运行迁移命令：

npx nx migrate @nx/gradle npx nx migrate --run-migrations

或直接运行注册的迁移器：

npx nx g @nx/gradle:migrate-change-plugin-version-0-1-12

Nx 会根据 migrations.json 中登记的version: "22.5.0-beta.5"自动判定该迁移适用的 Nx 版本范围，并对工作区内的所有 Gradle 项目统一执行升级。

源码剖析：迁移到底做了什么

迁移的实际逻辑位于 change-plugin-version-0-1-12.ts，整体分为三步：

export default async function update(tree: Tree) { const nxJson = readNxJson(tree); if (!nxJson) { return; } if (!hasGradlePlugin(tree)) { return; } const gradlePluginVersionToUpdate = '0.1.12'; // 1. 使用 AST 方式更新版本目录，保留原有格式 await updateNxPluginVersionInCatalogsAst(tree, gradlePluginVersionToUpdate); // 2. 再更新 build.gradle(.kts) 文件 await addNxProjectGraphPlugin(tree, gradlePluginVersionToUpdate); }

前置条件：双重守卫确保安全

迁移启动前有两个保护性检查：

1. 必须存在nx.json——没有 Nx 配置就没有必要执行；
2. 必须启用了@nx/gradle插件——has-gradle-plugin.ts 会遍历nx.json的plugins数组，检查其中是否包含@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 管理 Gradle 项目时，迁移才会生效，避免对无关项目造成误改。

更新 build.gradle(.kts)：正则匹配精准替换

gradle-project-graph-plugin-utils.ts 中的updateNxPluginVersion负责改写构建脚本。它使用一条正则同时兼容 Groovy 与 Kotlin DSL 的写法：

const regex = /(id\s*\(?["']dev\.nx\.gradle\.project-graph["']\)?\s*version\s*\(?["'])([^"']+)(["']\)?)/;

即同时匹配：

• Groovy：id "dev.nx.gradle.project-graph" version "0.1.11"
• Kotlin：id("dev.nx.gradle.project-graph") version("0.1.11")

匹配成功后只替换中间的版本号部分，插件 ID 与引号风格原样保留。若正则未命中（例如版本号通过版本目录引用），函数会打印一条警告提示手动更新，而不是盲目破坏文件结构。

此外，该工具还提供一个兜底方案extractNxPluginVersion：如果无法从文件文本中提取版本，会调用./gradlew buildEnvironment --quiet从 Gradle 依赖树中解析实际生效的插件版本，确保迁移前后判断准确。

更新 libs.versions.toml：AST 解析保住注释与排版

现代 Gradle 项目往往通过版本目录统一管理依赖，插件声明分散在libs.versions.toml中。迁移的第二路处理 version-catalog-ast-utils.ts 专门针对这一场景：

1. 用toml-eslint-parser将 TOML 解析为 AST；
2. 定位[plugins]表中插件 ID 为dev.nx.gradle.project-graph的条目；
3. 根据声明格式选择对应的更新路径；
4. 按 AST 节点区间做字符串切片重组（reconstructTomlWithUpdates），只替换版本值，注释、缩进、空行等全部原样保留。

版本目录的三种写法，迁移全部兼容

从 change-plugin-version-0-1-12.spec.ts 的测试用例可以看出，迁移覆盖了版本目录中声明 Gradle 插件的三种主流格式：

格式一：简单格式（"插件ID:版本号"）

[plugins] nx-graph = "dev.nx.gradle.project-graph:0.0.1"

迁移后变为"dev.nx.gradle.project-graph:0.1.12"。实现中还会保留原字符串的引号风格（单引号或双引号），见version-catalog-ast-utils.ts中的quote判断。

格式二：对象格式 + 直接版本

[plugins] nx-graph = { id = "dev.nx.gradle.project-graph", version = "0.0.1" }

直接更新version键的值。

格式三：对象格式 + version.ref 引用

[versions] nx-project-graph = "0.0.1" [plugins] nx-graph = { id = "dev.nx.gradle.project-graph", version.ref = "nx-project-graph" }

这是最需要"追根溯源"的写法——插件本身没有版本号，迁移必须顺着version.ref找到[versions]表中对应的条目并修改它。测试中还覆盖了包含[libraries]、[bundles]等更多段落的"复杂目录"场景，确保在真实项目中不会误伤其他依赖。

多模块与多文件：迁移天然支持整个工作区

迁移不是只处理一个文件。addBuildGradleFileNextToSettingsGradle会通过 glob 匹配工作区下所有的settings.gradle与settings.gradle.kts，在其同目录定位build.gradle(.kts)；findVersionCatalogFiles则匹配所有**/gradle/*.versions.toml。这意味着：

• 单仓库内存在proj1、proj2等多个 Gradle 项目时，所有build.gradle都会被统一升级（测试用例should handle multiple build.gradle files验证了这一点）；
• 每个项目的gradle/libs.versions.toml也会同步更新；
• 版本目录与构建脚本同时存在时，两处都会被改到（测试用例should handle both version catalog and build.gradle updates验证了两者都变成 0.1.12）。

边界情况：什么情况下迁移会选择"不动"

自动迁移同样重视安全性与幂等性，测试用例明确覆盖了以下边界：

手动升级与验证（不需要自动迁移时）

如果你因为某种原因无法运行 Nx 迁移，也可以手动完成升级：

1. Groovy DSL（build.gradle）：

plugins { id 'java' id "dev.nx.gradle.project-graph" version "0.1.12" }

2. Kotlin DSL（build.gradle.kts）：

plugins { id("java") id("dev.nx.gradle.project-graph") version("0.1.12") }

3. 使用版本目录（gradle/libs.versions.toml）：

[versions] nx-project-graph = "0.1.12" [plugins] nx-graph = { id = "dev.nx.gradle.project-graph", version.ref = "nx-project-graph" }

升级完成后，运行插件的核心任务验证插件可正常生成项目图报告（参考 project-graph 插件 README）：

./gradlew nxProjectGraph

成功时终端会输出报告文件路径：

> Task :nxProjectGraph < your workspace >/build/nx/add-nx-to-gradle.json

随后在 Nx 侧执行npx nx graph，即可看到 Gradle 项目以节点形式出现在项目图中。若需要排查版本是否真的生效，可运行./gradlew buildEnvironment --quiet检查依赖树中dev.nx.gradle.project-graph的实际解析版本。

延伸：迁移链条与当前版本

值得注意的是，0.1.12 并不是终点。同一迁移机制随后又推出了 0.1.13（Nx 22.5.3）、0.1.14、0.1.15……直至 versions.ts 中记录的gradleProjectGraphVersion = '0.1.25'（插件构建文件 build.gradle.kts 中的version = "0.1.25"与之对应）。升级到更高版本 Nx 时，会按顺序执行对应的版本迁移，逐步把插件推进到与 Nx 匹配的版本。这套"版本链迁移"的设计思路，保证了 Nx 与 Gradle 插件始终以约定的 JSON 契约协同工作，也是 Nx 作为 Monorepo 平台对多语言生态做版本治理的典型实践。

【免费下载链接】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