skip to content
logo

Search

Turborepo 自定义远程缓存

8 min read

为 Turborepo 项目提供一个自定义远程缓存服务，使首次构建将产物上传到远端，后续构建命中远端缓存而无需重新计算，从而显著缩短时间

# turborepo
Turborepo

原理

Turborepo 对每个任务计算“内容哈希”（代码、依赖锁、命令、声明的输出及环境变量等），将压缩后的产物作为“artifact”上传至远程服务。后续相同哈希的任务在“GET/HEAD”阶段命中缓存直接下载产物。

  • 服务端提供 PUT /v8/artifacts/:id 写入、HEAD/GET /v8/artifacts/:id 读取
  • 团队标识通过查询参数 teamId、team 或 slug 传入
  • 客户端（CLI）通常使用 --team，服务端会以 slug 接收

社区实现方案：https://turborepo.com/docs/core-concepts/remote-caching#community-implementations

缓存服务

启动服务：

初始化与启动：在服务端项目目录执行 pnpm install 后运行 pnpm dev 或 pnpm start。

配置 .env ：

  • PORT=3000（监听端口）
  • TURBO_TEAM=sunburst（团队/slug，客户端需同名）
  • TURBO_TOKEN=turbotokenlocal（鉴权令牌，客户端需一致）
  • CACHE_DIR=./cache（缓存二进制存储目录，按需）
  • AUTH_MODE=static（默认，静态 Token 鉴权）
  • STORAGE_PROVIDER=local（本地文件存储；生产建议云存储）

启动服务：

  • 在服务代码目录运行开发或生产启动脚本（如 pnpm dev 或 pnpm start）
  • 本地存储路径示例（团队 sunburst）：C:\Users\admin\AppData\Local\Temp\turborepocache\sunburst

注意：要验证是否提供自动创建团队子目录的功能，如果没有，需手动创建，确保团队目录存在。

服务端日志识别：

  • 写入成功：出现 PUT/保存工件（artifact）的日志
  • 读取未命中：出现 GET/404 “Artifact not found”
  • 鉴权失败：出现 401 Unauthorized（通常是令牌或团队不匹配）

业务项目配置

Turbo 配置（turbo.json）关键项：

remoteCache：

  • "enabled": true（启用远端缓存）
  • "signature": false（开发环境关闭签名；生产可考虑开启）
  • "teamId": "sunburst"（与服务端团队保持一致）

tasks：

  • "dependsOn": ["^build"]
  • "outputs": ["dist/**"] 声明构建产物路径,未声明的文件不会上传远程（推荐覆盖常见产物：dist/**、.next/**、packages/*/dist/**、.output/**）
  • "env": ["TURBO_*"]（将 TURBO_* 注入缓存 key，按需）

构建参数与传递

需要传的参数与怎么传

三个关键参数：

  • --api 或 TURBO_API：远程缓存地址，如 http://127.0.0.1:3000
  • --team 或 TURBO_TEAM：团队标识，如 sunburst
  • --token 或 TURBO_TOKEN：鉴权令牌，需与服务端 .env 一致

运行模式参数（通过 --cache= 指定）：

  • --cache=local:rw 本地读写
  • --cache=local:r 本地只读
  • --cache=local:,remote:rw 禁用本地、远端读写（常用于播种）
  • --cache=local:,remote:r 禁用本地、远端只读（常用于命中验证）

在命令行显式传参（最稳妥）：

  • pnpm turbo run build --filter=dashboard --api http://127.0.0.1:3000 --team sunburst --token turbotokenlocal

使用环境变量（便于长期脚本化）：

  • export TURBO_API=http://127.0.0.1:3000
  • export TURBO_TEAM=sunburst
  • export TURBO_TOKEN=turbotokenlocal
  • 然后：pnpm turbo run build --filter=dashboard

配置文件方式（最不安全，谨慎）：

  • .turbo/config.json 写入 apiurl/teamslug/token，但建议仅在开发环境临时使用

端到端验证流程（本地快速验证）

设置客户端环境（在执行构建的同一个终端）：

  • export TURBO_API=http://127.0.0.1:3000
  • export TURBO_TEAM=sunburst
  • export TURBO_TOKEN=turbotokenlocal

首次写入（强制计算并写入远程）：

  • 清理本地缓存：rm -rf .turbo
  • 强制构建：pnpm turbo run build --filter=dashboard --force
  • 成功迹象：
    • 服务端日志出现 PUT /v8/artifacts/<id>?slug=sunburst，且无 401/400 错误
    • 本地远程存储目录出现压缩的新文件（artifact id 名称）

二次命中（正常构建）：

  • pnpm turbo run build --filter=dashboard
  • Turborepo 控制台输出会显示远程命中提示（不同版本文案略有差异），任务执行耗时显著降低

深度确认（服务端与文件系统）：

  • curl -sI -H "Authorization: Bearer turbotokenlocal" "http://127.0.0.1:3000/v8/artifacts/<artifactId>?team=sunburst" 返回 200 OK 说明 artifact 存在
  • 目录查看：ls -lh "C:\Users\admin\AppData\Local\Temp\turborepocache\sunburst"

日志信息说明

客户端构建日志：

  • “Remote caching enabled” 表示已启用远端缓存。
  • “cache miss, executing …” 表示发生了重建。
  • “cache hit, replaying logs …” 表示命中缓存重放日志。
  • “Finishing writing to cache…” 后无错误，表示客户端写入结束。

服务端日志：

  • PUT/保存工件 → 写入成功
  • GET/200 → 读取命中
  • GET/404 → 读未命中（通常没播种或 key 不匹配）
  • 401 Unauthorized → 令牌或团队不匹配

生产环境落地

存储选择：

  • S3、Azure Blob、Google Cloud Storage 更适合生产（持久化、可扩展、跨区域）
  • 本地存储仅适合开发或单机临时使用，生产需挂载持久卷或网络存储

鉴权策略：

  • AUTH_MODE=static：简单可靠，令牌通过环境或密钥管理注入
  • AUTH_MODE=jwt：对接企业身份与授权（JWKS_URL、Scopes：artifacts:read|write）

CI 集成：

  • 在 CI 的构建任务里将 TURBO_API/TURBO_TEAM 以构建参数传入
  • 使用 CI/CD Secrets 注入 TURBO_TOKEN（用 CI Secret 管理令牌，避免代码库明文）
  • 主构建（播种）：--cache=local:,remote:rw 写入远端
  • 下游/并行流水线（复用）：--cache=local:,remote:r 只读远端，提高命中率
  • 灰度与回滚：在 CI 中先以 --team 区分环境（如 staging 与 prod），不同团队使用不同令牌与存储目录

性能与稳定性：

  • 根据产物大小调整 BODY_LIMIT（服务端接收的最大请求体）
  • 设置合理并发与连接数（如 S3_MAX_SOCKETS）
  • 避免将过多环境变量纳入缓存 key：env: ["TURBO_*"] 会导致不同 TURBO_TOKEN/TEAM 的 key 改变，按需取舍
  • 清理策略：定期清理陈旧 artifact 或按团队/项目归档

安全与合规：

  • 令牌管理：使用强随机令牌、定期轮换；限制服务只在内网访问。
  • TLS/代理：生产建议加 TLS，或放在可信的内网/容器网络中。
  • 签名校验：signature: true 可提升工件完整性（视服务端支持）。

常用命令清单

  • 远端读写播种：
    • CI=1 TURBO_API=http://127.0.0.1:3000 TURBO_TEAM=sunburst TURBO_TOKEN=turbotokenlocal pnpm -w turbo run dashboard#build --filter=dashboard --cache=local:,remote:rw
  • 远端只读验证：
    • CI=1 TURBO_API=http://127.0.0.1:3000 TURBO_TEAM=sunburst TURBO_TOKEN=turbotokenlocal pnpm -w turbo run dashboard#build --filter=dashboard --cache=local:,remote:r
  • 上游快速验证：
    • CI=1 TURBO_API=http://127.0.0.1:3000 TURBO_TEAM=sunburst TURBO_TOKEN=turbotokenlocal pnpm -w turbo run build --filter=@mint-core/demo-utils --cache=local:,remote:rw

结论

  • 通过自建远程缓存服务与合理的 Turbo 配置，可以在 Monorepo 中实现“任务级、内容哈希驱动”的精细缓存：上游未变命中、下游变更仅重建自身
  • 生产落地核心在于：服务端鉴权与团队隔离、客户端参数规范传递、任务 outputs 精准覆盖、CI 的播种与只读策略，以及稳定的环境与日志监控