turborepo

Turborepo 是 Vercel 推出的高性能 JavaScript/TypeScript 单体仓库构建系统，本 Skill 提供完整的配置指南与最佳实践。核心用法围绕 turbo.json 配置展开，开发者需定义任务管道明确构建依赖关系，通过 dependsOn 声明任务间的执行顺序，利用 ^build 语法确保依赖包先行构建。配合 --affected 标志可仅构建变更包及其下游依赖，显著减少 CI/CD 时间。远程缓存支持团队共享构建产物，避免重复计算。

显著优点包括：智能并行执行基于依赖图优化任务调度，大幅缩短构建时间；细粒度缓存机制精确追踪文件哈希与环境变量，实现"构建一次，处处可用"；与 pnpm/npm 工作区无缝集成，支持复杂 monorepo 架构。turbo watch 模式提供高效的开发体验，自动重编译变更依赖。

潜在局限性在于配置复杂度较高，初学者易混淆 ^build 与 build 的依赖语义，或错误配置 outputs 导致缓存失效。作为 T3 来源的社区文档，虽基于官方资料整理，但缺乏官方直接背书，部分边缘场景建议对照官方文档验证。严格的环境变量管理要求也增加了配置负担。

适合目标群体为中大型前端/全栈团队，特别是采用 Next.js、Node.js 技术栈且包含多个应用与共享包的 monorepo 架构。对构建速度敏感、CI 资源消耗大的工程团队收益最为显著。

使用风险主要包括：错误的缓存配置可能导致过时产物被复用，建议关键部署使用 --force 跳过缓存；环境变量未正确声明会导致缓存命中但运行时错误；远程缓存凭证管理不当存在泄露风险；过度依赖缓存可能掩盖依赖声明不完整等架构问题。

核心用法

Turborepo 是 Vercel 出品的 JavaScript/TypeScript monorepo 构建系统，核心能力包括：

1. 智能缓存 — 基于文件哈希的本地/远程缓存，避免重复构建
2. 任务管道 — 通过 turbo.json 的 dependsOn 声明依赖图，自动并行执行
3. 精准过滤 — --affected 仅构建变更包及其依赖，--filter 支持多维度包选择
4. 环境感知 — env/globalEnv 将环境变量纳入缓存键，确保配置变更触发重建

标准配置模式：

• 包级任务：每个 package.json 定义脚本（build/test/lint）
• 根级委托：根目录仅通过 turbo run <task> 触发，不含业务逻辑
• 任务注册：turbo.json 统一配置依赖关系与输出目录

显著优点

• 极速构建：缓存命中率可达 90%+，CI 时间从数十分钟降至分钟级
• 远程协作：Vercel Remote Cache 共享团队构建产物
• 框架无关：支持 npm/pnpm/Yarn，适配 Next.js、Vite、tsc 等任意工具链
• 开发体验：turbo watch 实现依赖变更自动重编译，持久化任务智能编排

潜在局限

• 学习曲线：^build vs build、inputs/outputs 等概念需理解依赖图语义
• 配置分散：大型仓库需在根 turbo.json 与包级 turbo.json 间权衡
• 缓存调试复杂：环境变量、隐式依赖未声明时易出现意外缓存命中
• 实验性功能：Boundaries（包边界检查）尚不稳定

适合人群

| 场景 | 推荐度 |

|------|--------|

| 5+ 包的 JS/TS monorepo | ⭐⭐⭐⭐ |

| 频繁 CI 构建的团队 | ⭐⭐⭐⭐⭐ |

| 需共享代码的跨应用项目 | ⭐⭐⭐⭐⭐ |

| 单仓库简单项目 | ⭐⭐☆☆☆ |

| 非 JS 生态（Rust/Go） | ⭐☆☆☆☆ |

常规风险

1. 配置误用：--parallel 绕过依赖图、../ 跨包引用文件、root .env 隐式耦合
2. 缓存失效：未声明 env 导致配置变更未重建；outputs 遗漏使产物未缓存
3. 安全边界：globalPassThroughEnv 过度宽松可能泄露 CI 敏感变量

本 Skill 为纯文档型（T-MD），无代码执行，可安全用于学习参考与配置生成。