skip to content
logo

Search

Vercel + Turborepo 远程缓存实践

5 min read

Vercel + Turborepo 实现远程缓存的方案实践

# turborepo
Turborepo

远程缓存的概念

默认情况下，Turborepo 的缓存仅保存在本地文件系统中，这在团队协作和持续集成场景下会导致大量重复工作 —— 即使输入完全相同的任务（如 turbo run build）也需要在不同的机器上重复执行。

远程缓存 是 Turborepo 提供的一个强大功能，它允许团队共享一个单一的缓存。 通过远程缓存，Turborepo 可以安全地与云服务器通信，存储任务的执行结果。 这种机制可以显著减少整个组织内的重复工作，从而节省大量时间。

值得注意的是：

  • 使用 Turborepo 不强制要求启用远程缓存
  • 远程缓存是免费的，可以使用托管服务或自托管方式
  • 在使用远程缓存时，需要确保正确的缓存配置和环境变量处理
  • Turborepo 会将日志作为构建产物处理，请注意控制台输出的内容

Vercel 托管方案实践

即使你的应用不托管在 Vercel 上也可以使用 Vercel 提供的远程缓存服务。启用步骤如下：

认证 CLI

npx turbo login

执行后会打开浏览器，要求你登录 Vercel 账号并授权。

链接项目到远程缓存

npx turbo link

这个命令会将你的项目与 Vercel 的远程缓存服务关联。

配置 turbo.json

检查项目根目录下的 turbo.json 文件，确保包含以下配置：

turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": [".env.local"],
  "remoteCache": {
    "signature": true,
    "enabled": true,
    "teamId": "sunburst" // 你的vercel团队 ID
  },
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"],
      "cache": true, // 启用缓存
      "env": ["TURBO_*"] // 传递环境变量
    },
    "dev": {
      "cache": false, // dev 任务不启用缓存
      "persistent": true
    }
  }
}

构建产物的完整性验证

Turborepo 支持在上传到远程缓存前对构建产物进行签名。也就是配置"signature": true。 所以需要在对应的 env 文件中设置签名密钥环境变量：TURBO_REMOTE_CACHE_SIGNATURE_KEY

.env.local
TURBO_REMOTE_CACHE_SIGNATURE_KEY="your-secret-key"

Turborepo 使用 HMAC-SHA256 算法进行签名，下载时会验证产物的完整性和真实性。

Turborepo 会忽略任何无法验证的工件并将其视为缓存未命中。

验证是否生效

执行以下步骤来验证：

  • 先执行一次构建：pnpm build
  • 然后清除本地缓存：rm -rf./.turbo/cache
  • 再次执行构建：pnpm build

重新执行构建，如果配置正确，turbo 将从远程缓存下载日志和产物，如果看到 cache hit，则说明远程缓存生效。

也可以使用pnpm turbo build --remote-only --verbosity=2 来指定使用远程缓存，并输出详细的日志。 remote-cache

因为 Turborepo 会在后台启动一个守护进程来管理远程缓存。可能某些文件正在被使用或被锁定导致无法删除。 可以先强制关闭这个守护进程，然后再删除。

Get-Process | Where-Object {$_.Name -like "*turbo*"} | Stop-Process -Force

在团队中使用

其他团队成员只需要执行：

npx turbo login
npx turbo link

就可以共享到你的远程构建缓存。大大提升开发效率。每次构建时，Turborepo 会先检查远程缓存是否有匹配的构建结果，如果有就直接使用，避免重复构建。

要禁用远程缓存，可以使用：

pnpm turbo build --no-cache

注意事项

  1. 注意检查是否真的命中了远程缓存，而不是本地缓存（.turbo 目录）
  2. 确保 .gitignore 中包含了 .turbo 目录
  3. 如果你的构建输出包含敏感信息，建议在生产环境中禁用远程缓存
  4. 远程缓存在免费版 Vercel 账号中有一定的容量限制
  5. CI/CD 环境中需要设置 TURBO_TOKEN 和 TURBO_TEAM 环境变量
  6. 可以在 Vercel 的控制台中重点关注 “Time Saved” 和 “Remote Cache Artifacts”，这两个指标最能直观地反映远程缓存带来的收益

避坑：Remote Cache Artifacts 面板，如果按项目过滤，本地工件的使用不予归因。 artifacts