WEBKT

自建 Turborepo 远程缓存：彻底告别 Vercel 延迟，实现团队构建秒级复用

3 0 0 0

在大型 Monorepo 项目中，Turborepo 凭借其“指纹识别”和“构建缓存”机制，极大地提升了开发体验。然而，Turborepo 默认使用的 Vercel Remote Cache 在国内开发者眼中却存在两大短板：一是网络延迟导致缓存下载甚至比本地构建还慢；二是出于企业合规性考虑，许多代码指纹和构建产物无法上传至公有云。

本文将手把手教你基于开源方案，利用 Docker 和私有云存储（如 MinIO 或阿里云 OSS）搭建一套属于自己的 Turborepo 远程缓存服务。

1. 为什么需要远程缓存？

在一个团队中，如果没有远程缓存，每个开发者和 CI 机器人都要独立执行相同的构建任务：

  • 重复劳动：同事 A 已经编译过 shared-utils，同事 B 拉取代码后还得再编译一遍。
  • CI 缓慢：流水线每次都要从零开始安装依赖、打包，浪费大量的计算资源。

有了远程缓存，只要团队中任何一个人或 CI 节点生成了缓存，其他人只需“一秒下载”即可复用结果。

2. 方案选型：turborepo-remote-cache

由于 Turborepo 的缓存协议本质上是一套基于 HTTP 的 API 规范，社区出现了多个实现。目前最成熟、维护最活跃的是 ducktors/turborepo-remote-cache。

该项目支持多种后端存储：

  • Local：直接存在服务器硬盘（适合单机测试）。
  • S3：兼容 AWS S3、MinIO、阿里云 OSS（适合生产环境，推荐）。
  • Azure/GCP：适配其他主流云厂商。

3. 环境准备

在开始部署前，你需要准备：

  1. 一台安装了 Docker 和 Docker Compose 的 Linux 服务器。
  2. 一个用于存储的 Bucket（以 MinIO 或 S3 为例）。
  3. 一个固定的域名（并配置好 SSL 证书，Turbo 客户端要求 HTTPS 或本地 localhost）。

4. 部署流程 (Docker Compose)

创建一个目录并编写 docker-compose.yml：

version: '3.8'

services:
  turbo-cache:
    image: ducktors/turborepo-remote-cache:latest
    ports:
      - "3000:3000"
    environment:
      # 必填：用于验证客户端的 Token（自定义长字符串）
      - TURBO_TOKEN=your_secure_password_here
      # 存储类型：s3
      - STORAGE_PROVIDER=s3
      # S3 配置
      - STORAGE_PATH=turbocache
      - S3_REGION=oss-cn-hangzhou
      - S3_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
      - S3_ACCESS_KEY=你的AccessKey
      - S3_SECRET_KEY=你的SecretKey
      - S3_BUCKET=你的Bucket名称
    restart: always

执行启动命令：

docker-compose up -d

5. 客户端配置：连接私有缓存

在你的 Monorepo 项目根目录下，你不再需要运行 turbo login，而是通过环境变量或命令行参数直接指向你的私服。

方案 A：通过环境变量配置（推荐用于 CI）

在 CI/CD 流水线（如 Jenkins、GitLab CI）中配置以下变量：

  • TURBO_API: https://turbo.yourdomain.com
  • TURBO_TOKEN: your_secure_password_here
  • TURBO_TEAM: any-string (自定义团队标识)

方案 B：本地开发配置

在本地开发时，可以在运行命令时注入：

npx turbo build --api="https://turbo.yourdomain.com" --token="your_secure_password_here" --team="my-team"

或者在项目根目录创建一个 .turbo/config.json (注意不要提交 Token 到 Git)：

{
  "teamid": "my-team",
  "apiurl": "https://turbo.yourdomain.com"
}

6. 验证是否成功

  1. 首轮构建：在本地运行 npx turbo build。你会看到控制台输出 Remote caching enabled。构建完成后，检查你的 S3/OSS 桶，会发现多了一堆哈希值命名的文件。
  2. 清理本地缓存：删除本地目录 rm -rf node_modules/.cache/turbo。
  3. 次轮构建：再次运行 npx turbo build。
    • 预期结果：控制台出现 >>> FULL TURBO 字样。
    • 时间对比：原本需要 2 分钟的构建，现在应该在 5-10 秒内完成（主要取决于网络下载速度）。

7. 最佳实践建议

  • 清理策略：缓存文件会随时间膨胀。建议在 S3 桶上配置“生命周期管理”，例如删除 30 天未访问的旧缓存，以节省存储费用。
  • 安全性：虽然有了 TURBO_TOKEN，但建议在 Nginx 层增加 IP 白名单限制，仅允许公司内网和 CI 节点的 IP 访问。
  • 监控：该开源镜像提供了 /health 接口，可以接入 Prometheus 或 Uptime Kuma 监控服务可用性。

总结

通过自建 Turborepo 远程缓存，我们不仅解决了 Vercel 的网络访问瓶颈，还实现了对构建产物的完全掌控。对于一个 10 人以上的开发团队，这套方案平均每天能为每位成员节省 15-30 分钟的编译等待时间，是前端工程化路径中投入产出比极高的优化手段。

架构师老李 Turborepo远程缓存前端工程化

评论点评