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-workspaceyarn 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.tsTemplate 流程--template从nrwlGitHub 组织下的模板仓库如nrwl/react-template直接下载模板。源码会先做严格的正则校验/^nrwl\/[\w.-]$/防止路径穿越再下载模板、删除模板自带的package-lock.json以重新生成适配所选包管理器的锁文件最后执行依赖安装。create-workspace.ts中内置了四个简写映射create-workspace.tsangular→nrwl/angular-template、react→nrwl/react-template、typescript→nrwl/typescript-template、empty→nrwl/empty-template因此可以直接写npx create-nx-workspace --templatereact。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-workspacelatest --templatenrwl/tanstack-start-template每个模板本质上都是一个已接线完成的工作 monorepo项目间依赖已配置、缓存已开启、任务管线已就绪创建完成后可以直接运行任务。常用命令行参数速查下表汇总了create-nx-workspace常用选项参数定义集中在 yargs-options.ts完整字段注释见 create-workspace-options.ts参数别名说明默认值--packageManager/--pm--pm指定包管理器pnpm / yarn / npm / bun自动探测描述默认值为 npm--template—指定 GitHub 模板仓库或内置简写名无进入交互选择--nxCloud--ci是否接入 Nx Cloudyes/github/gitlab/azure/bitbucket-pipelines/circleci/skip/never交互询问--useGitHub—是否使用 GitHub 作为 Git 托管平台影响 Nx Cloud 引导流程false--defaultBase—新建项目的默认基线分支名main--skipGit-g跳过初始化 Git 仓库false--skipGitHubPush—跳过通过 gh CLI 推送到 GitHubfalse--interactive—是否启用交互式提示true--allPrompts-a显示全部提示false--analytics—是否共享使用数据以改进 Nx交互询问--verbose-v开启详细日志false--commit.name/--commit.email/--commit.message—初始提交的作者与提交信息提交信息默认为Initial commit其中--nxCloud的取值类型NxCloud在 nx-cloud.ts 中定义。需要注意的是第三方预设默认需要二次确认才能安装--trustThirdPartyPreset可跳过确认这是为了防止一个与 Nx 无关的同名 npm 包被静默安装。创建后的收尾链路格式化、Git 与 Nx Cloudcreate-nx-workspace并非只生成文件就结束createWorkspace()create-workspace.ts在脚手架完成后还会依次执行四个收尾动作理解这条链路有助于排查创建过程中的异常格式化创建工作区全程在NX_SKIP_FORMATtrue环境下进行待依赖落盘后统一执行一次nx format --all收尾格式化因为此时 Git 尚未初始化没有可对比的基线所以使用--all。若格式化失败工具会明确提示工作区创建成功但文件未格式化并给出在仓库内运行nx format:write的补救建议。Git 初始化默认--skipGitfalse在目录中执行git init并提交初始 commitdefaultBase决定基线分支名若指定了--commit.name/email/message则使用对应作者信息提交。GitHub 推送仅在已提交 未跳过推送 CI 提供商为 GitHub 或选择nxCloudyes三个条件同时满足时才通过ghCLI 推送到 GitHub推送失败不会让整个创建流程失败工具会输出Push your repo to GitHub之类的引导提示。Nx Cloud 接入除非选择skip或never工具会读取 Nx Cloud token、生成 onboarding URL、按需在浏览器中自动打开配置页并把短链接写入新工作区的 READMEnever选项会在nx.json中写入永不再连接的标记。从源码结构看createWorkspace对 SIGINTCtrlC也做了兜底处理工作区完整安装完成后才记录目录状态避免中断产生半成品目录相关状态读取函数为getInterruptedWorkspaceState()。把 Nx 引入既有仓库npx nx init对于已经存在的 npm/pnpm/yarn 工作区或普通单包仓库无需推倒重建。Nx 提供了一行命令的增量式接入方案npx nxlatest init该命令由nx init子命令实现其 yargs 定义位于 command-object.ts。命令的核心动作是安装nx依赖、生成/更新nx.json配置文件、扫描现有package.json脚本并推断缓存策略可选地配置 Nx Cloud 远程缓存。nx init的设计目标就是不改动现有脚本、不改变既有工作流只做增量叠加——这一点与创建新工作区是互补的两条路径。nx init 支持的常用选项nx initv2 流程支持以下参数见 command-object.ts参数说明默认值--nxCloud是否设置 Nx Cloud 分布式缓存交互询问--interactive设为false时禁用交互式提示适合 CI 自动化true--useDotNxInstallation在当前仓库的.nx目录中初始化 Nx 工作区配置false--plugins要安装的插件skip表示不装all表示安装全部检测到的插件或逗号分隔的插件列表如nx/vite,nx/jest交互检测--cacheable逗号分隔的可缓存操作列表如build,test,lint—--aiAgents要配置的 AI Agent 列表claude/codex/copilot/cursor/gemini/opencode/none交互询问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时才写入defaultBaseutils.ts。命令还内置了对不同存量场景的适配实现从源码目录结构可以看出的目标场景包括普通 npm 仓库add-nx-to-npm-repo.ts、已有 monorepoadd-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_PLUGINSfalse或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 stepsnx 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跟随交互选择名称与起始模板确定技术栈后可加--templatename跳过交互。存量仓库执行npx nxlatest initNx 会以最小侵入的方式识别现有脚本、配置缓存与依赖顺序必要时用--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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考