Nx Gradle 插件迁移指南：升级 dev.nx.gradle.project-graph 至 0.1.14

Nx Gradle 插件迁移指南升级 dev.nx.gradle.project-graph 至 0.1.14【免费下载链接】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 仓库中nx/gradle插件在 22.6.0 版本引入的自动化迁移展开说明该迁移如何把 Gradle 构建文件中的dev.nx.gradle.project-graph插件版本从 0.1.13 升级到 0.1.14并深入解析其底层实现机制。读完本文你将掌握该迁移的触发条件、自动改写 build 文件与版本目录version catalog的工作原理以及不依赖自动迁移时的手动升级方法。迁移概述一次版本号升级背后的自动化在 Nx 22.6.0 中nx/gradle插件附带了一条自动化迁移migration其唯一目标是调整 Gradle 构建脚本中声明的 Nx 项目图Project Graph插件版本。该迁移的变更内容与文档记录定义在 change-plugin-version-0-1-14.md并在 migrations.json 中注册为change-plugin-version-0-1-14对应的发布版本为22.6.0-beta.11。它的定位非常清晰只做版本替换不做任何逻辑重构。升级完成后Gradle 构建文件中的插件声明将从旧版本切换到新版本其余内容保持原样。变更内容Before / After迁移对build.gradle的改动如下。升级前Beforeplugins { id dev.nx.gradle.project-graph version 0.1.13 }升级后Afterplugins { id dev.nx.gradle.project-graph version 0.1.14 }需要注意的是Gradle 项目还可能使用 Kotlin DSLbuild.gradle.kts此时插件声明的写法为id(dev.nx.gradle.project-graph) version(0.1.14)。迁移对两种 DSL 形式均予以支持判断逻辑见下文源码分析。另外如果项目采用了 Gradle 版本目录gradle/libs.versions.toml则迁移会优先更新目录中的插件版本而非直接改写 build 文件这部分在版本目录场景一节展开。迁移的触发条件与执行流程这条迁移并非对任何仓库都无条件生效。其入口实现位于 change-plugin-version-0-1-14.ts执行流程如下。前置条件检查const nxJson readNxJson(tree); if (!nxJson) { return; } if (!hasGradlePlugin(tree)) { return; }迁移会做两层判断工作区必须存在nx.json否则直接返回工作区必须已启用nx/gradle插件。第二层判断通过hasGradlePlugin完成其实现位于 has-gradle-plugin.ts它会遍历nx.json的plugins数组检查是否存在值为nx/gradle的字符串项或{ plugin: nx/gradle }形式的对象项。也就是说只有真正接入 Nx Gradle 集成的仓库才会被该迁移触碰。两步更新策略const gradlePluginVersionToUpdate 0.1.14; // 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);迁移采取先目录、后构建文件的两步策略第一步扫描工作区中所有gradle/libs.versions.toml版本目录文件若其中声明了 Nx 项目图插件则更新其版本第二步定位每个settings.gradle(.kts)旁的build.gradle(.kts)更新或补齐插件声明。版本目录基于 TOML AST 的格式保留更新在 version-catalog-ast-utils.ts 中目录更新采用了基于toml-eslint-parser的 AST 方案而非简单的字符串替换。其核心价值在于保留原有格式它解析 TOML 得到 AST只针对版本值节点所在的[start, end)范围做定点替换再按位置逆序拼接回原文从而不破坏注释、缩进、引号风格等细节。该工具支持两种常见的目录声明格式简单格式simplenxProjectGraph dev.nx.gradle.project-graph:0.1.13更新时会连同插件 ID 一起替换版本部分对象格式objectnxProjectGraph { id dev.nx.gradle.project-graph, version 0.1.13 }会直接更新version字段若使用version.ref ...引用[versions]表中的版本变量则会递归找到被引用的版本项进行更新。build.gradle(.kts)正则匹配与版本替换针对直接写在构建文件中的插件声明gradle-project-graph-plugin-utils.ts 定义了匹配正则const regex /(id\s*\(?[]dev\.nx\.gradle\.project-graph[]\)?\s*version\s*\(?[])([^])([]\)?)/;该正则同时兼容 Groovy DSLid ... version ...与 Kotlin DSLid(...) version(...)两种写法捕获组$2即为当前版本号。更新函数updateNxPluginVersion将其替换为目标版本若正则未命中例如通过版本目录别名alias(libs.plugins.nx.project.graph)声明则无法原地替换此时会输出警告日志提示手动更新。手动升级方式如果工作区未通过nx migrate自动执行该迁移或出于某种原因需要手动升级可以直接修改构建文件打开build.gradle或build.gradle.kts将dev.nx.gradle.project-graph的版本号改为0.1.14重新运行任意 Nx 命令如nx graph或nx run-many -t build确认项目图生成与构建链路正常。若项目使用版本目录则应同步修改gradle/libs.versions.toml中对应插件的版本或在引用该版本的version.ref处一并更新。从 0.1.x 到 0.1.25系列迁移的版本演进dev.nx.gradle.project-graph的升级在 Nx 仓库中被建模为一连串的独立迁移每个小版本对应一条迁移记录。从 migrations.json 可以看到完整的演进链迁移目标版本引入版本0.1.021.1.2-beta.10.1.221.3.0-beta.00.1.421.3.11-beta.00.1.521.4.0-beta.120.1.621.4.1-beta.10.1.721.5.1-beta.50.1.821.6.1-beta.20.1.922.1.0-rc.30.1.1022.2.0-beta.40.1.1122.4.0-beta.20.1.1222.5.0-beta.50.1.1322.5.30.1.1422.6.0-beta.110.1.1522.6.0-beta.130.1.16 ~ 0.1.2022.7.0 各 beta 版本0.1.21 / 0.1.2223.0.0 各 beta / rc 版本0.1.23 / 0.1.2423.1.0 各 beta 版本0.1.2523.2.0-beta.11这种一版一迁移的设计使得任意历史版本的工作区都能通过nx migrate逐步收敛到最新插件版本。当前仓库中nx/gradle期望的默认插件版本常量定义在 versions.tsexport const gradleProjectGraphPluginName dev.nx.gradle.project-graph; export const gradleProjectGraphVersion 0.1.25;其中gradleProjectGraphVersion是addNxProjectGraphPlugin在未显式传参时使用的默认目标版本而change-plugin-version-0-1-14这类迁移则显式传入各自的历史版本号确保迁移过程在时间线上是确定且可重放的。验证迁移结果迁移完成后可通过以下方式验证检查build.gradle(.kts)中的插件版本号已变为0.1.14若使用版本目录检查gradle/libs.versions.toml中对应项含version.ref引用的[versions]项已同步更新运行nx graph查看项目图是否正常生成或运行一次构建任务确认 Gradle 能正确解析新版本的插件。需要说明的是本文描述的迁移行为以当前仓库packages/gradle下的实现为准若你的 Nx 版本早于 22.6.0-beta.11该迁移不会出现在迁移清单中若晚于 23.2.0-beta.11则推荐直接升级到默认的0.1.25版本。执行nx migrate前请先提交工作区变更以便在升级出现问题时回退。【免费下载链接】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），仅供参考