turborepo-caching

Turborepo 缓存配置与构建优化

技能概述

Turborepo Caching 是一套针对 JavaScript/TypeScript Monorepo 项目的构建优化方案，通过本地和远程缓存机制大幅缩短构建时间，适用于需要频繁构建和测试的中大型代码仓库。

适用场景

1. 新建 Turborepo 项目

当你开始一个新的 monorepo 项目，或者需要从零配置 Turborepo 时，该技能可以帮你快速搭建 turbo.json 配置文件，定义合理的 pipeline 依赖关系和缓存策略。包括目录结构规划、全局依赖配置、环境变量设置等基础工作。

2. CI/CD 构建优化

如果你的团队在 GitHub Actions、GitLab CI 或其他持续集成环境中运行构建，该技能提供了完整的 CI 集成方案。通过 --filter 参数只构建变更的包，配合远程缓存共享构建产物，可以将 CI 时间从数十分钟降低到几分钟。

3. 迁移现有 Monorepo

当你从 Lerna、Nx 或 pnpm workspace 迁移到 Turborepo 时，该技能提供了平滑的迁移指南和配置模板。你可以保留现有的 workspace 结构，逐步引入 Turborepo 的缓存和任务调度能力，无需一次性重写整个构建流程。

核心功能

1. Pipeline 任务配置

通过 turbo.json 定义项目中各类任务的执行顺序和缓存规则。使用 dependsOn 声明任务依赖（如 build 依赖 ^build），用 outputs 指定需要缓存的产物文件，用 inputs 精确控制影响缓存哈希的文件范围。还支持环境变量敏感配置和包级别的自定义 pipeline。

2. 远程缓存方案

支持 Vercel 官方远程缓存和自托管缓存服务器两种模式。官方方案只需 npx turbo link 即可接入，适合快速上手；自托管方案提供了 Express 示例代码，适合需要私有化部署的企业环境。缓存可在团队成员和 CI 之间共享，真正实现"构建一次，处处复用"。

3. 智能过滤与增量构建

Turborepo 的 --filter 语法非常灵活，可以精确控制构建范围。例如 --filter=@myorg/web... 只构建指定包及其依赖，--filter='...[origin/main]' 只构建相对于某分支有变更的包。配合 --dry-run 和 --graph 命令，可以在实际执行前预览任务图。

常见问题

Turborepo 缓存保存在哪里？

默认情况下，本地缓存保存在系统用户目录下的 .turbo/cache 文件夹（macOS/Linux 为 ~/.turbo，Windows 为 %LOCALAPPDATA%\turbo）。如果配置了远程缓存，构建产物还会上传到 Vercel 云服务或你自建的服务器。

缓存不生效（cache miss）是什么原因？

最常见的原因包括：没有正确配置 outputs 字段导致没有文件被缓存、inputs 包含了不必要的文件导致哈希频繁变化、环境变量发生变化但没有在 env 字段中声明。使用 turbo build --verbosity=2 可以查看具体的缓存哈希和命中情况。

CI 中怎么只构建变更的包？

使用 --filter 参数配合分支差异表达式。例如在 GitHub Actions 中可以使用 turbo build --filter='...[origin/main]'，这会自动检测相对于 main 分支有变更的包及其依赖包。对于 Pull Request，可以用 --filter='...[base_ref]' 实现类似效果。

远程缓存免费吗？

Vercel 提供的远程缓存对个人和小团队有免费额度，具体限制可能会调整。对于大型团队或企业，推荐使用自托管缓存服务器，该技能提供了完整的 Express 实现示例，可以部署在任何支持 Node.js 的环境中。

dependsOn 中的 ^ 符号是什么意思？

^ 表示"所有依赖包"。例如 "dependsOn": ["^build"] 意味着当前包的 build 任务需要等待所有 workspace 依赖包的 build 任务完成。这确保了当你修改共享组件时，依赖该组件的应用会自动重新构建。