Turborepo 是面向 JavaScript/TypeScript 单仓库的高性能构建系统,由 Vercel 开发,核心用 Rust 实现,官方定位为“面向智能体编程的构建系统”,当前版本为 v2.8。
用途:为包含多个应用与共享包的单仓库编排构建、测试、lint 等任务,减少重复执行并加速 CI。
主要能力:
- 任务缓存:基于内容哈希,文件真正变化时才重新构建。
- 远程缓存:通过 Vercel 在多台机器和 CI 间共享构建缓存。
- 并行执行:自动利用全部 CPU 核心。
- 增量构建:--affected 只运行改动包及其依赖方。
- 依赖图感知:理解包之间的依赖关系。
- Pruned 子集:为部署单个应用生成最小仓库。
- 2.8+ 支持 Git worktree 缓存共享、turbo devtools 可视化包与任务图、面向 AI 智能体的 turbo docs 文档输出。
- 2.7+ 支持可组合配置,可从任意工作区包扩展 turbo.json。
安装:新建项目用 npx create-turbo@latest;已有单仓库用 npm install turbo --save-dev;升级用 npx @turbo/codemod migrate。
turbo.json 任务管道通过 tasks 定义任务依赖图,常用字段包括 dependsOn(如 ^build 表示先构建依赖包)、outputs(需缓存的构建产物)、inputs(影响任务哈希的文件)、env(影响哈希的环境变量)、cache:false(跳过缓存,适合 dev server 或代码生成)、persistent:true(长时间运行任务)、globalDependencies 与 globalEnv。
工作区过滤:turbo build --filter=web 只运行 web;web... 含依赖;...web 含依赖方;...[main] 表示自 main 以来改动包及其依赖方;./apps/* 按目录;!docs 排除。
常用命令:turbo build、turbo build --affected、turbo build --filter=web、turbo prune web --docker、turbo ls、turbo login、turbo link。图可视化可用 turbo build --graph,支持 DOT、JSON 与 HTML 输出;turbo build --dry-run 可预览将执行的任务及缓存命中状态。
适用场景:多个应用共享代码、共享组件库、CI 耗时过长、团队共享构建产物、需要强制架构边界,以及作为 Vercel 微前端架构的编排层。单 Next.js 应用不必使用,Turbopack 已负责打包。
限制与注意事项:需 turbo.json 正确配置任务依赖与缓存范围;远程缓存依赖 Vercel 账号与 TURBO_TOKEN、TURBO_TEAM 环境变量;Bun 支持要求文本格式 bun.lock,若只有二进制 bun.lockb 会报错,需用 bun install --save-text-lockfile 生成;官方已知问题提到 turbo prune 在 Bun 1.3+ 下可能产生锁文件格式差异导致 bun i --frozen-lockfile 失败。其余收费、价格等信息暂未提供。