Nx Gradle 插件版本迁移实战将 dev.nx.gradle.project-graph 升级至 0.1.6【免费下载链接】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 仓库中注册于 21.4.1 版本、用于将 Gradle 项目图插件dev.nx.gradle.project-graph从 0.1.0 升级到 0.1.6 的自动迁移展开讲解该迁移的触发条件、底层实现原理、在 Groovy DSL / Kotlin DSL / Gradle Version Catalog 等多种场景下的行为以及配套测试对迁移正确性的验证方式。读完本文你将掌握 Nx 对 Gradle 插件版本做代码级自动化升级的完整套路并能自行核查与手动执行类似的小版本升级。迁移背景为什么需要一条改版本号的迁移dev.nx.gradle.project-graph是 Nx 官方维护的 Gradle 插件负责在 Gradle 构建中生成供 Nx 消费的项目图 JSON项目节点、目标与依赖关系。Nx 的 Gradle 集成nx/gradle会通过nx.json中声明的nx/gradle插件把 Gradle 项目纳入 Nx 工作区而该 Gradle 插件的版本需要与 Nx 版本保持配套。为了不让用户手工逐个打开build.gradle改版本号Nx 采用迁移migration机制每次 Nx 升级时把对用户文件系统的改动封装成一条自动化变更。本迁移正是该机制在 21.4.1 版本中的一个实例文档原文change-plugin-version-0-1-6.md描述的内容非常聚焦把构建文件中的dev.nx.gradle.project-graph插件版本改为0.1.6。从仓库的迁移目录结构可以看出这是一条持续演进的主线21-1-2升级到 0.1.0、21-3-0到 0.1.2、21-3-11到 0.1.4、21-4-0到 0.1.5本迁移21-4-1到 0.1.6之后还有 0.1.721-5-1一直到当前仓库packages/gradle/src/utils/versions.ts中的0.1.25。每一条都遵循相同的模式本迁移可以作为理解整条主线的最小切片。迁移要改什么Before / After 示例迁移文档给出了最直接的改动示例。升级前构建脚本中的插件声明为plugins { id dev.nx.gradle.project-graph version 0.1.0 }升级后plugins { id dev.nx.gradle.project-graph version 0.1.6 }需要注意几点插件 ID 保持不变仍然是dev.nx.gradle.project-graph该常量定义于 packages/gradle/src/utils/versions.ts 的gradleProjectGraphPluginName仅版本号字符串由0.1.0变为0.1.6文档给出的是 Groovy DSL 语法实际迁移同样覆盖 Kotlin DSLbuild.gradle.kts中的id(dev.nx.gradle.project-graph) version(0.1.6)这一点由迁移实现与测试共同保证。迁移的触发条件只在该管的地方动手迁移并非无条件执行入口函数change-plugin-version-0-1-6.ts在动手前先做两道守卫const nxJson readNxJson(tree); if (!nxJson) { return; } if (!hasGradlePlugin(tree)) { return; }第一道工作区必须存在nx.json否则整个迁移直接返回第二道nx.json的plugins配置中必须启用nx/gradle插件。hasGradlePluginpackages/gradle/src/utils/has-gradle-plugin.ts的检查逻辑是遍历nxJson.plugins匹配字符串形式的nx/gradle或对象形式中plugin nx/gradle的条目。这两道守卫的意义在于迁移只作用于启用了 Nx Gradle 集成的工作区避免对纯 Gradle 项目产生意外写入。这也是测试用例中专门覆盖无nx.json不改动无 Gradle 插件不改动两个场景的原因。迁移的两条执行路径版本目录与构建脚本在通过守卫后迁移依次执行两个步骤源码注释明确标注了顺序// 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 Version Cataloglibs.versions.toml的 AST 更新现代 Gradle 项目常用 Version Catalog 集中管理依赖与插件版本。迁移通过 packages/gradle/src/utils/version-catalog-ast-utils.ts 中的updateNxPluginVersionInCatalogsAst处理这类文件用globAsync递归查找所有**/gradle/*.versions.toml对每个文件用toml-eslint-parser解析成 AST在[plugins]表中定位插件dev.nx.gradle.project-graph支持三种声明形态简单格式nx-graph dev.nx.gradle.project-graph:0.1.0替换:后的版本号对象格式 直接版本nx-graph { id ..., version 0.1.0 }替换version值对象格式 版本引用nx-graph { id ..., version.ref nx-project-graph }此时需进一步定位[versions]表中的nx-project-graph 0.1.0并替换其值关键设计是基于 AST 节点范围range做增量替换reconstructTomlWithUpdates而不是整文件重写从而完整保留原有缩进、注释与引号风格——这就是源码注释中 preserve formatting 的含义。路径二build.gradle(.kts)的正则更新addNxProjectGraphPluginpackages/gradle/src/generators/init/gradle-project-graph-plugin-utils.ts负责构建脚本的更新其内部流程为查找工作区所有settings.gradle/settings.gradle.kts确保每个旁边存在对应的build.gradle/build.gradle.ktsaddBuildGradleFileNextToSettingsGradle用正则/(id\s*\(?[]dev\.nx\.gradle\.project-graph[]\)?\s*version\s*\(?[])([^])([]\)?)/同时匹配 Groovyid ... version ...与 Kotlinid(...) version(...)两种写法通过updateNxPluginVersion执行替换命中则原地替换版本号未命中则打印警告Please update plugin dev.nx.gradle.project-graph to 0.1.6并保持内容不变降级为提示不强行破坏文件。此外如果构建脚本通过版本目录别名如alias(libs.plugins.nx.graph)引用插件迁移会通过findVersionCatalogPluginAlias在构建文件同级gradle/libs.versions.toml→ 工作区根目录gradle/libs.versions.toml→ 子目录任意libs.versions.toml的顺序中查找别名并通过aliasToAccessorPath将连字符别名nx-project-graph转换为 Gradle 访问器nx.project.graph确保别名引用与直接声明两种方式都能被正确处理、且不会重复追加。迁移覆盖的实操场景全景从配套测试 change-plugin-version-0-1-6.spec.ts 可以归纳出该迁移在真实工作区中会遇到的完整场景矩阵这也是你在实际升级时可对照自查的清单场景测试行为结论Groovy DSLbuild.gradleid dev.nx.gradle.project-graph version 0.0.1→ 0.1.6正则直接替换旧版本号不再存在Kotlin DSLbuild.gradle.ktsid(dev.nx.gradle.project-graph) version(0.0.1)→ 0.1.6括号写法同样被匹配缺少nx.json文件内容原样保留迁移安全退出不做任何改动nx.json未启用nx/gradle文件内容原样保留守卫生效多模块多个build.gradleproj1与proj2全部升级逐个settings.gradle驱动覆盖所有子项目Version Catalogversion.ref[versions]中nx-project-graph 0.0.1→0.1.6引用链被正确追踪Version Catalog直接版本内联version 0.0.1→0.1.6对象格式直接版本被替换Version Catalog简单格式dev.nx.gradle.project-graph:0.0.1→:0.1.6:后版本被替换Catalog 与构建脚本同时存在两处版本均升级且互不冲突两条执行路径协同工作复杂 Catalog含[libraries]/[bundles]仅nx-gradle-project-graph版本变化其余条目不动AST 增量替换格式化零破坏如何应用这条迁移该迁移已注册在 packages/gradle/migrations.json条目change-plugin-version-0-1-6指向./dist/src/migrations/21-4-1/change-plugin-version-0-1-6文档指向对应的.md。当你的工作区启用nx/gradle并将 Nx 升级到包含 21.4.1 的版本后通过 Nx 标准的nx migrate流程即可让该迁移自动改写上述各类构建文件迁移执行前后建议对比 git diff确认只有插件版本号被变更、缩进与注释保持不变。如果出于某种原因需要手工升级例如迁移被跳过只需按文档的 Before/After 示例将build.gradle与build.gradle.kts中的版本改为0.1.6并在使用 Version Catalog 时同步更新libs.versions.toml中对应的版本条目若构建脚本里只有警告而没有自动替换说明插件声明写法不在正则覆盖范围内需要人工核对插件 ID 字符串是否与dev.nx.gradle.project-graph完全一致。升级之后0.1.6 插件的职责与用法升级到的0.1.6插件本身是 Nx 与 Gradle 之间的桥梁。根据 packages/gradle/project-graph/README.md该插件的核心职责是在构建时输出 Nx 可消费的项目图 JSON并暴露nxProjectGraph任务./gradlew nxProjectGraph任务运行后会在workspace/build/nx/add-nx-to-gradle.json生成包含nodes、dependencies、externalNodes的结构化数据其中nodes下的每个项目又包含targets信息——这正是 Nx 计算任务图、进行缓存与增量构建的数据基础。插件还支持通过-Phash12345传入哈希参数以及在nxProjectReport块中设置atomized false来关闭每个 Gradle 任务生成独立 Nx 目标的原子化模式。掌握这些能力可以让你在升级版本后更好地利用插件产出。小结dev.nx.gradle.project-graph0.1.0 → 0.1.6 的迁移虽然表面只是改一个版本号但其背后是 Nx 迁移机制的一次完整示范通过nx.json守卫确定作用域、用 AST 增量替换保住 Version Catalog 的格式、用兼容双 DSL 的正则处理构建脚本、以多场景测试矩阵锁定行为边界。这条迁移与你后续遇到的 0.1.7、0.1.8 直至当前仓库versions.ts中的 0.1.25 系列迁移共享同一套实现骨架理解它就等于理解了 Nx 在 Gradle 插件版本治理上的全部要点。【免费下载链接】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），仅供参考