用 Nx migrate 自动化更新依赖:从 package.json 到源码的一站式迁移实战指南

发布时间:2026/9/10 0:51:02

用 Nx migrate 自动化更新依赖:从 package.json 到源码的一站式迁移实战指南 用 Nx migrate 自动化更新依赖从 package.json 到源码的一站式迁移实战指南【免费下载链接】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 migrate是 Nx 内置的依赖更新与代码迁移工具它不仅能自动改写package.json中的依赖版本还能同步更新 Vite、Playwright、Jest、ESLint 等配置文件并直接改写你的源码以适配新版本包带来的破坏性变更。本文以 Nx 官方课程 05-automate-updating-dependencies.md 为主线结合 Nx 官方文档 automate-updating-dependencies.mdoc 与仓库源码实现带你完整掌握nx migrate的两阶段工作流、--include包选择策略、AI 辅助迁移agentic flow以及nx.json全局默认配置读完即可在自己的工作区中安全、可控地完成一次跨版本升级。nx migrate 帮你自动化三件事保持工具链tooling时刻更新是维护任何项目中最繁琐、最耗时的工作之一。Nx 官方课程将nx migrate的核心价值概括为三点自动更新package.json依赖将目标包及其关联包升级到新版本无需手工改版本号迁移配置文件例如 Vite、Playwright、Nx 自身的配置都会按新版本要求的格式被自动改写调整源码以匹配新版本跨破坏性变更breaking changes时比如某个 API 改名或某个导入路径变更迁移会直接修改你的源代码。只需在项目根目录执行一条命令Nx 就会以交互方式引导你完成整个更新nx migrate从源码看该命令的入口定义在 command-object.tsnx migrate [packageAndVersion]既负责生成迁移文件也负责运行迁移两条子路径由--run-migrations等参数区分。工作原理插件声明迁移Nx 统一收集执行Nx 知道自己的配置文件位于何处并确保它们符合预期的格式。这个自动化更新过程通常被称为migration迁移。关键在于每个 Nx 插件都可以为自己擅长的领域提供迁移脚本。例如 Vite 插件会在跨破坏性变更时提供迁移来更新 Vite 配置文件。当你运行nx migrate时Nx 会从所有已安装插件中收集待执行的迁移pending migrations并把必要的变更应用到工作区。这一机制在仓库中可以直接验证每个插件在自己的migrations.json中声明迁移清单例如 packages/vite/migrations.json 中就有rename-rollup-options-to-rolldown-optionsVite 8 用 Rolldown 替换 Rollup 后把vite.config.ts中的rollupOptions重命名为rolldownOptions这样的真实迁移迁移清单的数据结构定义在 misc-interfaces.ts一个MigrationsJson由generators迁移生成器、schematics兼容旧命名和packageJsonUpdates依赖版本更新建议组成每条迁移条目包含version适用版本、implementation实现文件、description、可选的promptAI 提示文件等字段。以 packages/workspace/migrations.json 为例packageJsonUpdates展示了推荐依赖升级的写法——这里 Nx 建议把 TypeScript 从 5.7/5.8 升级到 5.8/5.9并通过x-prompt向用户确认{ generators: { 23-0-0-move-typescript-compilation-import: { version: 23.0.0-beta.10, description: Rewrites imports of nx/workspace/src/utilities/typescript/compilation to nx/js/internal, where the module now lives., implementation: ./dist/src/migrations/update-23-0-0/move-typescript-compilation-import } }, packageJsonUpdates: { 21.5.0: { version: 21.5.0-beta.2, x-prompt: Do you want to update to TypeScript v5.9?, requires: { typescript: 5.8.0 5.9.0 }, packages: { typescript: { version: ~5.9.2, alwaysAddToPackageJson: false } } } } }可以看到迁移是按version精确锚定的requires字段限定了适用前提如typescript 5.8.0 5.9.0只有满足条件时这条更新建议才会被纳入本次迁移。迁移的两阶段工作流先生成再运行更新 Nx 工作区分为两个阶段这也是理解整个nx migrate的关键Generate生成nx migrate把包版本更新应用到package.json并写出一个migrations.json文件。此时不触碰任何源码。Run运行nx migrate --run-migrations运行上一步生成的迁移更新配置文件与源码。两阶段之间你可以随时介入针对自己的具体工作区做出调整——在大代码库中这种生成与执行分离的设计让你能够更精细地控制变更范围。Step 1生成迁移运行migrate命令并按提示操作nx migrateNx 会解析最新版本并且当本次更新跨越超过一个大版本major version时询问你想一次跳多远。官方建议并推荐最稳妥的方式是一次只升级一个大版本详见 advanced-update.mdoc 中 One major version at a time 一节先升级到当前大版本的最新版运行迁移再进入下一个大版本如此往复。Nx 还会询问要迁移哪些包版本该答案对应--include参数required—— 目标包及其随附的包。例如 Nx 本身及其插件如nx/viteoptional—— 这些包推荐的依赖更新。例如vite本身而非nx/viteall—— 以上两者全部包含。拿不准时选required。只更新 Nx 及其插件可以让 PR 变更范围更小、出问题的概率更低这在大型工作区尤为重要。之后再用nx migrate --includeoptional补齐其余更新如果你接受在一个 PR 里完成所有事就用--includeall。有些情况下你还可以把optional 补课限定到单个插件的依赖例如nx migrate nx/vite --includeoptional关于该用法的注意事项见 advanced-update.mdoc 中 Choosing which packages to migrate 一节部分插件更新依赖其他插件先执行更新如nx/angular有时需要nx/js的 TypeScript 更新因此拿不准时建议直接跑完整的nx migrate --includeoptional。生成阶段结束后你会得到package.json已写入新版本号migrations.json已生成仅当存在待执行迁移时。此时尚未安装任何包也没有触碰其他文件。接下来先检查package.json确认改动是否合理——有时迁移会把某个包升到不被允许的版本或与另一个包产生冲突你可以在安装前自由调整版本号。确认无误后按你的包管理器安装依赖npm installyarn installpnpm installbun install同时打开migrations.json看看将要应用哪些迁移。如果该文件不存在说明没有需要运行的迁移。Step 2运行迁移执行上一步生成的迁移nx migrate --run-migrations一条迁移里有什么迁移逐条运行包含两种类型的变更基于生成器Generator-based又称 script-based程序化的配置或代码变更。例如 Vite 8 中把vite.config.ts的rollupOptions改为rolldownOptions——这正是 packages/vite/migrations.json 中rename-rollup-options-to-rolldown-options所做的事。基于提示Prompt-basedAI 辅助的变更。这类变更无法用确定性规则表达需要针对你的具体代码做判断。一条迁移可以是纯生成器、纯提示也可以是混合型先跑生成器、再由 AI 辅助完成剩余变更。运行过程纯生成器迁移会自动运行所有改动处于未暂存unstaged状态供你审阅。当队列中出现纯提示或混合型迁移、且系统安装了受支持的 AI AgentClaude Code、OpenAI Codex 或 OpenCode时Nx 会询问是否继续 agentic 流程。你可以选择仅本次生效也可以让 Nx 在nx.json中记住你的选择。开启 agentic 流程后先生成器式变更再由 Agent 校验结果然后 Agent 按提示指令应用基于提示的变更每条迁移都会单独创建一个 git commit这样 Agent 可以在隔离的 diff 中审阅每条迁移的改动。如果没有 Agent纯生成器迁移以及混合型迁移的生成器部分仍然会运行被跳过的提示文件会按顺序列在 next-steps 输出中方便你手动处理。在 AI Agent 的终端内运行时如果你在某个 AI Agent 的终端里执行nx migrate --run-migrationsNx 会把基于提示的迁移委托给该 Agent而不是再派生一个新的 Agent。迁移是版本特定的每个 Nx 插件只提供与特定版本相关的迁移。生成的migrations.json只包含适用于你当前这次升级的迁移。从源码看agentic 流程由 packages/nx/src/command-line/migrate/agentic 目录下的模块实现提示文件则统一存放在工作区的tools/ai-migrations目录见 prompt-files.ts 中的AI_MIGRATIONS_DIR定义。每个 Agent 的可选值claude-code、codex、opencode与参数校验规则定义在 command-object.ts。Step 3清理运行完所有迁移后可以删除migrations.json并提交剩余改动。需要注意的是建议保留migrations.json直到所有在迁移前创建的分支都合并完毕。保留该文件可以让其他开发者运行nx migrate --run-migrations把同样的迁移流程应用到他们新合并的代码上。Step 4更新社区插件可选如果你安装了 Nx 社区插件需要逐个迁移它们前提是它们提供了迁移脚本nx migrate my-plugin查看当前安装了哪些插件运行nx report在 nx.json 中配置 migrate 默认值与其每次运行都重复传相同的参数不如在工作区nx.json的migrate段中设置全局默认值。你可以控制提交行为、包选择、跨多版本处理方式以及 agentic 流程// nx.json { migrate: { agentic: claude-code, createCommits: true, commitPrefix: chore(repo): apply nx migration } }该配置项的类型定义在 nx-json.ts 的NxMigrateConfiguration中支持的选项包括配置项等价参数说明默认值createCommits--create-commits/-C每条迁移运行后自动创建 git commitfalsecommitPrefix--commit-prefix迁移 commit 的消息前缀chore: [nx migration]include--include限制迁移哪些包required/optional/allallmultiMajorMode--multi-major-mode跨多个大版本时的处理方式direct直达目标 /gradual先升到最小推荐步骤交互式询问agentic--agenticagentic 流程默认值false关闭、true自动解析已安装 Agent、或指定claude-code/codex/opencode交互式询问validate--validate/--no-validateagentic 流程开启时是否对纯生成器迁移做 Agent 驱动的校验trueuseRegistryResolution—是否通过 npm registry 解析版本更快环境变量NX_MIGRATE_USE_REGISTRY_RESOLUTION可覆盖true默认值的合并逻辑在 migrate-config.ts 的applyNxJsonMigrateDefaults中实现遵循命令行参数 环境变量 nx.json 内置默认值的优先级。例如multiMajorMode对应的NX_MULTI_MAJOR_MODE环境变量会优先于nx.json中的配置。完整的nx.json配置参考见 reference/nx-json.mdoc。保持所有 Nx 包版本同步运行nx migrate时nx包和所有nx/包会被更新到相同版本。保持这些版本同步对 Nx 正常工作至关重要具体原因和排查方法见 keep-nx-versions-in-sync.mdoc。只要坚持用nx migrate而不是手工改版本号你就不用担心同步问题。另外安装新插件时请使用nx add plugin它会自动安装与你仓库中 Nx 版本匹配的插件版本。官方插件的迁移生成器设计为幂等的重复运行等价于运行一次因此即使迁移中途重跑也不必担心重复应用。需要更多控制高级更新技巧当你需要偏离默认行为时——比如先跳过可选包更新、锁定或禁用某个 AI Agent、逐条运行迁移、或通过修改migrations.json跳过某条迁移——可以参考 Advanced Update Process 指南。其中几个高频场景如下逐条提交便于审阅。大型升级尤其是跨大版本会产生大量改动难以区分哪些是自动生成、哪些是手工调整。使用--create-commits让每条迁移单独成 commitnx migrate --run-migrations --create-commits默认 commit 前缀是chore: [nx migration]可用--commit-prefix自定义nx migrate --run-migrations --create-commits --commit-prefixchore(core): AUTOMATED - 手工调整migrations.json。两阶段分离的价值在大项目中尤为明显你可以注释掉、重排、跳过某条迁移甚至让同一条迁移跑多次比如长迁移过程中 rebase 之后。自定义迁移文件路径nx migrate --run-migrationsmigrations.json覆盖版本。想用与 Nx 推荐不同的包版本时nx migrate --tojest30.0.0,cypress15.0.0注意选择 Nx 未测试过的组合可能引入意外问题升级最好在干净的 git 历史中进行失败时可用git reset --hard与git clean -fd回滚使用--create-commits时需回退到第一条自动迁移 commit 之前的 SHA。小结nx migrate把升级依赖从手工劳动变成了一条可复现、可分阶段控制、可审阅的命令流生成Generate→ 检查 → 安装 → 运行Run→ 清理。插件生态通过migrations.json声明各自领域的迁移Vite、Workspace 都是现成范例Nx 负责收集并按版本精确执行对无法确定性表达的破坏性变更还能借助 Claude Code、Codex 或 OpenCode 以 agentic 流程辅助完成。配合nx.json的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),仅供参考
延伸阅读

更多相关文章

2026/9/10 0:51:02

LCD1602与C51单片机驱动实战:从时序原理到排错技巧

简介:这是一套面向C51单片机学习者与电子爱好者的LCD1602显示例程合集。例程围绕矩阵按键键值显示、DS18B20温度读取、DS1302时钟时间显示以及ADC0832电压转换这四类典型应用,演示了如何通过单片机控制字符型液晶屏将数据直观呈现,可直接借鉴…

2026/9/10 0:51:02

CTS测试AaptParser failed报错全解析:APK解析失败根源与修复

做CTS测试的人,应该都见过这类让人血压飙升的报错: AaptParser failed for file CtsCameraTestCases.apk. The APK wont be installed 。 这句话翻译成人话就是:测试框架尝试解析CtsCameraTestCases这个APK的时候失败了,所以这…

2026/9/10 1:36:07

STM32CubeMX+TouchGFX+QSPI组合实战:从环境配置到GUI联调全解析

简介:这份工程包面向使用 STM32CubeMX 与 TouchGFX 进行嵌入式 GUI 开发的工程师,解决将图片、字库这类超大数组从内部 Flash 搬运到外部 QSPI Flash(W25Q256)的典型问题。zip 包共 2000 个文件,核心代码以 652 个 .c …

2026/9/9 13:11:35

超人会飞不算本事:系统稳定依赖清晰规则与边界设计

开头先不绕弯子。“#斯坦李吐槽dc 所以超人是无缘无故会飞的嘛哈哈哈哈哈哈哈锤哥真是技术人才啊!#雷神 #复联”这类调侃式短标题,第一波冲击力在于它把两个宇宙的角色塞进同一个吐槽箱里,但细想一下就能发现,它真正碰到的根本不是…

2026/9/8 7:15:15

超人VS蜘蛛侠:拆解超级IP的影响力与传播方法论

把“蜘蛛侠 vs 超人”放在 CSDN 上聊,可能很多人第一反应是走错片场了。但如果把这两个角色看成“两个持续运营了 80 多年的文化产品”,你会发现,这场比较本质上是两个不同 IP 策略的长期结果对比:超人赢在定义了整个超级英雄题材…

2026/9/9 16:31:09

基于CNN的调制信号识别:MATLAB实现时频图分类实战

简介:本资源是一套面向通信工程与信号处理方向学习者、研究者的深度学习实践方案,聚焦调制信号自动检测与识别这一典型无线通信任务,解决传统方法依赖人工特征、低信噪比下性能下降等痛点。压缩包共12个文件(10.73MB)&…

2026/9/10 0:00:55

目录对比去重实战:用哈希算法精准清理重复文件

我电脑里现在还有一块换了三次机的“数据墓地”硬盘,里面存着2016年以前所有旧笔记本的完整备份。平时不觉得有什么,直到前阵子想把它整理归档,发现同一个安装包、同一批照片、同一份论文草稿,在几个不同的备份目录里反复出现。更…

2026/9/10 0:00:55

Leaflet离线地图完整Demo合集:内网部署与坐标纠偏实战

简介:这是一份面向Web GIS开发者的LeafLet离线地图示例合集,帮助开发者快速掌握离线地图从搭建到交互的完整流程。压缩包共723个文件,大小14.06MB,以319个js脚本、175个html页面和29个css样式文件为主体,配合png/svg图…

2026/9/10 0:00:55

MATLAB读取Rinex 3.02观测文件:多系统GNSS数据解析实战

简介:基于MATLAB开发的Rinex3.02版观测文件(o文件)读取代码包,面向卫星定位导航方向的学习者与研究人员,用于解决新版观测文件的数据解析、历元提取与时间转换问题。压缩包共4个文件,包含两个m脚本、一个19…

2026/9/7 16:23:03

USB Type-C PCB布局分区设计:电源、高速信号与PD协议全攻略

做硬件这行,Type-C接口算是典型的“看着简单,做起来全坑”的东西。光引脚就24个,高低速信号、电源、控制线全部塞在一个小小的连接器里,如果PCB布局不做规划,打样回来基本就是“插上没反应”、“高速掉线”、“静电一打…

2026/9/7 22:46:00

系统编程学习原型如何补齐稳定性边界

系统编程学习原型如何补齐稳定性边界预算有限时&#xff0c;我先优化明显多余的复制&#xff0c;而不是猜测性地换容器。用借用传递只读数据通常就能减少分配&#xff1a; fn parse(line: &str) -> Result<Item, Error> { /* ... */ }用基准确认热点确实在分配&am…

2026/9/9 10:21:54

雨花区哪家财务公司代理记账比较好?

在雨花区&#xff0c;企业处理财税事务常常面临诸多挑战&#xff0c;选择一家靠谱的财务公司至关重要。湖南巨勤财务管理咨询有限公司就是本地正规实体财税服务机构&#xff0c;深耕本地工商财税行业多年&#xff0c;熟悉当地工商局、税务局最新政策与申报流程。主营公司注册、…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
咨询二维码