turborepo-caching

Turborepo 缓存

Turborepo 构建优化的生产实践模式。

以下情况请勿使用此技能

• 任务与 Turborepo 缓存无关
• 你需要使用此范围之外的其他领域或工具

说明

• 明确目标、约束和所需输入。
• 应用相关最佳实践并验证结果。
• 提供可执行的步骤和验证方法。

以下情况请使用此技能

• 设置新的 Turborepo 项目
• 配置构建流水线
• 实现远程缓存
• 优化 CI/CD 性能
• 从其他单体仓库工具迁移
• 调试缓存未命中问题

核心概念

1. Turborepo 架构

Workspace Root/
├── apps/
│   ├── web/
│   │   └── package.json
│   └── docs/
│       └── package.json
├── packages/
│   ├── ui/
│   │   └── package.json
│   └── config/
│       └── package.json
├── turbo.json
└── package.json

2. 流水线概念

概念	描述
dependsOn	必须先完成的任务
cache	是否缓存输出
outputs	要缓存的文件
inputs	会影响缓存键的文件
persistent	长时间运行的任务（开发服务器）

版本与缓存正确性

下面的 JSON 使用 Turbo 1.x 风格（pipeline，与示例中的 ^1.10.0 依赖版本相匹配）；Turbo 2 使用 tasks。请查阅已安装版本的架构和迁移文档。显式指定 inputs 会替换默认值：请包含 $TURBO_DEFAULT$，或包含所有实际的源文件、配置和依赖输入，以避免测试或构建使用过时的成功结果。切勿缓存包含机密信息的输出；如果必需的外部状态未绑定，也不要复用缓存中的成功结果。

模板

模板 1：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": [
        "$TURBO_DEFAULT$",
        "src/**/*.tsx",
        "src/**/*.ts",
        "test/**/*.ts"
      ]
    },
    "lint": {
      "outputs": [],
      "cache": true
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "clean": {
      "cache": false
    }
  }
}

模板 2：针对特定包的流水线

// apps/web/turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "extends": ["//"],
  "pipeline": {
    "build": {
      "outputs": [".next/**", "!.next/cache/**"],
      "env": [
        "NEXT_PUBLIC_API_URL",
        "NEXT_PUBLIC_ANALYTICS_ID"
      ]
    },
    "test": {
      "outputs": ["coverage/**"],
      "inputs": [
        "$TURBO_DEFAULT$",
        "src/**",
        "tests/**",
        "jest.config.js"
      ]
    }
  }
}

模板 3：使用 Vercel 进行远程缓存

# Login to Vercel
npx turbo login

# Link to Vercel project
npx turbo link

# Run with remote cache
turbo build --remote-only

# CI environment variables
TURBO_TOKEN=your-token
TURBO_TEAM=your-team

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

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'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npx turbo build --filter='...[origin/main]'

      - name: Test
        run: npx turbo test --filter='...[origin/main]'

模板 4：自托管远程缓存

使用经过审核且实现了已安装 Turbo 远程缓存协议的服务端。要求进行身份验证、由服务端执行租户授权、限制构件大小、安全验证哈希值和路径、原子写入、处理流错误并设置保留期限。不要通过将不可信的 teamId/hash 值拼接为文件系统路径来构建生产缓存。启用受支持的构件签名并进行端到端验证；共享缓存可以提供可执行的构建输出。避免将令牌放入命令行参数或日志中，也不要向不可信的 PR 授予写入权限。

模板 5：筛选与范围限定

# Build specific package
turbo build --filter=@myorg/web

# Build package and its dependencies
turbo build --filter=@myorg/web...

# Build package and its dependents
turbo build --filter=...@myorg/ui

# Build changed packages since main
turbo build --filter='...[origin/main]'

# Build packages in directory
turbo build --filter='./apps/*'

# Combine filters
turbo build --filter=@myorg/web --filter=@myorg/docs

# Exclude package
turbo build --filter='!@myorg/docs'

# Include dependencies of changed
turbo build --filter='...[HEAD^1]...'

模板 6：高级流水线配置

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"],
      "inputs": [
        "$TURBO_DEFAULT$",
        "!**/*.md",
        "!**/*.test.*"
      ]
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"],
      "inputs": [
        "$TURBO_DEFAULT$",
        "src/**",
        "tests/**",
        "*.config.*"
      ],
      "env": ["CI", "NODE_ENV"]
    },
    "test:e2e": {
      "dependsOn": ["build"],
      "outputs": [],
      "cache": false
    },
    "deploy": {
      "dependsOn": ["build", "test", "lint"],
      "outputs": [],
      "cache": false
    },
    "db:generate": {
      "cache": false
    },
    "db:push": {
      "cache": false,
      "dependsOn": ["db:generate"]
    },
    "@myorg/web#build": {
      "dependsOn": ["^build", "@myorg/db#db:generate"],
      "outputs": [".next/**"],
      "env": ["NEXT_PUBLIC_*"]
    }
  }
}

模板 7：根目录 package.json 设置

{
  "name": "my-turborepo",
  "private": true,
  "workspaces": [
    "apps/*",
    "packages/*"
  ],
  "scripts": {
    "build": "turbo build",
    "dev": "turbo dev",
    "lint": "turbo lint",
    "test": "turbo test",
    "clean": "turbo clean && rm -rf node_modules",
    "format": "prettier --write \"**/*.{ts,tsx,md}\"",
    "changeset": "changeset",
    "version-packages": "changeset version",
    "release": "turbo build --filter=./packages/* && changeset publish"
  },
  "devDependencies": {
    "turbo": "^1.10.0",
    "prettier": "^3.0.0",
    "@changesets/cli": "^2.26.0"
  },
  "packageManager": "[email protected]"
}

缓存调试

# Dry run to see what would run
turbo build --dry-run

# Verbose output with hashes
turbo build --verbosity=2

# Show task graph
turbo build --graph

# Force no cache
turbo build --force

# Show cache status
turbo build --summarize

# Debug specific task
TURBO_LOG_VERBOSITY=debug turbo build --filter=@myorg/web

最佳实践

应该做

• 定义明确的输入——避免缓存失效
• 使用工作区协议——"@myorg/ui": "workspace:*"
• 启用远程缓存——在 CI 和本地之间共享
• 在 CI 中进行筛选——只构建受影响的包
• 缓存构建输出——不要缓存源文件

不应该做

• 不要缓存开发服务器——使用 persistent: true
• 不要在 env 中包含机密信息——使用运行时环境变量
• 不要忽略 dependsOn——否则会导致竞态条件
• 不要过度筛选——可能会漏掉依赖项

资源

• Turborepo 文档
• 缓存指南
• 远程缓存

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为针对特定环境进行验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并请求澄清。