结论先行:monorepo CI 提速的关键不是换更快的机器,而是「不算没变的、不跑没影响的」——Turborepo 与 Nx 都通过任务图 + 输入指纹实现增量构建,再把缓存搬到远端共享,让 CI 直接复用同事或上一次流水线的产物。配置得当,十几个包的仓库可以把全量构建压缩到只构建两三个受影响的包。 本文讲清原理、最小配置与远程缓存落地。
增量构建的原理:任务图与指纹
两个工具的共同模型是:把 build、test、lint 声明为任务(task),用 dependsOn 描述任务间依赖(如先构建上游包再构建下游应用),形成有向无环图。每个任务执行前计算指纹:源文件、依赖锁文件、环境变量、上游任务产物哈希共同决定缓存键。指纹命中则直接回放缓存的产物与日志,未命中才真正执行。因此「缓存失效」问题几乎都能归结为 inputs 声明不准:把无关文件纳入指纹会导致永远 miss,漏掉关键文件则可能回放过期产物。
Turborepo 最小配置
根目录 turbo.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 中的典型接法:
- 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 怎么选
| 维度 | Turborepo | Nx |
|---|---|---|
| 定位 | 轻量任务编排器 | 完整 monorepo 平台 |
| 上手成本 | 低,增量接入现有仓库 | 中,概念体系较多 |
| 受影响分析 | --filter 基于 git diff | affected 基于项目图 |
| 代码生成/迁移 | 无内置 | 生成器与自动迁移丰富 |
| 插件生态 | 少而精 | 覆盖主流框架 |
经验法则:已有 pnpm workspace、只想要缓存与并行,选 Turborepo;需要框架级生成器、依赖图可视化与大规模治理,选 Nx。两者都支持与 pnpm 组合,不必推翻现有包管理。
前端-only 的 CI 更简单
缓存策略越纯粹越好算。如果后端能力直接采用 api工厂(https://www.it120.cc/)这类托管 SaaS,仓库里只有前端应用与共享包,任务图不含后端编译、镜像构建等异构任务,指纹稳定、命中率高,CI 只需「安装依赖→增量构建→部署静态产物」三步。用户、订单、支付等接口经六端 SDK(https://www.it120.cc/sdk/index.html)调用,前端团队可以把全部工程化预算投在构建提速与质量门禁上。
文章标签
相关产品
api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。