Nx 23 迁移指南将nx/vite/plugin的createNodesV2导入重命名为createNodes【免费下载链接】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 23 将nx/vite的推断插件主导出从createNodesV2正式更名为createNodes旧的createNodesV2名称仅作为废弃别名保留。本指南围绕 迁移说明文档 展开完整讲解这条自动化迁移的触发方式、重写范围、别名与去重等边界行为并结合 迁移实现源码 与 单元测试 深入剖析其 AST 级重写原理。读完本文你将清楚这条迁移改了什么、没改什么、为什么这样改并掌握在需要时手工清理残余createNodesV2用法的完整清单。迁移背景为何要把createNodesV2更名为createNodesNx 的插件系统长期存在两个并行的推断接口createNodes旧版接收解析后的配置路径数组与createNodesV2新版直接接收文件路径列表具备更完整的缓存与依赖收集能力。随着createNodesV2逐步成为事实标准nx/vite在 Nx 23 中将createNodes提升为插件的主导出名称语义上与 Nx 全局的插件接口命名保持一致。从当前仓库源码可以确认这一改名不是简单的删除在 packages/vite/src/plugins/plugin.ts#L182 中createNodesV2被显式定义为createNodes的别名保证旧名继续可用export const createNodesV2 createNodes;packages/vite/plugin.ts 作为包入口同时重新导出createNodes与createNodesV2供迁移前后的代码共存。因此迁移本身不是破坏性的即使你不运行迁移旧的createNodesV2导入依然能正常工作它只是引导新代码统一使用规范名createNodes为后续彻底移除废弃别名铺路。迁移如何触发与注册这条迁移以 Nx 标准迁移migration generator的形式发布注册在 packages/vite/migrations.json#L57-L62update-23-0-0-migrate-create-nodes-v2-import: { version: 23.0.0-beta.24, description: Rename imports of createNodesV2 from nx/vite/plugin to the canonical createNodes export., implementation: ./dist/src/migrations/update-23-0-0/migrate-create-nodes-v2-to-create-nodes, documentation: ./dist/src/migrations/update-23-0-0/migrate-create-nodes-v2-to-create-nodes.md }这意味着它随 Nx 的自动迁移机制触发。在包含nx/vite的工作区中升级到 Nx 23该迁移的最低版本为23.0.0-beta.24后执行标准的nx migrate流程nx migrate latest nx migrate --run-migrationsNx 会读取迁移配置自动在当前工作区运行该迁移并对命中的文件逐一重写。迁移完成后它会打印类似下面的统计信息Renamed createNodesV2 imports to createNodes in N file(s).该日志由 migrate-create-nodes-v2-to-create-nodes.ts#L54-L58 中的logger.info输出其中 N 为实际被修改的文件数。迁移的核心行为扫描与重写扫描范围迁移入口函数migrateCreateNodesV2ToCreateNodes通过visitNotIgnoredFiles(tree, .)遍历工作区中所有未被忽略的文件仅处理以下四种 TypeScript 扩展名见 实现源码 L23-L24.ts.tsx.cts.mts其余文件如.md、.js、.json一律跳过——测试用例does not rewrite non-TS files验证了这一点docs/example.md中的createNodesV2文本不会被触碰。此外文件内容中若根本不含createNodesV2字符串也会被快速跳过L44-L46。匹配条件仅限nx/vite/plugin的具名绑定重写并非见名就改。目标模块说明符被硬编码为一个集合TARGET_SPECIFIERS new Set([nx/vite/plugin])L30只有从nx/vite/plugin导入/再导出的具名绑定才会被改写。测试用例对此有明确约束从其他模块导入import { createNodesV2 } from nx/other-plugin/plugin→ 不改写相对路径导入import { createNodesV2 } from ./plugin→ 不改写从nx/vite/plugin导入但与createNodesV2无关的绑定如import { createNodes }→ 不改写。三种典型改写场景根据 官方迁移文档 与源码具名导入/导出的改写分为三种情况1. 单独导入createNodesV2改写前import { createNodesV2 } from nx/vite/plugin;改写后import { createNodes } from nx/vite/plugin;2. 别名导入Alias 保留改写前import { createNodesV2 as cn } from nx/vite/plugin;改写后import { createNodes as cn } from nx/vite/plugin;注意只改导入来源名as左侧本地别名cn保持不变。由于本地绑定名未变文件体内对cn的所有引用都无需改动见 L189-L197 的测试。3. 同时导入createNodes与createNodesV2去重改写前import { createNodes, createNodesV2 } from nx/vite/plugin;改写后import { createNodes } from nx/vite/plugin;冗余的createNodesV2绑定被直接丢弃即使createNodesV2排在前面的{ createNodesV2, createNodes }同样会被正确去重。多行书写的具名导入每行一个绑定也会被统一规整为单行{ ... }形式。此外以下几种形式同样受支持均有测试覆盖默认导入与具名导入共存import def, { createNodesV2 } from nx/vite/plugin→import def, { createNodes } from nx/vite/plugin默认绑定不动纯类型导入import type { createNodesV2 } ...与行内type修饰符import { type createNodesV2 } ...均保留type关键字具名再导出export { createNodesV2 } from nx/vite/plugin与export { createNodesV2 as cn } ...同样被改写冗余别名折叠import { createNodesV2 as createNodes } ...会坍缩为import { createNodes } ...。深入源码AST 级的精准重写为什么必须解析 AST 而不是字符串替换迁移文档强调只重写静态的具名导入/导出绑定而createNodesV2字符串可能以各种面目出现在源码中注释、字符串字面量、属性访问、对象键名等。字符串替换无法区分这些场景因此实现借助 TypeScript Compiler API 将文件解析为 AST 后按节点类型精确处理。核心函数是rewriteCreateNodesV2ImportsL69-L104整体流程为用ts.createSourceFile将源码解析为语法树以TSX脚本类型解析兼顾.tsx文件遍历顶层语句对ImportDeclaration调用collectImportRewrite对ExportDeclaration调用collectExportRewrite收集所有StringChange删除 插入编辑点若某个非别名的createNodesV2本地绑定被真正重命名即文件作用域内名字发生了变化再调用collectValueUsageRewrites同步重写文件体内对该绑定的一切值引用最后通过applyChangesToString一次性应用所有编辑。这样既保证了import/export关键字、模块说明符、默认导入等不被误伤也保证了改动是局部最小的。绑定重写与去重的实现细节rewriteNamedBindingsL173-L212负责重渲染{ ... }花括号内的绑定列表用renderSpecifier逐个序列化绑定无别名时直接把名字从createNodesV2换成createNodes有别名时只换as左侧若换名后别名变得多余createNodesV2 as createNodes则折叠为createNodes用seen集合做去重当列表同时含有createNodes与createNodesV2时后者因渲染结果相同而被丢弃最后用删除整个花括号段 插入新花括号段的方式生成编辑不触碰模块说明符与语句其余部分。值得留意的是renderSpecifier对type修饰符的处理L214-L232每个绑定前的type前缀都会被保留因此import { type createNodesV2 }会规整地变成import { type createNodes }。值引用同步重写最容易被忽略的部分这是整个迁移中最精巧的设计。文档中改一个 import 名看似简单但当非别名的createNodesV2绑定被重命名后文件体内所有对它的值引用都会悬空。因此只有当localBindingRenamed为真时collectValueUsageRewrites才会扫描文件体把游离的createNodesV2标识符一并改名。isRenamableValueUsageL280-L317精确定义了哪些标识符必须跳过这些规则与迁移文档中不重写清单一一对应导入/导出声明自身的绑定位置已由声明级改写处理属性访问x.createNodesV2、config.createNodesV2——这里createNodesV2是成员名而非绑定限定类型名Foo.createNodesV2对象字面量键{ createNodesV2: 1 }——键名应保留遮蔽绑定的声明名const createNodesV2 ...、函数/类声明名、参数名、解构绑定元素——这些是新的局部绑定不应被改。此外还有一个巧妙的特例简写属性。若代码为export const plugins { createNodesV2 }直接把标识符改成createNodes会让对象键意外从createNodesV2变成createNodes语义变化。实现会将其展开为{ createNodesV2: createNodes }保留键名、只改值L265-L267。测试用例renames value usages of a lone createNodesV2 import和expands a shorthand property usage to preserve the key分别验证了这些行为。明确的不重写范围What is not rewritten根据 迁移文档 的What is not rewritten一节以下形式的createNodesV2不会被自动改写但会继续正常工作因为运行时别名createNodesV2 createNodes仍然存在形式示例是否改写命名空间导入import * as plugin from nx/vite/plugin否动态导入const m await import(nx/vite/plugin)否require解构const { createNodesV2 } require(nx/vite/plugin)否属性访问plugin.createNodesV2否通配再导出export * from nx/vite/plugin否字符串/注释createNodesV2、// import { createNodesV2 } ...否以上行为全部有对应测试佐证例如does not rewrite require() destructuring (still valid via alias)——require解构保留因为运行时别名仍可用leaves createNodesV2 in strings and comments alone——字符串与注释中的文本不受影响does not rewrite export * from declarations——export *没有具名绑定可改leaves property accesses and strings while renaming the binding——config.createNodesV2与字符串createNodesV2在绑定被改名后依然原样保留。如果你希望在 Nx 23 中彻底告别废弃名这些场景需要手工更新。建议的清理顺序是优先运行自动迁移处理静态具名导入/导出用仓库级搜索如rg createNodesV2找出残余匹配逐一检查残余命中是否属于上表列出的形式手工将plugin.createNodesV2改为plugin.createNodes、将require解构改为从nx/vite/plugin具名导入createNodes等。测试驱动迁移正确性的保障迁移的正确性由 migrate-create-nodes-v2-to-create-nodes.spec.ts 中 20 余个用例保障测试分两组单元测试组rewriteCreateNodesV2Imports直接对纯字符串输入调用重写函数并断言输出覆盖单独导入改名、同语句其他绑定保留、别名改写、冗余别名折叠、双向去重、多行导入规整、默认导入共存、import type与行内type、具名再导出含别名、异构模块说明符不误改、export *不改、字符串/注释/require保留、值引用同步改名、函数实参中的改名、简写属性展开、属性访问与字符串保留、别名导入时文件体不改名等场景。集成测试组migration runner通过createTreeWithEmptyWorkspace()构造虚拟工作区验证迁移在Tree上的端到端行为在libs/foo/src下同时放置a.ts、b.tsx、c.cts、d.mts四种扩展名文件迁移后各自的导入/导出均被正确改写证明扫描覆盖全部四种 TS 扩展名不含废弃名的文件内容保持不变非 TS 文件如.md中的createNodesV2文本不被触碰。这些测试同时充当了迁移行为的活文档读者在手工处理残余场景时可以直接以测试中的输入输出对照为准则。小结迁移后的状态检查完成nx migrate --run-migrations后建议做如下验证确认日志迁移运行时应输出Renamed createNodesV2 imports to createNodes in N file(s).N 为修改文件数搜索残余rg createNodesV2应仅命中上表列出的不重写范围场景若有验证构建运行nx run-many -t build或你的常规校验命令确认改名后的工作区一切正常——createNodesV2运行时别名仍在 plugin.ts 中生效任何遗漏的引用都不会直接报错这也是迁移可以安全进行的根本原因规划清理如需彻底移除废弃名按上文清单手工更新残余用法并留意后续 Nx 版本中废弃别名可能的移除公告。最后补充一点本文介绍的重写逻辑是针对nx/vite/plugin的迁移若你的工作区中其他插件如nx/workspace/plugin也存在createNodesV2导出它们不在此迁移的改写范围内请以各插件自身的迁移配置为准。【免费下载链接】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），仅供参考
