Nx Gradle 插件迁移指南将 dev.nx.gradle.project-graph 升级到 0.1.19【免费下载链接】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 在22.7.0-beta.11版本中内置了一条自动迁移Migration用于将 Gradle 项目中的dev.nx.gradle.project-graph插件从0.1.18升级到0.1.19。本指南以 change-plugin-version-0-1-19.md 文档为核心讲解这条迁移的用途、触发方式、底层实现原理以及当自动迁移无法覆盖时的手动升级方案。阅读本文后你将理解 Nx 如何通过迁移机制维护 Gradle 插件版本的一致性并能独立完成该插件的版本升级与验证。迁移背景Nx 与 Gradle 项目图插件Nx 通过nx/gradle插件支持 Gradle 工作区的项目发现、依赖分析与任务编排。为了让 Nx 能识别 Gradle 工程结构并构建项目图Project GraphGradle 构建脚本中需要声明一个配套的 Gradle 插件plugins { id dev.nx.gradle.project-graph version 0.1.18 }这个插件的版本与nx/gradle插件之间存在对应关系Nx 每次升级都会通过迁移将工作区内的 Gradle 插件版本同步到新版本。仓库中packages/gradle/src/migrations/目录下保存了从0.1.0一路到0.1.25的完整迁移链例如 22-7-0 目录内就包含0.1.16至0.1.20五条迁移而packages/gradle/src/utils/versions.ts中定义的gradleProjectGraphVersion当前值为0.1.25说明后续版本仍在持续演进。本篇文章聚焦的0.1.19迁移对应 Nx 版本22.7.0-beta.11其注册信息位于 migrations.jsonchange-plugin-version-0-1-19: { version: 22.7.0-beta.11, cli: nx, description: Change dev.nx.gradle.project-graph to version 0.1.19 in build file, factory: ./dist/src/migrations/22-7-0/change-plugin-version-0-1-19, documentation: ./dist/src/migrations/22-7-0/change-plugin-version-0-1-19.md }可以看到该迁移由nxCLI 触发factory指向迁移的实际执行代码documentation指向本文所依据的说明文档。迁移结果Before / After 示例迁移完成后的改动非常直观——仅替换plugins块中的插件版本号。原文档给出了标准示例Beforeplugins { id dev.nx.gradle.project-graph version 0.1.18 }Afterplugins { id dev.nx.gradle.project-graph version 0.1.19 }对于 Kotlin DSL 工程对应的build.gradle.kts写法为plugins { id(dev.nx.gradle.project-graph) version 0.1.19 }如何触发这条迁移该迁移通过 Nx 的migrate命令运行。在包含nx/gradle插件且启用了 Gradle 支持的工作区中执行nx migrate nx/gradleNx 会根据 migrations.json 中记录的版本信息自动挑选并执行所有高于当前工作区版本的迁移其中包括change-plugin-version-0-1-19。之后运行nx migrate --run-migrations应用生成的migrations.json文件即可完成迁移。migrations.json中每条迁移的cli: nx字段表明它是由 Nx 自己的 migrate 流程调度的如果你使用的是 Lerna则需要通过nx migrate而不是 Lerna 命令来执行这类迁移。源码级解析迁移的内部执行流程迁移的实际逻辑位于 change-plugin-version-0-1-19.ts完整流程如下export default async function update(tree: Tree) { const nxJson readNxJson(tree); if (!nxJson) { return; } if (!hasGradlePlugin(tree)) { return; } const gradlePluginVersionToUpdate 0.1.19; // Update version in version catalogs using AST-based approach to preserve formatting await updateNxPluginVersionInCatalogsAst(tree, gradlePluginVersionToUpdate); // Then update in build.gradle(.kts) files await addNxProjectGraphPlugin(tree, gradlePluginVersionToUpdate); }第一步前置条件校验迁移首先调用readNxJson(tree)读取工作区根目录的nx.json。如果nx.json不存在直接返回不做任何改动。随后调用hasGradlePlugin定义于 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插件时迁移才会继续执行。这保证了迁移不会误伤未使用 Gradle 集成的普通 Nx 工作区。第二步更新 Version Cataloglibs.versions.toml迁移先通过updateNxPluginVersionInCatalogsAst处理版本目录。很多 Gradle 工程使用 Gradle Version Cataloggradle/libs.versions.toml统一管理依赖版本例如[plugins] nx-project-graph { id dev.nx.gradle.project-graph, version 0.1.18 }该工具采用AST抽象语法树方式改写版本号目的是在精确替换版本值的同时保留 TOML 文件的原有格式与注释避免简单字符串替换带来的格式破坏。第三步更新 build.gradle(.kts) 文件版本目录更新完成后迁移调用addNxProjectGraphPlugin处理各build.gradle(.kts)文件。该函数位于 gradle-project-graph-plugin-utils.ts其执行要点如下定位构建脚本通过globAsync查找工作区内所有**/settings.gradle与**/settings.gradle.kts文件并在每个 settings 文件同级确保存在对应的build.gradle或build.gradle.ktsKotlin DSL 工程为.kts后缀。版本匹配正则使用如下正则精确匹配插件声明const regex /(id\s*\(?[]dev\.nx\.gradle\.project-graph[]\)?\s*version\s*\(?[])([^])([]\)?)/;该正则同时兼容 Groovy DSLid ... version ...与 Kotlin DSLid(...) version(...)两种写法。就地替换通过updateNxPluginVersion将捕获到的旧版本号替换为0.1.19若在文件中找不到插件声明则会输出一条警告日志提示用户手动更新。版本目录优先addNxProjectGraphPluginToBuildGradle会依次在构建脚本所在目录的gradle/libs.versions.toml、工作区根目录的gradle/libs.versions.toml以及子目录的任意libs.versions.toml中查找插件别名。若找到别名如nx-project-graph则构建脚本中会改用alias(libs.plugins.nx.project.graph)形式声明插件别名中的连字符在 Gradle 访问器中转换为点号此时版本号统一由版本目录管理构建脚本本身不再出现版本字符串。幂等性保障如果插件已存在但版本不同则只更新版本如果插件已通过版本目录别名声明则跳过allprojects重复应用逻辑确保迁移重复执行不会产生重复的插件声明或多余的apply块。手动升级不依赖迁移命令的路径如果你希望跳过nx migrate流程或工作区结构特殊导致自动迁移未完全生效可以按照以下步骤手动升级场景一构建脚本中直接声明版本编辑build.gradleGroovy DSLplugins { id dev.nx.gradle.project-graph version 0.1.19 }或build.gradle.ktsKotlin DSLplugins { id(dev.nx.gradle.project-graph) version 0.1.19 }场景二使用 Version Catalog编辑gradle/libs.versions.toml将[plugins]下的版本值改为0.1.19[plugins] nx-project-graph { id dev.nx.gradle.project-graph, version 0.1.19 }若构建脚本中此前直接写死了版本号则将其改为别名引用形式plugins { alias(libs.plugins.nx.project.graph) }升级后的验证完成升级后可通过以下方式验证检查版本声明确认工作区内所有build.gradle、build.gradle.kts及libs.versions.toml中的插件版本均为0.1.19。运行构建执行./gradlew buildEnvironment --quiet观察依赖树中dev.nx.gradle.project-graph:dev.nx.gradle.project-graph.gradle.plugin的版本是否为0.1.19——这也是迁移代码中getPluginVersion函数位于 gradle-project-graph-plugin-utils.ts用于兜底探测实际生效版本的方式。验证 Nx 项目图运行nx graph或nx show projects确认 Nx 仍能正确识别 Gradle 项目结构说明插件升级后与nx/gradle的集成工作正常。结语dev.nx.gradle.project-graph从0.1.18到0.1.19的升级是 Nx22.7.0系列中一次常规的插件版本同步迁移。从源码实现看Nx 的迁移机制具备三项关键保障通过nx.json前置校验避免误改无关工程优先采用 AST 方式处理 Version Catalog 以保留格式通过正则与别名检测保证构建脚本改写的幂等性。理解这条迁移的实现思路也能帮助你预判后续每次 Gradle 插件版本升级如仓库中已存在的0.1.20至0.1.25迁移会如何作用于你的工作区。【免费下载链接】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），仅供参考