掌握 Nx Generators:从脚手架到自动迁移的代码生成实战指南
掌握 Nx Generators:从脚手架到自动迁移的代码生成实战指南
导读
Nx Generators 是 Nx Monorepo 平台的核心能力之一,用于搭建项目骨架、执行自动化代码迁移以及消除仓库内的重复性劳动,从而保证整个代码库的一致性。本文将基于 Nx 仓库中面向 AI Agent 的 nx-generate 技能文档,系统讲解如何发现、选择、执行 Nx Generator,并结合当前仓库中的真实源码(本地 workspace generator 与插件 generator 的定义与 schema)深入剖析生成器的底层工作方式,帮助你(或你的 Agent)在任何 Nx 工作区中安全、规范地生成代码并完成验证。
Nx Generator 是什么
Nx generators(生成器)是 Nx 提供的强大工具,它的典型用途包括:
- 搭建新项目(如应用 application、库 library);
- 为功能或样板代码生成脚手架(如 React 组件、hook、Storybook 配置);
- 运行工作区专属的自定义生成器;
- 执行自动化的代码迁移(migrations);
- 自动化任何重复性任务,减少样板工作量。
生成器确保了代码库中每个新建产物的结构、命名和配置都遵循同一套约定,避免"每个开发者各写各的"。
从本仓库源码来看,一个生成器由三部分共同定义:generators.json(声明生成器条目)、factory 实现文件(实际执行逻辑)、schema.json(描述可接受的选项)。例如本地插件 tools/workspace-plugin/generators.json 中声明了两个生成器:
{
"generators": {
"remove-migrations": {
"factory": "./src/generators/remove-migrations/generator",
"schema": "./src/generators/remove-migrations/schema.json",
"description": "remove-migrations generator"
},
"bump-maven-version": {
"factory": "./src/generators/bump-maven-version/generator",
"schema": "./src/generators/bump-maven-version/schema.json",
"description": "Bump Maven plugin version and create migration"
}
}
}
而插件型生成器同样遵循此结构,例如 packages/react/generators.json 中声明了 init、application(别名 app)、library(别名 lib)、component(别名 c)、hook 等 React 专属生成器,以及面向 Module Federation 的 consumer / provider 生成器。生成器通常还带有别名(aliases),方便命令行短写,例如 npx nx g @nx/react:lib 等价于 @nx/react:library。
使用 Generator 的核心原则
在执行任何生成器之前,先记住四条关键原则,它们能显著提升生成结果的正确性:
- 始终使用
--no-interactive:阻止生成器抛出交互式提示导致执行挂起,这对无人值守的 CLI 与 Agent 场景尤其重要; - 阅读生成器源码:仅看 schema 远远不够,必须理解生成器实际做了什么(创建/修改了哪些文件、有什么副作用);
- 匹配仓库既有模式:先研究仓库中已有的同类产物,遵循其命名、目录结构与配置惯例;
- 用 lint / test / build / typecheck 等验证:生成的代码必须通过验证。所列 target 只是示例,应使用该工作区实际合适的验证命令。
从发现到执行:Generator 的完整操作流程
1. 发现可用生成器
使用 Nx CLI 发现工作区中可用的生成器:
# 列出某个插件提供的全部生成器
npx nx list @nx/react
# 查看工作区中已安装的插件
npx nx list
这些生成器既包括插件生成器(如 @nx/react:library),也包括本地工作区生成器(如当前仓库 tools/workspace-plugin/generators.json 中定义的 bump-maven-version、remove-migrations)。
2. 将生成器与用户需求匹配
确定哪些生成器能满足需求,考虑的因素包括:想要的产物类型(app 还是 lib)、涉及的框架、以及用户提到的具体生成器名称。
关键规则:当一个本地工作区生成器与一个外部插件生成器都能满足需求时,优先选择本地工作区生成器。因为本地生成器是针对当前仓库的模式定制过的,最贴合仓库惯例。
如果确实没有合适的生成器,可以停止使用本技能。但在下结论前,务必仔细审视所有可用生成器——"没有合适生成器"的举证门槛很高。
3. 查看生成器的可用选项
用 --help 了解生成器的全部选项:
npx nx g @nx/react:library --help
重点关注:必填选项、可能需要覆盖的默认值、以及与用户需求相关的选项。
schema 是选项的第一手来源。以本地生成器 tools/workspace-plugin/src/generators/bump-maven-version/schema.json 为例,它声明了两个必填选项:
newVersion:要升级到的 Maven 插件版本(如'0.0.10'),并带正则约束^\d+\.\d+\.\d+$;nxVersion:迁移对应的 Nx 版本(如'22.1.0-beta.7'),用于确定下一次迁移应跟随的版本号。
schema 还提供了 required 字段(此处两个选项都必填)和 examples 字段,帮助理解调用方式:
npx nx g bump-maven-version --newVersion=0.0.10 --nxVersion=22.1.0-beta.7
这展示了 schema 是如何约束生成器调用参数的——Agent 在执行生成器前阅读 schema 即可获知所有合法选项、类型与校验规则。
4. 阅读生成器源码(关键步骤)
这一步至关重要。 schema 不会告诉你全部信息,阅读源码能帮你:
- 精确知道哪些文件会被创建/修改、创建在哪里;
- 理解副作用(更新配置、安装依赖等);
- 发现 schema 中不明显的行为与选项;
- 理解选项之间如何互相影响。
如何定位生成器源码:
- 插件生成器:用
node -e "console.log(require.resolve('@nx/<plugin>/generators.json'));"找到 generators.json,再顺藤摸瓜定位源码; - 若上一步失败,直接读取
node_modules/<plugin>/generators.json; - 本地生成器:通常在
tools/generators/或本地插件目录下(如本仓库的 tools/workspace-plugin/src/generators),或在仓库中按生成器名称搜索。
读完成源码后要重新评估:这真的是合适的生成器吗?如果不是,回到第 2 步重新选择。
⚠️ --directory 标志的行为容易误导。 它应指定生成产物的完整路径,而不是父目录:
# ✅ 正确 - directory 是库的完整路径
nx g @nx/react:library --directory=libs/my-lib
# 生成 libs/my-lib/package.json 等文件
# ❌ 错误 - 这会把文件创建在 libs 和 libs/src/... 下
nx g @nx/react:library --name=my-lib --directory=libs
# 生成 libs/package.json 等文件
5. 研究仓库既有模式
在生成之前,先检查目标区域:
- 查看相似的既有产物(其他库、应用等);
- 识别命名约定、文件结构与配置模式;
- 注意工作区使用的测试运行器、构建工具和 lint 工具;
- 据此配置生成器选项以匹配这些模式。
例如当前仓库的 @nx/react 生成器同时支持 Vite、Rsbuild 和 Rspack(见 packages/react/generators.json 中 consumer / provider 的描述),选用哪个 bundler 需要依据仓库既有配置决定。
6. 先用 Dry-Run 验证文件落点
始终先运行 --dry-run,验证文件将被创建在正确位置:
npx nx g @nx/react:library --name=my-lib --dry-run --no-interactive
仔细审查输出。如果文件会落在错误位置,依据第 4 步读源码获得的认知调整选项。
注意:部分生成器不支持 dry-run(例如会安装 npm 包的那种)。若 dry-run 因此失败,可以直接真实运行生成器。
7. 执行生成器
正式执行:
nx generate <generator-name> <options> --no-interactive
提示:新建的包往往需要接通工作区依赖(例如导入共享类型、被应用消费)。此时可借助 link-workspace-packages 技能正确添加这些依赖关系。
8. 按需修改生成的代码
生成器提供的是起点,之后可按需修改:
- 按需求增改功能;
- 调整导入、导出或配置;
- 与既有代码模式集成。
重要:如果替换或删除了生成的测试文件(如 *.spec.ts),要么写出有意义的替代测试,要么从项目配置中移除 test target——空的测试套件会导致 nx test 失败。
9. 格式化并验证
格式化所有生成/修改的文件:
nx format --fix
此命令示例针对内置的 prettier 格式化;若工作区使用其他格式化工具,应改用对应工具。
随后验证生成的代码可用。注意:生成器或后续修改可能影响多个项目,因此通常不能只对刚创建的产物运行 target:
# 这些 target 只是示例!
nx run-many -t build,lint,test,typecheck
这些是许多工作区通用的典型 target。应调研该工作区及其项目可用的其他 target——CI 配置通常是判断哪些关键 target 必须通过的最佳指南。
如果验证失败且问题可控(少量 lint 错误、轻微类型问题),直接修复;如果问题较多,先尝试明显修复,再向用户详细说明:生成了什么、什么失败了、尝试过什么。
库的构建能力选择:Buildable vs Non-buildable
默认选择非可构建(non-buildable)库,除非有特定理由需要可构建(buildable)。
| 类型 | 适用场景 | 生成器参数 |
|---|---|---|
| Non-buildable(默认) | 供应用消费的 monorepo 内部库 | 不加 --bundler 参数 |
| Buildable | 发布到 npm、跨仓库共享、需要缓存命中的稳定库 | --bundler=vite 或 --bundler=swc |
Non-buildable 库:
- 直接导出
.ts/.tsx源码; - 由消费方的 bundler 编译;
- 开发体验更快、配置更少。
Buildable 库:
- 拥有自己的 build target;
- 适合极少变化的稳定库(可获得缓存命中);
- 是 npm 发布的前提条件。
如果不确定,直接询问用户:"这个库应该是 buildable(独立构建步骤、更好缓存)还是 non-buildable(源码被直接消费、配置更简单)?"
底层原理:Generator 的执行机制
从源码结构可以推断,Nx 生成器体系建立在 Devkit 之上。Devkit 提供了生成器运行时的标准工具函数,例如 generateFiles(基于模板批量渲染文件)位于 packages/devkit/src/generators/generate-files.ts。生成器内部通常会:
- 读取并校验 schema 中声明的选项;
- 调用
generateFiles等 devkit API 渲染模板文件到目标目录; - 更新相关配置文件(project.json、package.json 等)并安装依赖;
- 返回生成结果摘要。
--dry-run 之所以能预览而不落盘,是因为 Nx 的生成器执行层(packages/nx/src/command-line/generate)在 dry-run 模式下收集所有将要执行的写入操作并仅打印输出,而不真正写入文件系统。这也解释了为什么那些"安装了 npm 包"的生成器无法 dry-run——副作用超出了文件写入的范畴。
在真实的 Nx 仓库中,生成器不仅是脚手架工具,还被大量用于自动化迁移:例如本仓库的 bump-maven-version 生成器(tools/workspace-plugin/src/generators/bump-maven-version/generator.ts)在升级 Maven 插件版本的同时生成面向用户的迁移脚本,这正是"生成器 = 脚手架 + 自动迁移 + 重复任务自动化"三位一体的最好例证。
实战清单:一次完整的 Generator 使用
将上述流程压缩为一份可复用的执行清单:
npx nx list发现可用生成器,或npx nx list <plugin>查看指定插件;- 优先选择本地 workspace generator,其次才是外部插件 generator;
npx nx g <generator> --help查看选项,阅读对应schema.json确认必填项与校验规则;- 阅读生成器源码(factory + schema),确认文件落点与副作用;
- 检查目标目录既有产物,匹配仓库命名与配置模式;
- 运行
--dry-run --no-interactive验证文件落点; - 正式执行
nx generate <generator> <options> --no-interactive; - 按需修改生成代码(若删除测试文件,需补写替代测试或移除 test target);
nx format --fix格式化,随后用 CI 中的关键 target 验证(如nx run-many -t build,lint,test,typecheck),失败则修复或上报。
这套流程既适用于人类开发者手工操作,也完整适用于 AI Agent 的自动化执行——--no-interactive、源码阅读与 dry-run 验证正是保证 Agent 生成结果安全可靠的三道防线。