：將 dev.nx.gradle.project-graph 升級至 0.1.20)
Nx Gradle 插件版本遷移實戰(zhàn)將 dev.nx.gradle.project-graph 升級至 0.1.20【免費下載鏈接】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本篇技術(shù)指南以 Nx 倉庫中 change-plugin-version-0-1-20.md 為骨架講解如何將 Gradle 構(gòu)建中的dev.nx.gradle.project-graph插件從 0.1.19 升級到 0.1.20。你將掌握手動修改構(gòu)建文件與通過nx migrate自動遷移兩條路徑并深入理解 Nx 遷移器在 build.gradle、build.gradle.kts 與 version cataloglibs.versions.toml三種聲明場景下的底層更新原理。遷移背景Nx 與 Gradle 項目圖的版本綁定Nx 通過nx/gradle插件將 Gradle 項目接入 Nx 的可計算項目圖project graph而這一能力依賴一個獨立的 Gradle 插件dev.nx.gradle.project-graph。該插件在 Gradle 構(gòu)建期執(zhí)行項目圖探測生成一份 JSON 文件供 Nx 消費其產(chǎn)物結(jié)構(gòu)包含nodes、dependencies與externalNodes三部分詳見 project-graph/README.md。由于 Nx 主版本與 Gradle 插件版本之間存在兼容性綁定Nx 在每次插件迭代后都會通過**遷移migration**機制要求工作區(qū)同步升級插件版本。0.1.20正是 Nx 22.7.0 周期內(nèi)的一次插件版本更新——在 migrations.json 中該遷移被注冊在22.7.0-beta.16版本下change-plugin-version-0-1-20: { version: 22.7.0-beta.16, cli: nx, description: Change dev.nx.gradle.project-graph to version 0.1.20 in build file, factory: ./dist/src/migrations/22-7-0/change-plugin-version-0-1-20, documentation: ./dist/src/migrations/22-7-0/change-plugin-version-0-1-20.md }同一遷移批次22-7-0目錄還包含 0.1.16 至 0.1.19 的連續(xù)版本升級可以看出這是 Nx 針對 Gradle 插件的高頻小版本迭代節(jié)奏。手動升級修改構(gòu)建文件中的插件版本原遷移文檔給出的核心操作是在構(gòu)建文件中將dev.nx.gradle.project-graph的版本改為 0.1.20。文檔以 Groovy DSLbuild.gradle給出了修改前后的對照修改前Beforeplugins { id dev.nx.gradle.project-graph version 0.1.19 }修改后Afterplugins { id dev.nx.gradle.project-graph version 0.1.20 }如果你的工作區(qū)使用 Kotlin DSLbuild.gradle.kts則對應(yīng)的寫法是plugins { id(dev.nx.gradle.project-graph) version(0.1.20) }通過 version catalog 管理版本的情況在大型 Gradle 工作區(qū)中插件版本往往不直接寫在plugins {}塊里而是集中聲明在gradle/libs.versions.toml再以 alias 方式引用。此時你需要修改的是 catalog 文件例如[plugins] nx-project-graph { id dev.nx.gradle.project-graph, version 0.1.20 }plugins { alias(libs.plugins.nx.project.graph) }注意catalog alias 中的短橫線nx-project-graph在 Gradle accessor 中會轉(zhuǎn)換為點號nx.project.graph這一規(guī)則在 gradle-project-graph-plugin-utils.ts 的aliasToAccessorPath函數(shù)中有明確實現(xiàn)。使用 nx migrate 自動升級手動修改雖然直觀但 Nx 推薦通過官方遷移通道完成升級。遷移器已在nx/gradle包的 migrations.json 中注冊并聲明cli: nx因此當(dāng)你將 Nx 升級到包含 22.7.0-beta.16 的版本后運行nx migrate nx/gradleNx 會解析遷移清單把change-plugin-version-0-1-20歸入待執(zhí)行的遷移集并在執(zhí)行階段調(diào)用對應(yīng)的遷移工廠factory。執(zhí)行遷移后構(gòu)建文件中的插件版本會自動更新為 0.1.20無需手工編輯。遷移器底層實現(xiàn)解析自動遷移的核心邏輯位于 change-plugin-version-0-1-20.ts其執(zhí)行流程分為四個步驟export default async function update(tree: Tree) { const nxJson readNxJson(tree); if (!nxJson) { return; } if (!hasGradlePlugin(tree)) { return; } const gradlePluginVersionToUpdate 0.1.20; // 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); }步驟一前置守衛(wèi)遷移器首先讀取工作區(qū)根目錄的nx.json。若文件不存在或工作區(qū)并未啟用nx/gradle插件遷移器會直接跳過。hasGradlePlugin的實現(xiàn)見 has-gradle-plugin.ts會檢查nx.json中plugins數(shù)組是否包含nx/gradle——它同時兼容字符串形式nx/gradle與對象形式{ plugin: nx/gradle }的聲明。這意味著只有真正使用 Gradle 支持的工作區(qū)才會被改動避免了對無關(guān)項目的無謂寫入。步驟二先更新 version catalog遷移器優(yōu)先處理gradle/libs.versions.toml這類版本目錄文件由 updateNxPluginVersionInCatalogsAst 負責(zé)。它會通過globAsync查找所有**/gradle/*.versions.toml然后對每個 catalog 執(zhí)行 AST 級別的版本替換。關(guān)鍵設(shè)計是基于 AST 的定點替換利用toml-eslint-parser解析 TOML 源碼精確定位插件聲明的 token 區(qū)間start/end僅替換版本字符串本身而不是整行重寫。因此原有的注釋、縮進、鍵順序與引號風(fēng)格單引號或雙引號都能被完整保留。該工具同時支持兩種 catalog 聲明格式簡單格式nx-project-graph dev.nx.gradle.project-graph:0.1.19直接改寫為:0.1.20對象格式nx-project-graph { id dev.nx.gradle.project-graph, version 0.1.19 }改寫內(nèi)聯(lián)表中的version字段version.ref 間接引用{ id dev.nx.gradle.project-graph, version.ref nxProjectGraph }時會順著引用鏈去更新[versions]表中對應(yīng)的版本條目。步驟三再更新 build.gradle(.kts)catalog 更新完成后遷移器調(diào)用 addNxProjectGraphPlugin 處理所有build.gradle(.kts)文件。其工作方式為通過 glob 找到工作區(qū)內(nèi)所有settings.gradle與settings.gradle.kts并在其同目錄確保存在對應(yīng)的build.gradle或build.gradle.kts根據(jù) DSL 類型選擇聲明語法——Kotlin DSL 生成id(dev.nx.gradle.project-graph) version(0.1.20)Groovy DSL 生成id dev.nx.gradle.project-graph version 0.1.20若插件已通過 catalog alias 引用則改用alias(libs.plugins.nx.project.graph)語法避免版本寫死使用正則/id\s*\(?[]dev\.nx\.gradle\.project-graph[]\)?\s*version\s*\(?[]\)?/見 gradle-project-graph-plugin-utils.ts定位舊版本號并替換為 0.1.20若文件內(nèi)容匹配不到則記錄logger.warn提示手動更新不會破壞原文件確保插件在plugins {}塊中聲明并通過allprojects { apply ... }傳播到所有子項目。遷移器還會調(diào)用extractNxPluginVersion校驗當(dāng)前版本若構(gòu)建文件中無法解析出版本號它會回退到執(zhí)行./gradlew buildEnvironment --quiet從依賴樹輸出中匹配dev.nx.gradle.project-graph:dev.nx.gradle.project-graph.gradle.plugin:version來確認(rèn)實際生效版本見 gradle-project-graph-plugin-utils.ts。升級驗證與插件功能回顧升級到 0.1.20 后可通過以下命令驗證插件是否正確加載并生成項目圖./gradlew nxProjectGraph正常執(zhí)行會在終端輸出類似 Task :nxProjectGraph your workspace /build/nx/add-nx-to-gradle.json該 JSON 文件即 Nx 項目圖的數(shù)據(jù)來源。如需向 Gradle 探測過程傳遞額外參數(shù)可使用./gradlew nxProjectGraph -Phash12345此外該插件還提供nx {}DSL 用于在構(gòu)建文件中聲明項目級元數(shù)據(jù)name、tags與任務(wù)級配置如緩存開關(guān)以及nxProjectReport { atomized false }用于關(guān)閉任務(wù)級原子化目標(biāo)生成詳見 project-graph/README.md。這些能力與版本升級本身解耦可在升級后按需啟用。版本演進一覽0.1.20 在插件迭代中的位置從 packages/gradle/src/migrations 目錄結(jié)構(gòu)與 versions.ts 可以看出dev.nx.gradle.project-graph的版本隨 Nx 版本持續(xù)演進插件版本對應(yīng) Nx 版本遷移注冊位置0.1.16 ~ 0.1.1922.7.0-beta 系列22-7-0 目錄0.1.2022.7.0-beta.16change-plugin-version-0-1-20.ts0.1.21 ~ 0.1.2223.0.023-0-0 目錄0.1.23 ~ 0.1.2423.1.023-1-0 目錄0.1.2523.2.023-2-0 目錄值得注意的是倉庫當(dāng)前 versions.ts 中定義的默認(rèn)插件版本已推進到0.1.25而 project-graph/build.gradle.kts 也以0.1.25發(fā)布該插件本身。這印證了0.1.20是 22.7.0 時代的歷史遷移點只要工作區(qū)升級到包含該遷移的 Nx 版本無論之前停留在 0.1.19 還是更早版本都能通過同一遷移器平滑收斂到目標(biāo)版本。小結(jié)dev.nx.gradle.project-graph從 0.1.19 升級到 0.1.20 是一條典型的 Nx 插件版本遷移路徑手動場景下只需修改build.gradleGroovy或build.gradle.ktsKotlin中的插件版本號或同步更新gradle/libs.versions.toml自動場景下則通過nx migrate nx/gradle觸發(fā)注冊于 migrations.json 的遷移器。遷移器內(nèi)部以先版本目錄、后構(gòu)建文件的順序配合 AST 定點替換與正則版本匹配在保留原有格式的前提下完成升級并通過nx/gradle插件存在性守衛(wèi)確保只作用于適用工作區(qū)。理解這條調(diào)用鏈不僅能讓本次升級得心應(yīng)手也能讓你舉一反三地掌握 Nx 遷移機制在 Gradle 生態(tài)中的通用運作方式。【免費下載鏈接】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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Nx Gradle 插件版本遷移實戰(zhàn)：將 dev.nx.gradle.project-graph 升級至 0.1.20
Nx Gradle 插件版本遷移實戰(zhàn)將 dev.nx.gradle.project-graph 升級至 0.1.20【免費下載鏈接】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本篇技術(shù)指南以 Nx 倉庫中 change-plugin-version-0-1-20.md 為骨架講解如何將 Gradle 構(gòu)建中的dev.nx.gradle.project-graph插件從 0.1.19 升級到 0.1.20。你將掌握手動修改構(gòu)建文件與通過nx migrate自動遷移兩條路徑并深入理解 Nx 遷移器在 build.gradle、build.gradle.kts 與 version cataloglibs.versions.toml三種聲明場景下的底層更新原理。遷移背景Nx 與 Gradle 項目圖的版本綁定Nx 通過nx/gradle插件將 Gradle 項目接入 Nx 的可計算項目圖project graph而這一能力依賴一個獨立的 Gradle 插件dev.nx.gradle.project-graph。該插件在 Gradle 構(gòu)建期執(zhí)行項目圖探測生成一份 JSON 文件供 Nx 消費其產(chǎn)物結(jié)構(gòu)包含nodes、dependencies與externalNodes三部分詳見 project-graph/README.md。由于 Nx 主版本與 Gradle 插件版本之間存在兼容性綁定Nx 在每次插件迭代后都會通過**遷移migration**機制要求工作區(qū)同步升級插件版本。0.1.20正是 Nx 22.7.0 周期內(nèi)的一次插件版本更新——在 migrations.json 中該遷移被注冊在22.7.0-beta.16版本下change-plugin-version-0-1-20: { version: 22.7.0-beta.16, cli: nx, description: Change dev.nx.gradle.project-graph to version 0.1.20 in build file, factory: ./dist/src/migrations/22-7-0/change-plugin-version-0-1-20, documentation: ./dist/src/migrations/22-7-0/change-plugin-version-0-1-20.md }同一遷移批次22-7-0目錄還包含 0.1.16 至 0.1.19 的連續(xù)版本升級可以看出這是 Nx 針對 Gradle 插件的高頻小版本迭代節(jié)奏。手動升級修改構(gòu)建文件中的插件版本原遷移文檔給出的核心操作是在構(gòu)建文件中將dev.nx.gradle.project-graph的版本改為 0.1.20。文檔以 Groovy DSLbuild.gradle給出了修改前后的對照修改前Beforeplugins { id dev.nx.gradle.project-graph version 0.1.19 }修改后Afterplugins { id dev.nx.gradle.project-graph version 0.1.20 }如果你的工作區(qū)使用 Kotlin DSLbuild.gradle.kts則對應(yīng)的寫法是plugins { id(dev.nx.gradle.project-graph) version(0.1.20) }通過 version catalog 管理版本的情況在大型 Gradle 工作區(qū)中插件版本往往不直接寫在plugins {}塊里而是集中聲明在gradle/libs.versions.toml再以 alias 方式引用。此時你需要修改的是 catalog 文件例如[plugins] nx-project-graph { id dev.nx.gradle.project-graph, version 0.1.20 }plugins { alias(libs.plugins.nx.project.graph) }注意catalog alias 中的短橫線nx-project-graph在 Gradle accessor 中會轉(zhuǎn)換為點號nx.project.graph這一規(guī)則在 gradle-project-graph-plugin-utils.ts 的aliasToAccessorPath函數(shù)中有明確實現(xiàn)。使用 nx migrate 自動升級手動修改雖然直觀但 Nx 推薦通過官方遷移通道完成升級。遷移器已在nx/gradle包的 migrations.json 中注冊并聲明cli: nx因此當(dāng)你將 Nx 升級到包含 22.7.0-beta.16 的版本后運行nx migrate nx/gradleNx 會解析遷移清單把change-plugin-version-0-1-20歸入待執(zhí)行的遷移集并在執(zhí)行階段調(diào)用對應(yīng)的遷移工廠factory。執(zhí)行遷移后構(gòu)建文件中的插件版本會自動更新為 0.1.20無需手工編輯。遷移器底層實現(xiàn)解析自動遷移的核心邏輯位于 change-plugin-version-0-1-20.ts其執(zhí)行流程分為四個步驟export default async function update(tree: Tree) { const nxJson readNxJson(tree); if (!nxJson) { return; } if (!hasGradlePlugin(tree)) { return; } const gradlePluginVersionToUpdate 0.1.20; // 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); }步驟一前置守衛(wèi)遷移器首先讀取工作區(qū)根目錄的nx.json。若文件不存在或工作區(qū)并未啟用nx/gradle插件遷移器會直接跳過。hasGradlePlugin的實現(xiàn)見 has-gradle-plugin.ts會檢查nx.json中plugins數(shù)組是否包含nx/gradle——它同時兼容字符串形式nx/gradle與對象形式{ plugin: nx/gradle }的聲明。這意味著只有真正使用 Gradle 支持的工作區(qū)才會被改動避免了對無關(guān)項目的無謂寫入。步驟二先更新 version catalog遷移器優(yōu)先處理gradle/libs.versions.toml這類版本目錄文件由 updateNxPluginVersionInCatalogsAst 負責(zé)。它會通過globAsync查找所有**/gradle/*.versions.toml然后對每個 catalog 執(zhí)行 AST 級別的版本替換。關(guān)鍵設(shè)計是基于 AST 的定點替換利用toml-eslint-parser解析 TOML 源碼精確定位插件聲明的 token 區(qū)間start/end僅替換版本字符串本身而不是整行重寫。因此原有的注釋、縮進、鍵順序與引號風(fēng)格單引號或雙引號都能被完整保留。該工具同時支持兩種 catalog 聲明格式簡單格式nx-project-graph dev.nx.gradle.project-graph:0.1.19直接改寫為:0.1.20對象格式nx-project-graph { id dev.nx.gradle.project-graph, version 0.1.19 }改寫內(nèi)聯(lián)表中的version字段version.ref 間接引用{ id dev.nx.gradle.project-graph, version.ref nxProjectGraph }時會順著引用鏈去更新[versions]表中對應(yīng)的版本條目。步驟三再更新 build.gradle(.kts)catalog 更新完成后遷移器調(diào)用 addNxProjectGraphPlugin 處理所有build.gradle(.kts)文件。其工作方式為通過 glob 找到工作區(qū)內(nèi)所有settings.gradle與settings.gradle.kts并在其同目錄確保存在對應(yīng)的build.gradle或build.gradle.kts根據(jù) DSL 類型選擇聲明語法——Kotlin DSL 生成id(dev.nx.gradle.project-graph) version(0.1.20)Groovy DSL 生成id dev.nx.gradle.project-graph version 0.1.20若插件已通過 catalog alias 引用則改用alias(libs.plugins.nx.project.graph)語法避免版本寫死使用正則/id\s*\(?[]dev\.nx\.gradle\.project-graph[]\)?\s*version\s*\(?[]\)?/見 gradle-project-graph-plugin-utils.ts定位舊版本號并替換為 0.1.20若文件內(nèi)容匹配不到則記錄logger.warn提示手動更新不會破壞原文件確保插件在plugins {}塊中聲明并通過allprojects { apply ... }傳播到所有子項目。遷移器還會調(diào)用extractNxPluginVersion校驗當(dāng)前版本若構(gòu)建文件中無法解析出版本號它會回退到執(zhí)行./gradlew buildEnvironment --quiet從依賴樹輸出中匹配dev.nx.gradle.project-graph:dev.nx.gradle.project-graph.gradle.plugin:version來確認(rèn)實際生效版本見 gradle-project-graph-plugin-utils.ts。升級驗證與插件功能回顧升級到 0.1.20 后可通過以下命令驗證插件是否正確加載并生成項目圖./gradlew nxProjectGraph正常執(zhí)行會在終端輸出類似 Task :nxProjectGraph your workspace /build/nx/add-nx-to-gradle.json該 JSON 文件即 Nx 項目圖的數(shù)據(jù)來源。如需向 Gradle 探測過程傳遞額外參數(shù)可使用./gradlew nxProjectGraph -Phash12345此外該插件還提供nx {}DSL 用于在構(gòu)建文件中聲明項目級元數(shù)據(jù)name、tags與任務(wù)級配置如緩存開關(guān)以及nxProjectReport { atomized false }用于關(guān)閉任務(wù)級原子化目標(biāo)生成詳見 project-graph/README.md。這些能力與版本升級本身解耦可在升級后按需啟用。版本演進一覽0.1.20 在插件迭代中的位置從 packages/gradle/src/migrations 目錄結(jié)構(gòu)與 versions.ts 可以看出dev.nx.gradle.project-graph的版本隨 Nx 版本持續(xù)演進插件版本對應(yīng) Nx 版本遷移注冊位置0.1.16 ~ 0.1.1922.7.0-beta 系列22-7-0 目錄0.1.2022.7.0-beta.16change-plugin-version-0-1-20.ts0.1.21 ~ 0.1.2223.0.023-0-0 目錄0.1.23 ~ 0.1.2423.1.023-1-0 目錄0.1.2523.2.023-2-0 目錄值得注意的是倉庫當(dāng)前 versions.ts 中定義的默認(rèn)插件版本已推進到0.1.25而 project-graph/build.gradle.kts 也以0.1.25發(fā)布該插件本身。這印證了0.1.20是 22.7.0 時代的歷史遷移點只要工作區(qū)升級到包含該遷移的 Nx 版本無論之前停留在 0.1.19 還是更早版本都能通過同一遷移器平滑收斂到目標(biāo)版本。小結(jié)dev.nx.gradle.project-graph從 0.1.19 升級到 0.1.20 是一條典型的 Nx 插件版本遷移路徑手動場景下只需修改build.gradleGroovy或build.gradle.ktsKotlin中的插件版本號或同步更新gradle/libs.versions.toml自動場景下則通過nx migrate nx/gradle觸發(fā)注冊于 migrations.json 的遷移器。遷移器內(nèi)部以先版本目錄、后構(gòu)建文件的順序配合 AST 定點替換與正則版本匹配在保留原有格式的前提下完成升級并通過nx/gradle插件存在性守衛(wèi)確保只作用于適用工作區(qū)。理解這條調(diào)用鏈不僅能讓本次升級得心應(yīng)手也能讓你舉一反三地掌握 Nx 遷移機制在 Gradle 生態(tài)中的通用運作方式。【免費下載鏈接】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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考