Nx 快速入门：用 create-nx-workspace 创建 Monorepo 工作区与 nx init 改造存量仓库

Nx 快速入门：用 create-nx-workspace 创建 Monorepo 工作区与 nx init 改造存量仓库

【免费下载链接】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 仓库中scripts/readme-fragments/content.md这段 README 片段展开，聚焦两条最核心的入场路径：用create-nx-workspace从零创建全新的 Nx Monorepo 工作区，以及用nx init把 Nx 增量式地引入既有仓库。读完本文，你将掌握三种创建命令的等价关系与推荐选择、nx init对存量项目的侵入方式与关键参数，并能从源码层面理解脚手架背后"模板下载 → 依赖安装 → Git 初始化 → Nx Cloud 接入"的完整执行链路。

创建 Nx 工作区：三条等价的命令

create-nx-workspace是 Nx 官方提供的交互式脚手架命令，它会通过命令行提示依次询问工作区名称、起始模板、包管理器、是否接入 Nx Cloud 等选项，然后生成一个"开箱即用"的 monorepo。该命令的本体源码位于 packages/create-nx-workspace，其包内 README 模板 readme-template.md 通过{{content}}占位符嵌入了本文所讲解的这段内容。

关联文档给出的三种调用方式在功能上完全等价，区别只在于由哪个工具驱动create-nx-workspace包：

# 方式一：通过 npx 直接运行（最通用，也是官方文档默认展示的方式） npx create-nx-workspace # 方式二：通过 npm init 简写形式 npm init nx-workspace # 方式三：通过 yarn create 简写形式 yarn create nx-workspace

从实现角度看，npm init nx-workspace等价于npx create-nx-workspace，yarn create nx-workspace等价于yarn dlx create-nx-workspace：包管理器会临时拉取并执行create-nx-workspace这个 npm 包，因此三条命令最终进入的是同一个入口。建议做法是：使用 npm 就用方式一或二，使用 Yarn 就用方式三，确保与自身包管理器生态一致。

命令启动后进入交互流程，核心交互点是工作区名称与起始模板，这一交互逻辑定义在 prompts.ts 中。工作区名称会同时作为生成的根目录名与nx.json中的组织标识；若传入.或./，则启用useCurrentDir语义——直接在当前目录原地脚手架（此时会放宽空目录检查，与已有文件冲突时由生成的同名文件覆盖），相关选项定义见 create-workspace-options.ts。

支持的包管理器

create-nx-workspace内置识别 pnpm、yarn、npm、bun 四种包管理器（见 package-manager.ts），既可通过--packageManager（别名--pm）显式指定，也可省略参数让工具自动探测。指定的包管理器会被用于安装依赖并生成对应的工作区锁文件。

起始模板（Starter Template）与预设（Preset）

创建流程支持两种产物来源，入口逻辑见 create-workspace.ts：

• Template 流程（--template）：从nrwlGitHub 组织下的模板仓库（如nrwl/react-template）直接下载模板。源码会先做严格的正则校验（/^nrwl\/[\w.-]+$/）防止路径穿越，再下载模板、删除模板自带的package-lock.json以重新生成适配所选包管理器的锁文件，最后执行依赖安装。create-workspace.ts中内置了四个简写映射（create-workspace.ts）：angular→nrwl/angular-template、react→nrwl/react-template、typescript→nrwl/typescript-template、empty→nrwl/empty-template，因此可以直接写npx create-nx-workspace --template=react。
• Preset 流程（默认，不传--template时）：在临时沙箱中先创建一个空工作区，再由内部生成器按所选预设写入对应框架的初始化代码。全部内建预设定义在 preset.ts 的Preset枚举中，包括angular-monorepo、angular-standalone、react-monorepo、react-standalone、vue-monorepo、vue-standalone、nuxt、next、react-native、expo、nest、express、node-monorepo、node-standalone、web-components、ts-standalone、apps、npm、ts等。

官方文档 start-new-project.mdoc 中还展示了跳过交互、直接指定模板的写法，例如：

npx create-nx-workspace@latest --template=nrwl/tanstack-start-template

每个模板本质上都是一个"已接线完成"的工作 monorepo：项目间依赖已配置、缓存已开启、任务管线已就绪，创建完成后可以直接运行任务。

常用命令行参数速查

下表汇总了create-nx-workspace常用选项，参数定义集中在 yargs-options.ts，完整字段注释见 create-workspace-options.ts：

其中--nxCloud的取值类型NxCloud在 nx-cloud.ts 中定义。需要注意的是：第三方预设默认需要二次确认才能安装（--trustThirdPartyPreset可跳过确认），这是为了防止一个与 Nx 无关的同名 npm 包被静默安装。

创建后的收尾链路：格式化、Git 与 Nx Cloud

create-nx-workspace并非只生成文件就结束，createWorkspace()（create-workspace.ts）在脚手架完成后还会依次执行四个收尾动作，理解这条链路有助于排查创建过程中的异常：

1. 格式化：创建工作区全程在NX_SKIP_FORMAT=true环境下进行，待依赖落盘后统一执行一次nx format --all收尾格式化（因为此时 Git 尚未初始化，没有可对比的基线，所以使用--all）。若格式化失败，工具会明确提示"工作区创建成功但文件未格式化"，并给出在仓库内运行nx format:write的补救建议。
2. Git 初始化：默认（--skipGit=false）在目录中执行git init并提交初始 commit，defaultBase决定基线分支名；若指定了--commit.name/email/message则使用对应作者信息提交。
3. GitHub 推送：仅在"已提交 + 未跳过推送 + CI 提供商为 GitHub 或选择nxCloud=yes"三个条件同时满足时，才通过ghCLI 推送到 GitHub；推送失败不会让整个创建流程失败，工具会输出"Push your repo to GitHub"之类的引导提示。
4. Nx Cloud 接入：除非选择skip或never，工具会读取 Nx Cloud token、生成 onboarding URL、按需在浏览器中自动打开配置页，并把短链接写入新工作区的 README；never选项会在nx.json中写入永不再连接的标记。

从源码结构看，createWorkspace对 SIGINT（Ctrl+C）也做了兜底处理：工作区完整安装完成后才记录目录状态，避免中断产生半成品目录，相关状态读取函数为getInterruptedWorkspaceState()。

把 Nx 引入既有仓库：npx nx init

对于已经存在的 npm/pnpm/yarn 工作区或普通单包仓库，无需推倒重建。Nx 提供了一行命令的增量式接入方案：

npx nx@latest init

该命令由nx init子命令实现，其 yargs 定义位于 command-object.ts。命令的核心动作是：安装nx依赖、生成/更新nx.json配置文件、扫描现有package.json脚本并推断缓存策略，可选地配置 Nx Cloud 远程缓存。nx init的设计目标就是"不改动现有脚本、不改变既有工作流"，只做增量叠加——这一点与创建新工作区是互补的两条路径。

nx init 支持的常用选项

nx init（v2 流程）支持以下参数（见 command-object.ts）：

nx init 究竟改了什么

从 utils.ts 的createNxJsonFile()实现（utils.ts）可以看到nx init生成nx.json的具体策略，这也是理解其"低侵入"承诺的关键：

• targetDefaults自动推导：对拓扑型脚本（如build、test这类下游依赖上游产物、需要按依赖顺序执行的任务）写入dependsOn: ["^<scriptName>"]，实现"受影响才执行"的依赖感知；对可缓存操作写入cache: true，把现有脚本的输出纳入 Nx 缓存体系。
• outputs记录：若脚本带有明确输出目录，会以{projectRoot}/<output>形式写入outputs，供缓存命中判定使用。
• defaultBase推断：通过deduceDefaultBase()检测仓库的默认分支，只有推断结果不是 Nx 默认的main时才写入defaultBase（utils.ts）。

命令还内置了对不同存量场景的适配实现，从源码目录结构可以看出的目标场景包括：普通 npm 仓库（add-nx-to-npm-repo.ts）、已有 monorepo（add-nx-to-monorepo.ts）、Nest 项目（add-nx-to-nest.ts）、Turborepo 项目（add-nx-to-turborepo.ts，并配套createNxJsonFromTurboJson()将 turbo.json 配置迁移为nx.json）以及 Angular 工作区等。此外，nx init会根据环境变量与配置自动在 v1/v2 两套实现间切换：当NX_ADD_PLUGINS=false或nx.json中useInferencePlugins为false时走 v1 路径（command-object.ts）。

在 AI Agent 场景下使用

值得强调的是，nx init的 v2 流程显式支持--aiAgents参数，可一次性为 Claude Code、OpenAI Codex、GitHub Copilot、Cursor、Gemini、OpenCode 等主流 Agent（完整枚举见 create-workspace-options.ts）写入工作区认知配置，让 AI 工具理解仓库的任务结构与执行方式。这是 Nx "同时面向开发者与 AI Agent 的 Monorepo 平台"定位在 CLI 层面的直接体现，官方文档 ai-setup.mdoc 对这类集成有进一步说明。

创建完成后的第一组命令

无论走哪条路径，工作区就绪后都可以用下面这组命令快速验证（官方文档 start-new-project.mdoc 中的"Next steps"）：

nx build <project-name> # 执行一次构建任务 nx build <project-name> # 再次执行，命中缓存，秒级返回 nx run-many -t build test # 在所有项目中批量执行 build 与 test nx graph # 可视化项目依赖图

nx graph会启动一个本地可视化面板展示项目间依赖关系，run-many -t则是跨项目批量跑任务的标准入口。

延伸学习资源

关联文档还列出了 Nx 的官方学习入口，包括 Nx 官方文档站（Docs / Guides / Tutorials）、Nx 入门介绍、官方 YouTube 频道以及博客文章。除外部资源外，本仓库内还有两条更贴近源码的进阶路径：

• astro-docs/src/content/docs/getting-started 下的系列指南（如 crafting-your-workspace.mdoc、setup-ci.mdoc）覆盖从创建工作区到配置 CI 的完整链路；
• create-nx-workspace的单元测试（create-workspace.spec.ts、prompts.spec.ts）与nx init的测试（init-v2.spec.ts）展示了上述行为如何被逐一验证。

总结

• 全新项目：执行npx create-nx-workspace（或npm init nx-workspace/yarn create nx-workspace），跟随交互选择名称与起始模板；确定技术栈后可加--template=<name>跳过交互。
• 存量仓库：执行npx nx@latest init，Nx 会以最小侵入的方式识别现有脚本、配置缓存与依赖顺序，必要时用--plugins、--cacheable、--nxCloud定制行为。
• 验证就绪：用nx build（观察缓存命中）、nx run-many -t build test、nx graph确认工作区配置正确。

两条路径共享同一套核心收益：任务缓存、受影响的增量执行、可插拔的框架插件体系，以及从本地到 CI 的平滑扩展能力。

【免费下载链接】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