需要创建或维护 Nx 的…

适用于在 TS/JS 项目中创建 Nx workspace、生成 app/lib/component、运行 affected/run-many、配置 CI/CD、Module Federation、NestJS 后端、远程缓存和依赖图调试。

适用场景

解决思路

1. 创建新 Nx workspace 时运行 `npx create-nx-workspace@latest`，按交互提示选择 preset（Integrated、Standalone、Package-based）和框架栈。
2. 在已有项目中初始化 Nx 时运行 `nx@latest init`。
3. 需要非交互式创建时运行 `npx create-nx-workspace@latest my-workspace --preset=react`；创建后用 `nx show projects` 验证新 workspace 项目列表。
4. 生成 React 应用：`nx g @nx/react:app my-app`。
5. 生成 React 库：`nx g @nx/react:lib my-lib`。
6. 生成 TypeScript 库：`nx g @nx/js:lib my-util`；生成后用 `nx show projects` 验证新 lib。
7. 在库中生成 React 组件：`nx g @nx/react:component my-comp --project=my-lib`。
8. 生成 NestJS 后端：`nx g @nx/nest:app my-api`；用 `nx show projects` 验证列出 my-api，并运行 `nx run my-api:build` 验证构建成功。
9. 仅对受影响项目运行任务：`nx affected -t lint test build`。
10. 对所有项目运行构建：`nx run-many -t build`。
11. 对指定项目运行测试：`nx run-many -t test -p=my-app,my-lib`。
12. 按模式运行测试：`nx run-many -t test --projects=*-app`。
13. 对单个项目运行特定 target：`nx run my-app:build`。
14. 可视化依赖图：`nx graph`。
15. 在每个项目的 `project.json` 中定义 targets、executor、configurations 和 tags，例如配置 name、projectType、sourceRoot、build.executor 为 `@nx/react:webpack`、outputs 为 `{workspaceRoot}/dist/apps/my-app`、production 配置 optimization 为 true、test.executor 为 `@nx/vite:test`、tags 为 `type:app` 和 `scope:frontend`。
16. 在 `targets.build` 中通过 `dependsOn` 设置项目依赖，例如 `{ projects: ['shared-ui'], target: 'build' }`。
17. 使用 tags 组织项目，例如 `['type:ui', 'scope:frontend', 'platform:web']`。
18. 生成 Module Federation remote：`nx g @nx/react:remote checkout --host=dashboard`。
19. 生成 Module Federation host：`nx g @nx/react:host dashboard`。
20. 在 CI 中使用 affected 命令只构建/测试变更项目，例如 `.github/workflows/ci.yml` 中运行 `npx nx affected -t lint --parallel`、`npx nx affected -t test --parallel`、`npx nx affected -t build --parallel`。
21. 创建 React 和 TypeScript 的 Nx workspace 时运行 `npx create-nx-workspace@latest my-workspace`，选择 Integrated Monorepo → React → Integrated monorepo (Nx Cloud)；验证 `cd my-workspace && nx show projects` 列出创建的应用；预期得到 apps/、libs/、nx.json 和 CI/CD workflow 文件。
22. 仅对最近变更项目运行测试时使用 `nx affected -t test --base=main~1 --head=main`；预期只执行受影响项目测试并利用之前运行的缓存。
23. 生成共享 UI 库：`nx g @nx/react:lib shared-ui`。
24. 在共享 UI 库中生成组件：`nx g @nx/react:component button --project=shared-ui`。
25. 在应用中导入共享库组件：`import { Button } from '@my-workspace/shared-ui'`，tsconfig paths 会自动配置；用 `nx run shared-ui:build` 验证构建成功，并用 `nx graph` 查看依赖链接。
26. 创建 Module Federation host app：`nx g @nx/react:host dashboard`。
27. 向 host 添加 remote：`nx g @nx/react:remote product-catalog --host=dashboard`。
28. 启动 Module Federation 开发服务器：`nx run dashboard:serve` 和 `nx run product-catalog:serve`；验证两个服务器启动，且 `nx graph` 显示 dashboard → product-catalog remote 连接。
29. 调试无关 lib 变更导致 app 重建时，先运行 `nx graph --focused=my-app` 查看项目图。
30. 检查隐式依赖：`nx show project my-app --json | grep implicitDependencies`。
31. 解决构建依赖问题：添加显式依赖配置，或在 `nx.json` 中使用 `namedInputs` 排除某些文件触发构建。
32. 验证依赖修复：修改无关 lib，运行 `nx affected -t build`，确认 `my-app` 不出现在受影响项目列表中。
33. 在 CI 中始终使用 `nx affected`，只测试/构建变更项目。
34. 按领域或业务能力组织 libs，而不是按技术层组织。
35. 一致使用 tags，例如 `type:app|lib`、`scope:frontend|backend|shared`。
36. 在 `nx.json` 中配置 `workspaceLayout` 边界，防止循环依赖。
37. 使用 Nx Cloud 启用远程缓存以提升团队效率。
38. 保持 `project.json` 简单，尽量使用 `nx.json` 中的默认值。
39. 优先使用 generators 而不是手动创建文件，以保持一致。
40. 配置 `namedInputs`，从生产缓存键中排除测试文件。
41. 使用 Module Federation 实现微前端独立部署。
42. 将 workspace generators 保留在 `tools/` 中，用于项目特定脚手架。
43. 使用 Nx 17+ 前确保 Node.js 18.10+。
44. Windows 用户使用 WSL 或 Git Bash 执行命令以获得最佳体验。
45. 首次设置时预留较长时间用于包安装。
46. 大型 monorepo（50+ 项目）使用分布式任务执行。
47. 使用 Module Federation 前确保 webpack 5+ 并完成特定 Nx 配置。
48. 运行某些 generators 前先安装所需额外插件。
49. 如果默认缓存目录 `~/.nx/cache` 过大，在 `nx.json` 中配置 `cacheDirectory`。
50. 出现循环依赖导致构建失败时，使用 `nx graph` 可视化并定位。
51. 在 Integrated、Standalone、Package-based 之间迁移 preset 时，预留手动调整工作。
52. 按主题查阅参考文件：`references/basics.md` 了解 workspace setup 和 basic commands。
53. 按主题查阅 `references/generators.md` 了解 app、lib、component 生成器。
54. 按主题查阅 `references/react.md` 了解 React、Next.js、Expo 模式。
55. 按主题查阅 `references/nestjs.md` 了解 NestJS 后端模式。
56. 按主题查阅 `references/typescript.md` 了解 TypeScript packages。
57. 按主题查阅 `references/ci-cd.md` 了解 GitHub、CircleCI 等 CI/CD。
58. 按主题查阅 `references/advanced.md` 了解 caching、affected、advanced。

适用边界 · 注意事项

• Node.js 版本低于 18.10 时，Nx 17+ 不适用。
• Windows 环境未使用 WSL 或 Git Bash 时，不建议按本经验操作。
• Module Federation 场景缺少 webpack 5+ 或相应 Nx 配置时，不适用。