nx-generate

运行 Nx 生成器

Nx 生成器是强大的工具，可用于搭建项目脚手架、执行自动化代码迁移，或在单体仓库中自动处理重复性任务。它们能确保代码库风格一致，并减少样板代码工作。

当用户想要：

• 创建新的项目，例如库或应用程序
• 搭建功能或样板代码
• 运行工作区专用或自定义生成器
• 执行 Nx 生成器能够完成的其他任何操作

生成器发现流程

步骤 1：列出可用的生成器

使用 Nx CLI 发现可用的生成器：

• 列出某个插件的所有生成器：npx nx list @nx/react
• 查看可用插件：npx nx list

其中包括：

• 插件生成器（例如，@nx/react:library、@nx/js:library）
• 本地工作区生成器（定义在仓库自己的插件中）

步骤 2：根据用户请求匹配生成器

根据用户的请求，确定哪些生成器可以满足需求。请考虑：

• 他们想创建的产物类型（库、应用程序等）
• 相关的框架或技术栈
• 他们是否提到了特定的生成器名称

重要：当本地工作区生成器和外部插件生成器都能满足请求时，始终优先使用本地工作区生成器。本地生成器针对特定仓库的模式和约定进行了定制。

用户请求可能确实没有任何 Nx 生成器能够满足。在这种情况下，你可以停止使用此技能，并尝试通过其他方式帮助用户。不过，要证明这一点并不容易。在放弃之前，请仔细考虑每一个可用的生成器，并深入了解所有可能相关的生成器。

执行前检查清单

运行任何生成器之前，请完成以下步骤：

1. 获取生成器 Schema

使用 --help 标志了解所有可用选项：

npx nx g @nx/react:library --help

请留意：

• 必须提供的必需选项
• 可能与用户请求相关的可选项
• 可能需要覆盖的默认值

2. 阅读生成器源代码

了解生成器的实际行为，有助于你：

• 知道将创建或修改哪些文件
• 了解任何副作用（更新配置、安装依赖等）
• 找出 Schema 中可能不明显的选项

查找生成器源代码：

• 对于插件生成器：使用 node -e "console.log(require.resolve('@nx/<plugin>/generators.json'));" 查找 generators.json，然后从中定位源代码
• 如果失败，直接读取 node_modules/<plugin>/generators.json
• 对于本地生成器：它们通常位于 tools/generators/ 或本地插件目录中。你可以在仓库中搜索生成器名称来查找。

2.5 重新评估生成器是否合适

了解所选生成器的行为后，请重新考虑：这个生成器是否适合满足用户的请求？ 如果不合适，可以返回生成器发现流程，在继续之前选择其他生成器。如果这样做，请务必再次完整执行执行前检查清单。

3. 了解仓库上下文

生成之前，请检查代码库中目标区域的情况：

• 查看类似的现有产物（其他库、应用程序等）
• 识别仓库中使用的模式和约定
• 记录命名约定、文件结构和配置模式
• 配置生成器时尽量遵循这些模式

例如，如果类似的库使用特定的测试运行器、构建工具或代码检查工具，请尽可能采用相同的工具。 如果项目或其他产物按照特定命名约定组织，请尽量遵循该约定。

4. 验证必需选项

确保所有必需选项都有值：

• 将用户的请求映射到生成器选项
• 尽可能根据上下文推断值
• 向用户询问任何关键缺失信息

执行

请注意，如果用户没有全局安装 nx，可能需要在命令前加上 npx/pnpx/yarn。 许多生成器的行为会因执行位置而异。例如，第一方 nx 库生成器会使用当前工作目录来确定库的放置目录。这一点非常重要。

考虑试运行（可选）

强烈建议先使用 --dry-run 运行，但并非必须。请自行判断：

• 对于复杂的生成器或不熟悉的情况：先进行试运行
• 对于简单且熟悉的生成器：可以直接执行
• 试运行会显示文件名以及创建/删除/修改标记，但不会显示内容
• 某些情况下，生成器不支持试运行（例如需要安装 npm 包时），此时 --dry-run 可能会失败。不要因此气馁，只需继续实际运行生成器，并在过程中迭代调整。

运行生成器

使用以下命令执行生成器：

nx generate <generator-name> <options> --no-interactive

重要：始终包含 --no-interactive，以防提示导致执行挂起。

示例：

nx generate @nx/react:library --name=my-utils --no-interactive

处理生成器故障

如果生成器失败：

1. 诊断错误——仔细阅读错误消息
2. 找出原因——缺少选项、值无效、冲突等
3. 尝试自动修复——调整选项或解决冲突
4. 重试——使用修正后的选项再次运行生成器

常见故障原因：

• 缺少必需选项
• 选项值无效
• 与现有文件冲突
• 缺少依赖项
• 生成器不支持某些标志组合

生成后

1. 修改生成的代码（如有需要）

生成器提供的是起点，但输出可能需要调整，以符合用户的特定要求：

• 按要求添加或修改功能
• 调整导入、导出或配置
• 与仓库中现有的代码模式集成

2. 格式化代码

对所有生成或修改的文件运行格式化程序：

nx format --fix

JavaScript/TypeScript 以外的语言可能还需要使用其他格式化命令。

3. 运行验证

验证生成的代码是否正常工作。具体方式取决于生成器类型和可用目标。 如果生成器创建了新项目，请直接运行该项目的目标。 请自行判断需要验证哪些内容。

示例：

nx lint <new-project>
nx test <new-project>
nx build <new-project>

4. 处理验证失败

验证失败时：

如果问题范围可控（少量 lint 错误、轻微类型问题）：

• 修复问题
• 重新运行验证以确认

如果问题较多（大量错误、复杂问题）：

• 先尝试简单且明显的修复
• 如果仍然失败，请向用户说明：
  • 生成了什么
  • 哪些验证未通过
  • 已尝试进行哪些修复
  • 还需要用户提供信息才能解决的问题

错误处理

生成器故障

• 查看错误消息，了解具体原因
• 确认已提供所有必需选项
• 检查是否与现有文件冲突
• 确保生成器名称和选项正确

缺少选项

• 查阅生成器架构，了解必需字段
• 在合理的情况下根据上下文推断值
• 对于无法推断的值，请向用户询问

核心原则

1. 优先使用本地生成器 - 如果工作区／本地生成器和外部插件生成器都可用，始终优先选择前者

2. 运行前先了解 - 阅读架构和源代码，充分了解将要发生的事情

3. 不要显示提示 - 始终使用 --no-interactive，以防命令挂起

4. 生成器只是起点 - 根据需要修改生成结果，充分满足用户需求

5. 验证更改是否有效 - 不要只生成代码；确保代码能够构建、通过 lint 检查和测试

6. 主动修复问题 - 不要只报告错误；在可能的情况下尝试自动解决

7. 遵循仓库中的模式 - 研究仓库中现有的类似代码，并遵循其惯例