跳到主要内容
api工厂
工程化

Turborepo/Nx 增量构建与远程缓存:monorepo CI 提速

api工厂资讯栏目 约 5 分钟阅读
本文由 AI 辅助生成,内容基于公开资讯整理改写,技术细节以官方文档为准。
内容摘要解析任务图与输入指纹的增量构建原理,给出 turbo.json 配置、受影响分析与远程缓存接入要点,附 Turborepo 与 Nx 选型对照表。

结论先行:monorepo CI 提速的关键不是换更快的机器,而是「不算没变的、不跑没影响的」——Turborepo 与 Nx 都通过任务图 + 输入指纹实现增量构建,再把缓存搬到远端共享,让 CI 直接复用同事或上一次流水线的产物。配置得当,十几个包的仓库可以把全量构建压缩到只构建两三个受影响的包。 本文讲清原理、最小配置与远程缓存落地。

增量构建的原理:任务图与指纹

两个工具的共同模型是:把 build、test、lint 声明为任务(task),用 dependsOn 描述任务间依赖(如先构建上游包再构建下游应用),形成有向无环图。每个任务执行前计算指纹:源文件、依赖锁文件、环境变量、上游任务产物哈希共同决定缓存键。指纹命中则直接回放缓存的产物与日志,未命中才真正执行。因此「缓存失效」问题几乎都能归结为 inputs 声明不准:把无关文件纳入指纹会导致永远 miss,漏掉关键文件则可能回放过期产物。

Turborepo 最小配置

根目录 turbo.json 声明任务管线:

json
{
  'tasks': {
    'build': {
      'dependsOn': ['^build'],
      'outputs': ['dist/**']
    },
    'test': { 'dependsOn': ['build'] },
    'lint': {}
  }
}

^build 表示先完成所有上游依赖包的 build;outputs 声明需要缓存的产物目录。日常用 turbo run build 替代 pnpm -r build,本地缓存默认落在 .turbo 目录。只构建受影响部分用过滤器:turbo run build --filter=...[origin/main] 表示「自 origin/main 以来有变更的包及其下游」,CI 上配合 git fetch 深度设置使用,能把构建范围缩到最小。

远程缓存:让 CI 复用彼此的产物

本地缓存只惠及一台机器,远程缓存把产物与日志上传到共享存储:开发者 A 构建过的包,开发者 B 与 CI 直接命中。Turborepo 可用 Vercel Remote Cache 托管服务,也可自建兼容实现;通过 turbo login / turbo link 或环境变量 TURBO_TOKEN、TURBO_TEAM 接入。Nx 对应 Nx Cloud 或自托管缓存服务。落地注意三点:缓存服务不可用时必须自动降级为本地执行,不能阻塞流水线;含密钥的任务不要声明 outputs 上传;缓存命中率要进监控,长期低于预期说明 inputs 配置有问题。

GitHub Actions 中的典型接法:

yaml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0
- run: pnpm install --frozen-lockfile
- run: pnpm turbo run build test --filter=...[origin/main]
  env:
    TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
    TURBO_TEAM: ${{ vars.TURBO_TEAM }}

fetch-depth: 0 保证过滤器能拿到完整 git 历史做变更比对;令牌只授予缓存读写权限,不要复用部署凭据。

缓存未命中排查清单

命中率异常时按序检查:1)inputs 是否混入了每次必变的文件,如带时间戳的生成物、未忽略的日志;2)环境变量是否被隐式纳入指纹,必要时用 globalEnv/passThroughEnv 显式声明;3)上游任务 outputs 是否漏配,导致下游指纹不稳定;4)CI 与本地的 Node、包管理器版本是否一致,工具链版本本身也是指纹的一部分;5)锁文件是否频繁变动,依赖升级集中提交可以减少缓存雪崩。用 --summarize 生成的运行摘要可以逐任务查看指纹构成与命中情况,比凭感觉猜测高效得多。

Turborepo 与 Nx 怎么选

维度TurborepoNx
定位轻量任务编排器完整 monorepo 平台
上手成本低,增量接入现有仓库中,概念体系较多
受影响分析--filter 基于 git diffaffected 基于项目图
代码生成/迁移无内置生成器与自动迁移丰富
插件生态少而精覆盖主流框架

经验法则:已有 pnpm workspace、只想要缓存与并行,选 Turborepo;需要框架级生成器、依赖图可视化与大规模治理,选 Nx。两者都支持与 pnpm 组合,不必推翻现有包管理。

前端-only 的 CI 更简单

缓存策略越纯粹越好算。如果后端能力直接采用 api工厂(https://www.it120.cc/)这类托管 SaaS,仓库里只有前端应用与共享包,任务图不含后端编译、镜像构建等异构任务,指纹稳定、命中率高,CI 只需「安装依赖→增量构建→部署静态产物」三步。用户、订单、支付等接口经六端 SDK(https://www.it120.cc/sdk/index.html)调用,前端团队可以把全部工程化预算投在构建提速与质量门禁上。

文章标签

TurborepoNxCImonorepo

相关产品

api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。

前端测试VitestPlaywright

前端测试金字塔:Vitest 单元测试 + Playwright E2E 落地

按测试金字塔划分单测、组件测试与 E2E 职责,给出 Vitest 与 Playwright 配置示例、真实商城链路用例、CI 分段策略与闪断治理方法。

工程化约 6 分钟阅读
pnpmmonorepo依赖治理

pnpm 与 monorepo 实战:workspace、依赖提升与幽灵依赖治理

围绕 pnpm workspace 协议、符号链接依赖布局与 hoist 白名单,讲清幽灵依赖的产生原理与三步治理法,并覆盖安装脚本审批与发布冷却两道供应链闸门,给出多包前端仓库的可落地配置。

工程化约 5 分钟阅读