Nx-cloud配置

Nx Cloud 远程缓存与分布式任务执行配置

#resource / nodejs #type / howto #status / seed

Nx Cloud 配置

基础概念

Nx Cloud 是 Nx 构建系统的云服务，核心功能：

远程缓存（Remote Cache）：将构建/测试产物缓存到云端，团队成员共享缓存结果，避免重复构建
分布式任务执行（Distributed Task Execution, DTE）：将任务分发到多台机器并行执行，大幅缩短 CI 时间
运行分析：可视化查看任务执行时间、缓存命中率等指标

使用指南

连接 Nx Cloud

在 monorepo 项目根目录执行：

# 自动连接 Nx Cloud 并生成 access token
npx nx connect

执行后会在 nx.json 中添加 nxCloudAccessToken 配置，同时在 .env 或 CI 环境变量中设置 token。

手动配置

登录 nx.app，创建组织和 workspace
获取 Access Token
在 nx.json 中配置：

{
  "nxCloudAccessToken": "your-token-here"
}

或通过环境变量：

# .env
NX_CLOUD_ACCESS_TOKEN=your-token-here

CI 流水线集成

GitHub Actions 示例

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci

      # 使用 Nx Cloud 分布式执行
      - run: npx nx affected -t lint test build --parallel=3
        env:
          NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}

启用分布式任务执行

# 在 CI 中使用分布式执行（需要 Nx Agents）
npx nx-cloud start-ci-run --distribute-on="3 linux-medium-js"

这会将任务自动分配到 3 个云 agent 上并行执行。

验证配置

# 查看远程缓存是否生效
npx nx run <project>:<target> --verbose

# 查看缓存命中率
npx nx-cloud status

# 测试缓存：先运行一次，改代码前再运行应看到缓存命中
npx nx affected -t build
# 第一次：全部执行
# 不改代码再运行：应显示 [remote cache]

实战经验

查看缓存效果

在 CI 日志中关注以下标志：

[from cache] — 使用了本地缓存
[from remote cache] — 使用了远程缓存
无标记 — 重新执行了任务

常见问题

问题	原因	解决
缓存始终未命中	输入文件 hash 变化、依赖版本浮动	检查 `nx.json` 的 `namedInputs` 配置
Token 无效	过期或权限不足	重新 `npx nx connect` 或在 nx.app 重新生成
DTE 任务分配不均	任务粒度太粗	拆分大型 target，使用 `--parallel`

经验总结

远程缓存是最容易落地的优化，推荐优先启用
分布式执行适合大型 monorepo，小项目收益不明显
CI 中务必通过 secrets 管理 token，不要硬编码

信息参考

[[nx|Nx]]
Monorepo MOC