Nx 连接 Nx Cloud 实战：为 Tasker Monorepo 开启远程缓存与分布式 CI-编程实验室

Nx 连接 Nx Cloud 实战：为 Tasker Monorepo 开启远程缓存与分布式 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

本篇技术指南聚焦 Nx 课程系列中的关键一步——将 Nx 工作区连接到 Nx Cloud。你将以课程中的 Tasker（基于 Next.js 的 PNPM workspace 单体仓库）为例，掌握推送仓库、创建 Nx Cloud 工作区、关联 GitHub 仓库的完整流程，理解连接成功后远程缓存（Remote Caching）与分布式 CI（Distributed Task Execution）如何被激活，并拿到可直接落地的 GitHub Actions 配置。

Nx 与 Nx Cloud 的分工：从"智能单体仓库"到"快速构建"

课程中对二者的定位非常清晰：Nx 负责"Smart Monorepos"（智能单体仓库），Nx Cloud 带来"Fast Builds"（快速构建）。Nx 本身已经提供了任务编排、本地缓存、依赖图与 affected 计算等能力，让大规模单体仓库在本地开发时保持高效；而 Nx Cloud 则将这种效率延伸进 CI 管线——它为 Nx 提供远程缓存（跨机器共享任务结果）与分布式任务执行（跨多台 Agent 机器并行运行任务），确保即使是很庞大的单体仓库，在 CI 中也始终能保持快速且经过优化。

课程的最终目标也围绕这一点展开：将 Tasker 这个 PNPM workspace monorepo 推送到 GitHub，在 Nx Cloud 上创建一个工作区，并把 Nx Cloud 工作区与 GitHub 仓库关联起来。完成这一连接后，你的 Nx 工作区就具备了远程缓存与分布式 CI 的能力，为后续课程中"把 Playwright e2e 测试从 20 分钟压缩到 9 分钟"的优化打下基础（课程大纲见 course.md）。

连接前的准备工作：确保 Nx 已就位

在连接 Nx Cloud 之前，需要先确认 Nx 已经正确安装在你的工作区中。连接本身不会为你安装 Nx，远程缓存、affected、任务分发等能力只有在nx真正接管任务执行时才会生效。

对于 Tasker 这类已有 PNPM workspace 的存量仓库，课程（01-nx-init.md）给出了两种方式：

手动方式：将nx包加入package.json，并手动创建 nx.json 配置文件；
推荐方式：直接运行初始化命令，它会分析仓库结构并询问少量问题，在保留原有 PNPM workspace 结构的前提下完成 Nx 配置：

nx init

官方设置 CI 的指南（setup-ci.mdoc）也给出了等价的命令形式npx nx@latest init；如果是全新仓库，则可以直接用npx create-nx-workspace@latest起步。关键判定依据是：仓库根目录存在nx.json且package.json的 devDependencies 中包含nx，说明 Nx 已经就位。

连接流程三步走：推送 → 创建工作区 → 关联仓库

这是课程（06-nx-cloud-setup.md）的核心实操环节，完整流程如下：

第一步：将 Tasker monorepo 推送到 GitHub

Nx Cloud 工作区需要与一个远程仓库建立关联，因此首先要保证你的仓库已经推送到 GitHub（或其他支持的 Git 托管平台）。如果尚未推送，先在本地完成提交并推送：

git add . git commit -m "chore: prepare workspace for Nx Cloud" git push -u origin main

第二步：创建并连接 Nx Cloud 工作区

连接方式有两种，任选其一：

网页方式：打开 Nx Cloud 的 Web 应用（对应文档 nx-cloud.mdoc 中描述的https://cloud.nx.app/get-started流程），选择"创建新仓库"或"连接已有仓库"，按引导完成 GitHub 授权。官方称该流程通常只需 2 分钟。
命令行方式：在已推送到远程的 Nx 工作区根目录执行：

nx connect

nx connect会引导你完成同样的授权流程。对于希望由 Agent 或脚本自动化执行的场景，setup-ci.mdoc 中还给出了npx nx-cloud onboard connect-workspace命令，它以 JSON 形式返回结果：

运行npx nx-cloud onboard connect-workspace并解析返回的 JSON；
如果响应中包含actionRequired载荷（典型情况是 GitHub 授权），需要按提示完成授权后再继续，不要盲目重试；
确认nxCloudId已写入根目录的nx.json——这是连接成功的标志；若未写入，应检查返回的 JSON 错误信息。

第三步：关联 GitHub 仓库并验证

在 Nx Cloud Web 界面中，将新创建的工作区与你推送的 GitHub 仓库完成关联。此时可以打开nx.json确认nxCloudId字段已经生成——从源码实现的角度看，nxCloudId就是 Nx 与 Nx Cloud 建立信任关系的唯一标识，本地与 CI 中的nx命令都会依据它来定位远程缓存与任务编排服务。

完成上述三步后，工作区即处于"已连接"状态，可以开始使用远程缓存与分布式 CI 能力。

连接之后：远程缓存与分布式 CI 如何生效

连接成功并非终点，而是起点。Nx Cloud 带来的三项核心能力各有其生效前提：

远程缓存：跨机器共享任务结果

Nx Cloud 内置了强大的远程缓存能力。只要 CI（或本地开发者机器）通过nx运行任务，任务执行结果就会被上传到云端缓存；其他机器（或后续的 CI 运行）执行相同输入的任务时，会直接命中缓存而跳过实际执行。课程配套图片对比了缓存命中与未命中的差异——命中缓存时任务几乎是瞬时完成，未命中时才需要真实执行：

要保证缓存生效，一个容易被忽略的前提是：CI 必须调用nx来运行任务。官方文档（setup-ci.mdoc）明确说明：nx test没问题，npm test只要内部包裹了nx test也没问题，但直接调用jest、tsc、eslint等原始工具会绕过 Nx Cloud。因此现有 CI 脚本中的裸工具调用都应替换为：

# .github/workflows/ci.yml - run: npx nx run-many -t lint test build

nx run-many -t <task>用于运行多个项目的同名任务，nx run <project>:<task>则针对单个项目。

只运行受影响的任务：nx affected

连接 Nx Cloud 后，还可以用nx affected只运行被本次变更影响到的项目的任务，进一步压缩 CI 时间：

# .github/workflows/ci.yml - uses: actions/checkout@v7 with: fetch-depth: 0 - run: npx nx affected -t lint test build

这里fetch-depth: 0是关键：Nx 依赖完整 Git 历史来计算变更范围，通过NX_BASE与NX_HEAD两个环境变量确定比较区间。在 PR 上，Nx 将分支与nx.json中defaultBase指定的基线分支（默认main）比较；在推送到main时，则与上一个提交比较。

分布式任务执行：Nx Agents

在.nx/ci-config.yaml中声明 Agent 数量与启动模板，再用start-nx-agents启动任务分发：

# .nx/ci-config.yaml dte: distribute-on: 3 linux-medium-js

# .github/workflows/ci.yml - run: npx nx-cloud start-nx-agents - run: npx nx affected -t lint test build

任务分发与远程缓存协同工作，并且支持对 Playwright、Vitest 等测试工具进行任务级拆分（这正是课程第 12 课将 e2e 测试耗时减半的技术基础）。Nx Cloud 采用基于任务而非静态分配机器的 CI 模型（详见 nx-cloud.mdoc）：Agent 在 setup 步骤失败时，工作会自动重新分配到其他 Agent；工作增多时，加 Agent 机器即可自动扩展；已知的 flaky 任务会被自动识别并重跑。

为 CI 配置远程缓存的读写权限

远程缓存涉及跨团队共享，访问控制至关重要。课程第 8 课（08-remote-caching.md）专门讲解了在 Nx Cloud 工作区中创建 access token，为 GitHub Actions 授予远程缓存的读/写访问权限——CI 必须持有 token 才能读写远程缓存，这也是连接过程中需要完成的配套动作。

同样，开发者本地机器访问远程缓存则通过**个人访问令牌（PAT）**实现（见 10-nx-login.md）：在 Nx Cloud 中为 PAT 配置细粒度权限，决定开发者是只读使用远程缓存结果，还是同时具备写入（贡献缓存）的能力，然后在本机执行：

pnpm nx login

生成 CI 工作流：从手动替换到一键生成

课程第 7 课（07-optimize-ci.md）演示了用生成器快速替换 Tasker 现有的基于pnpm --filter的 GitHub Actions 脚本：

pnpm nx g ci-workflow

对应的完整形式是nx g @nx/workspace:ci-workflow --ci=<provider>，其中<provider>支持github、circleci、gitlab、azure、bitbucket-pipelines（见 setup-ci.mdoc）。生成器会自动接线 CI 任务运行器、远程缓存与nx fix-ci。另外，由于nx.json中的namedInputs参与了缓存指纹计算，修改 CI 配置文件后应确保缓存能正确失效，避免 CI 脚本变更后仍命中旧缓存。

完整 CI 参考：四合一流水线

下面是将远程缓存、affected、分布式执行与自愈 CI（nx fix-ci）整合在一起的完整 GitHub Actions 流水线（来自 setup-ci.mdoc）：

# .nx/ci-config.yaml dte: # 使用 linux-medium-js 启动模板分发到 3 个 Agent distribute-on: 3 linux-medium-js lifecycle: # 所有 build 任务被请求后关闭空闲 Agent stop-after: - build

# .github/workflows/ci.yml name: CI on: push: branches: - main pull_request: permissions: actions: read contents: read jobs: main: runs-on: ubuntu-latest steps: # fetch-depth: 0 让 Nx 拥有计算变更所需的完整历史 - uses: actions/checkout@v7 with: fetch-depth: 0 filter: tree:0 # 启动 .nx/ci-config.yaml 中声明的 Agent。 # 放在安装依赖之前，让 Agent 在安装期间完成启动。 - run: npx nx-cloud start-nx-agents - uses: actions/setup-node@v6 with: node-version: 24 cache: 'npm' - run: npm ci # 仅对本次变更影响到的项目运行 lint、test、build， # 由 Nx Cloud 分发到上面启动的 Agent 上执行。 - run: npx nx affected -t lint test build # 分析上述失败并自动提出修复方案。 # if: always() 确保即使任务失败也会执行——这正是它存在的意义。 - run: npx nx fix-ci if: always()

其中npx nx fix-ci是"自愈 CI"的入口：当任务失败时，Nx Cloud 会分析失败原因（如 flaky 测试、配置漂移等）并提出可在 GitHub 或 Nx Cloud 界面一键应用的修复建议。

小结与延伸阅读

连接 Nx Cloud 是课程"From PNPM Workspaces to Distributed CI"的分水岭：连接之前，Nx 解决的是本地任务编排与缓存；连接之后，远程缓存、affected、分布式执行与自愈 CI 才真正进入 CI 管线。整个课程（course.md）的推进路径也印证了这一点：添加 Nx → 配置本地缓存 → 定义任务管线 → 通过 Nx Cloud 启用远程缓存 → 调整 CI 实现任务分发 → 拆分并行化 Playwright e2e 测试，最终把执行时间从 20 分钟降到 9 分钟。

如需继续深入，仓库内可参考的权威资料包括：

Getting Started / Setup CI：完整的 CI 接入指南，含 Agent、access token、各 CI 平台差异说明；
Getting Started / Nx Cloud：Nx Cloud 的定位、任务型 CI 执行模型与连接方式；
课程第 7、8、10 课：07-optimize-ci.md、08-remote-caching.md、10-nx-login.md，分别覆盖 CI 命令替换、远程缓存读写 token 与开发者本机登录认证。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考