Nx 23 迁移指南将nx/devkit中废弃的 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导读在 Nx 23 中nx/devkit导出的插件 API 类型正式去掉了V2后缀CreateNodesV2变为CreateNodesNxPluginV2变为NxPlugin等旧名称仅以deprecated别名形式保留。Nx 为此提供了一条自动化迁移它会扫描工作区中所有.ts、.tsx、.cts与.mts文件把从nx/devkit导入与再导出的这些V2类型重写为规范名称同时保留别名、去重冗余绑定、同步更新函数体内的类型引用。读完本文你将掌握 Nx 23 插件类型重命名的完整映射、迁移的底层实现原理基于 TypeScript AST 的文本重写以及如何在你的工作区中安全地执行并验证这条迁移。为什么 Nx 23 要移除V2后缀Nx 插件系统的CreateNodesAPI 自引入以来经历了多次演进早期版本中CreateNodes的形态与CreateNodesV2不同因此以V2后缀区分版本。在 Nx 23 中插件 API 的类型已经稳定规范类型不再需要版本后缀规范类型CreateNodes、CreateNodesContext、CreateNodesResultArray、CreateNodesFunction、NxPlugin废弃别名对应的CreateNodesV2、CreateNodesContextV2、CreateNodesResultV2、CreateNodesFunctionV2、NxPluginV2仍以deprecated标注的别名保留供旧代码过渡使用新代码应使用规范名称。从源码看这些废弃别名在 packages/nx/src/project-graph/plugins/public-api.ts 中定义为规范类型的别名并带有deprecated注释例如/** * deprecated - use {link CreateNodes} instead */ export type CreateNodesV2T unknown CreateNodesT; /** * deprecated This will be removed in Nx 24. See {link CreateNodesContext} */ export type CreateNodesContextV2 CreateNodesContext;这些类型通过 packages/nx/src/devkit-exports.tsexport type * from ./project-graph/plugins/public-api再导出到 packages/devkit/index.tsexport * from nx/src/devkit-exports最终成为nx/devkit的公开 API。完整的类型重命名映射表迁移对以下五个类型的命名导入与命名再导出执行重写映射关系与 migrations.json 中的描述 及实现中的CREATE_NODES_V2_TYPE_RENAMES常量完全一致见 rename-create-nodes-v2-types.ts废弃名称nx/devkit规范名称CreateNodesV2CreateNodesCreateNodesContextV2CreateNodesContextCreateNodesResultV2CreateNodesResultArrayCreateNodesFunctionV2CreateNodesFunctionNxPluginV2NxPlugin特别留意第三行CreateNodesResultV2重命名为CreateNodesResultArray而非CreateNodesResult——CreateNodesResult是另一个不相关的类型描述单个项目的配置结果对象迁移不会触碰它。这一点在实现注释和测试中都有明确约定rename-create-nodes-v2-types.ts、rename-create-nodes-v2-types.spec.ts。迁移的扫描范围与重写规则该迁移注册于 packages/devkit/migrations.json版本为23.0.0-beta.24。它会遍历工作区中所有未被忽略的文件visitNotIgnoredFiles仅处理以.ts、.tsx、.cts、.mts结尾的文件常量TS_EXTENSIONS见 实现源码只重写模块说明符为nx/devkit的命名导入import { ... }与命名再导出export { ... } from nx/devkit——从nx/devkit/internal等其它说明符导入的同名类型不会被改动仅处理命名绑定不修改模块说明符、import/export关键字、type修饰符以及默认导入重写完成后对改动的文件调用formatFiles统一格式化保证代码风格一致。一个重要的快速跳过优化对每个候选文件迁移先检查其内容是否包含子串V2不包含则直接跳过实现源码。代码变化示例迁移前Beforeimport type { CreateNodesV2, CreateNodesContextV2 } from nx/devkit;迁移后Afterimport type { CreateNodes, CreateNodesContext } from nx/devkit;再看一个真实插件场景——带泛型参数的函数类型与上下文参数注解也会被同步更新// 迁移前 import { CreateNodesV2, CreateNodesContextV2 } from nx/devkit; export const createNodesV2: CreateNodesV2ComposerPluginOptions [x, () ({})]; async function fn(context: CreateNodesContextV2) {}// 迁移后 import { CreateNodes, CreateNodesContext } from nx/devkit; export const createNodesV2: CreateNodesComposerPluginOptions [x, () ({})]; async function fn(context: CreateNodesContext) {}上述场景由测试用例 renames generic type usages and parameter annotations 覆盖见 rename-create-nodes-v2-types.spec.ts。别名、重复绑定与特殊场景的处理迁移在重写时遵循一套细粒度规则均由单元测试逐一验证见 rename-create-nodes-v2-types.spec.ts别名被保留import type { CreateNodesV2 as CN }变成import type { CreateNodes as CN }本地绑定名CN不变冗余别名被折叠import type { CreateNodesV2 as CreateNodes }变成import type { CreateNodes }重命名后导入名与本地名相同as别名自然消失重复绑定被去重同一行同时导入{ CreateNodes, CreateNodesV2 }时冗余的CreateNodesV2绑定被丢弃结果仅保留{ CreateNodes }函数体内的引用被同步更新对于未使用别名的导入import { CreateNodesV2 }本地绑定名随之改变因此类型注解、泛型参数等函数体内部引用也会一并重写避免出现悬空引用而别名导入as CN不会触发函数体重写因为本地名未变成员位置不重写foo.CreateNodesV2、NS.CreateNodesV2这类属性访问或限定名中的CreateNodesV2不是对导入绑定的独立引用保持原样字符串与注释不触碰字符串字面量CreateNodesV2和注释中的示例代码不会被误改。实现原理基于 TypeScript AST 的文本重写核心函数rewriteCreateNodesV2Types(source: string): string使用 TypeScript 编译器 API 实现见 rename-create-nodes-v2-types.ts通过ensurePackage(typescript, typescriptVersion)按需加载 TypeScript 编译器与 Nx 声明的版本保持一致用ts.createSourceFile解析源码并开启setParentNodes从而支持从子节点回溯父节点遍历语句分别对ImportDeclaration与ExportDeclaration收集重写变更collectImportRewrite/collectExportRewrite对命名绑定列表整体重新渲染rewriteNamedBindings将整个{ ... }区间删除并按新内容插入重渲染时保留type内联修饰符与别名同时通过seen集合去重若存在未别名的导入导致本地绑定改名则用collectUsageRewrites遍历函数体重写所有对该绑定的独立引用——isRenameableReference会排除属性访问、限定名以及 import/export 声明内部的位置避免二次处理最终用applyChangesToString一次性把收集到的删除/插入变更应用到源码字符串上。这种整块重渲染 局部字符串变更的方式避免了逐个字符的脆弱替换也保证了多行导入、内联type修饰符import { type NxPluginV2, readJson }等复杂写法都能被正确处理。如何在你的工作区中执行这条迁移确保工作区升级到 Nx 23至少为23.0.0-beta.24之后的版本该迁移已注册在 packages/devkit/migrations.json 中使用 Nx 官方迁移流程触发npx nx migrate nx/devkit # 迁移命令会生成迁移列表确认包含 rename-create-nodes-v2-types 后执行 npx nx migrate --run-migrationsmigrations.json迁移运行后终端会输出类似Renamed deprecated CreateNodes V2 type imports from nx/devkit in N file(s).的日志见 实现源码说明改动过的文件数量由于迁移最后会调用formatFiles统一格式化你可以直接检查 git diff 确认改动范围再运行类型检查与测试验证。迁移后检查清单全仓库搜索CreateNodesV2|CreateNodesContextV2|CreateNodesResultV2|CreateNodesFunctionV2|NxPluginV2确认剩余出现仅为deprecated声明本身在 public-api.ts 中或注释、字符串等非代码位置确认CreateNodesResult不带V2未被误改——它是不相关的类型运行tsc或nx run-many -t build验证类型检查通过特别关注被重写文件中的函数体类型引用是否同步更新如果你的插件直接使用了NxPlugin对象中的createNodesV2字段请注意该字段本身在 public-api.ts 中也被标注为deprecated Prefer createNodes for new plugins——新代码应改用createNodes字段。相关资源迁移文档原文rename-create-nodes-v2-types.md迁移实现rename-create-nodes-v2-types.ts迁移单元测试rename-create-nodes-v2-types.spec.ts规范类型定义与废弃别名声明public-api.ts迁移注册信息packages/devkit/migrations.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/nx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考