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.12Beforeplugins { id dev.nx.gradle.project-graph version 0.1.11 }Afterplugins { 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-12Nx 会根据 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); }前置条件双重守卫确保安全迁移启动前有两个保护性检查必须存在nx.json——没有 Nx 配置就没有必要执行必须启用了nx/gradle插件——has-gradle-plugin.ts 会遍历nx.json的plugins数组检查其中是否包含nx/gradleexport 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*\(?[])([^])([]\)?)/;即同时匹配Groovyid dev.nx.gradle.project-graph version 0.1.11Kotlinid(dev.nx.gradle.project-graph) version(0.1.11)匹配成功后只替换中间的版本号部分插件 ID 与引号风格原样保留。若正则未命中例如版本号通过版本目录引用函数会打印一条警告提示手动更新而不是盲目破坏文件结构。此外该工具还提供一个兜底方案extractNxPluginVersion如果无法从文件文本中提取版本会调用./gradlew buildEnvironment --quiet从 Gradle 依赖树中解析实际生效的插件版本确保迁移前后判断准确。更新 libs.versions.tomlAST 解析保住注释与排版现代 Gradle 项目往往通过版本目录统一管理依赖插件声明分散在libs.versions.toml中。迁移的第二路处理 version-catalog-ast-utils.ts 专门针对这一场景用toml-eslint-parser将 TOML 解析为 AST定位[plugins]表中插件 ID 为dev.nx.gradle.project-graph的条目根据声明格式选择对应的更新路径按 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.json直接返回不做任何修改nx.json的 plugins 中没有nx/gradle直接返回不修改版本已是 0.1.12不重复修改实现中currentVersion ! expectedVersion才执行替换通过版本目录 alias 声明插件更新目录中的版本不向build.gradle重复注入插件声明手动升级与验证不需要自动迁移时如果你因为某种原因无法运行 Nx 迁移也可以手动完成升级1. Groovy DSLbuild.gradleplugins { id java id dev.nx.gradle.project-graph version 0.1.12 }2. Kotlin DSLbuild.gradle.ktsplugins { 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.13Nx 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考