从 Lerna 到 Turborepo
为什么 Lerna 被取代,Turborepo 的定位:任务编排 + 构建缓存,而不是包管理本身。和 pnpm/Nx 的关系。
安装与首次跑
基于 create-turbo 模板、接入现有 pnpm workspace、turbo.json 最小配置、turbo run build 全过程。
任务图 DAG
dependsOn、^ 前缀、跨包依赖、$TURBO_ROOT$。学会让 ui 先 build,web 再 build。
缓存命中原理
基于 inputs/outputs + env 哈希的缓存 key;.turbo/cache 结构;命中、部分命中、FULL TURBO。
远程缓存
Vercel 官方 + 自建 S3/Bitbucket 的 Remote Cache,TURBO_TOKEN + TURBO_TEAM、signature 校验、团队共享。
过滤与 prune
--filter 语法;turbo prune 为 Docker 裁剪 monorepo;结合 pnpm --filter 的差异与协作。
环境变量与 env hash
env、passThroughEnv、globalEnv 三档作用域;泄漏扫描;DOTENV 怎么进 hash。
开发模式 dev
turbo dev 长任务、persistent: true、interruptible、withDeps——同时跑 Next+Storybook+API 不打架。
CI / Vercel 集成
GitHub Actions 缓存串联 Vercel Remote Cache;Ignored Build Step;monorepo 多项目部署。
Turborepo 2 新特性
v2 重构(Rust 重写 + Go 移除)、boundaries 规则、turbo query、watch 模式 GA——2026 最佳实践清单。
关于这本指南
Turborepo 是 Vercel 2021 年收购 Jared Palmer 的项目后推出,2022 年 v1.0 发布,2024 年 v2 发布(Rust 重写)——目前(2026)是 JS/TS monorepo 构建编排的事实标准,被 Vercel、Shopify、Notion 内部使用。
本指南适合:已经在用 pnpm/Yarn workspaces 但觉得 CI 越来越慢的团队;从 Lerna 或 Nx 迁移的项目;想理解"任务哈希+远程缓存"机制的工程师。每章都有可跑的示例和 turbo.json 片段,配合官方 create-turbo 模板练手效果最佳。