Turborepo caching

何时使用

适用：

• 在 monorepo（apps/* + packages/*）首次搭建或重构 Turborepo，编写 turbo.json 任务流水线。
• 设计任务依赖（dependsOn）、显式声明 outputs/inputs/env 以稳定缓存键。
• 接入远程缓存：Vercel 托管或自托管缓存服务器，跨开发者与 CI 共享构建产物。
• 在 CI 中用 --filter 仅构建受改动影响的包，压缩流水线耗时。
• 排查 cache miss、缓存频繁失效或构建未命中缓存的问题。
• 从其他单仓工具迁移到 Turborepo。

不该用（负边界）：

• 任务与 Turborepo 缓存无关，或目标工具是 Nx / Bazel / Rush / Lerna 等非 Turborepo。
• 单一小工程、无跨包复用与共享构建诉求——引入 Turborepo 通常不划算。
• 需要环境特定的安全/合规评审：本技能产物须经本地实测验证，不能替代专家审查。

步骤

1. 明确目标与约束：包管理器（npm/pnpm/yarn）、workspace 布局、CI 平台、是否已有远程缓存后端、哪些任务可缓存。
2. 根 package.json 声明 workspaces 与 turbo 脚本；安装 turbo 为 devDependency。
3. 写根 turbo.json：逐任务声明 dependsOn、outputs、inputs、env；dev/clean/deploy 等不可缓存任务设 cache: false，长驻任务（dev server）设 persistent: true。
4. 需要时用包级 turbo.json（"extends": ["//"]）覆盖单个包的任务配置。
5. 接远程缓存：先 npx turbo login + npx turbo link（Vercel），或部署自托管缓存服务并用 --api/--token/--team 指向。
6. CI 注入 TURBO_TOKEN/TURBO_TEAM，用 --filter='...[origin/main]' 仅构建受影响包。
7. 调试与验证：--dry-run/--summarize/--verbosity=2 看任务与哈希；清缓存冷构建记基线，再增量构建对比命中率，固化进 CI。

指令

骨架（关键文件）：

workspace/
├── apps/        # web、docs … 每个含 package.json
├── packages/    # ui、config … 可复用库
├── turbo.json   # 任务流水线 + 缓存规则
└── package.json # workspaces + turbo 脚本

pipeline 关键概念：dependsOn（前置任务，^build 指依赖包先构建）/ cache（是否缓存）/ outputs（要缓存的产物）/ inputs（影响缓存键的源文件）/ env（纳入哈希的环境变量）/ persistent（长驻任务）。

根 turbo.json（任务编排 + 缓存）：

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": [".env", ".env.local"],
  "globalEnv": ["NODE_ENV", "VERCEL_URL"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "env": ["API_URL", "NEXT_PUBLIC_*"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "inputs": ["src/**/*.ts", "src/**/*.tsx", "test/**/*.ts"]
    },
    "lint": { "outputs": [], "cache": true },
    "typecheck": { "dependsOn": ["^build"], "outputs": [] },
    "dev": { "cache": false, "persistent": true },
    "clean": { "cache": false }
  }
}

--filter 范围控制（CI 增量构建核心）：

turbo build --filter=@myorg/web          # 仅该包
turbo build --filter=@myorg/web...       # 该包 + 其依赖
turbo build --filter=...@myorg/ui        # 该包 + 依赖它的包（dependents）
turbo build --filter='...[origin/main]'  # 自 main 以来变更的包及其影响面
turbo build --filter='./apps/*'          # 目录下的包
turbo build --filter='!@myorg/docs'      # 排除某包

缓存调试：

turbo build --dry-run        # 看将运行哪些任务，不实际执行
turbo build --summarize      # 输出缓存命中/未命中汇总
turbo build --verbosity=2    # 打印任务哈希，定位缓存失效
turbo build --force          # 强制忽略缓存
turbo build --graph          # 导出任务依赖图
TURBO_LOG_VERBOSITY=debug turbo build --filter=@myorg/web

示例

为含 web 与 ui 的 monorepo 接入远程缓存并在 CI 只构建受影响包：

1. 根 package.json 配 "workspaces": ["apps/*", "packages/*"]，脚本 "build": "turbo build"；包间依赖用 workspace 协议 "@myorg/ui": "workspace:*"。
2. 本地接 Vercel 远程缓存：npx turbo login → npx turbo link，之后开发与 CI 共享产物。
3. GitHub Actions 中注入凭据并按变更过滤：

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ vars.TURBO_TEAM }}
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: 'npm' }
      - run: npm ci
      - run: npx turbo build --filter='...[origin/main]'
      - run: npx turbo test  --filter='...[origin/main]'

4. 自托管缓存时，turbo.json 加 {"remoteCache": {"signature": false}}，构建指向自有服务：turbo build --api="http://localhost:3000" --token="my-token" --team="my-team"（服务端按 Turborepo 的 /v8/artifacts/:hash GET/PUT/HEAD 协议实现）。
5. 上线前：清缓存冷构建记基线耗时，再改一处做增量构建，用 --summarize 确认命中率提升。

注意事项

推荐做法：

• 显式声明 inputs，避免无关文件变动导致缓存失效。
• 包间依赖用 workspace 协议（workspace:*），保证依赖图准确。
• 开启远程缓存，在 CI 与本地之间共享产物；CI 用 --filter 只构建受影响包。
• 只缓存构建产物（outputs），不要把源文件当产物缓存。

避免：

• 别缓存 dev server——改用 persistent: true，并对 dev/clean/deploy 设 cache: false。
• 别把密钥写进 env（会进缓存键且有泄露风险），密钥走运行时环境变量。
• 别省略 dependsOn——会引发任务竞态与产物不一致。
• 别过度 --filter——可能漏掉真正依赖的包；产物务必本地实测，缺输入/权限/成功标准时停下来澄清。

互见

• related：bazel-build-optimization —— 另一类大型单仓构建系统与远程缓存方案，按工具栈二选一。
• related：monorepo-navigator —— monorepo 结构梳理与导航。
• combines_with：ci-cd-pipeline-builder —— 把 turbo --filter 增量构建编进 CI/CD 流水线。
• combines_with：deployment-engineer —— 缓存命中后的构建产物对接部署发布。
• Turborepo 文档：https://turbo.build/repo/docs ｜ 缓存：https://turbo.build/repo/docs/core-concepts/caching ｜ 远程缓存：https://turbo.build/repo/docs/core-concepts/remote-caching

---

采编自 sickn33/antigravity-awesome-skills（MIT）。