turborepo-caching - SKILL

name: turborepo-caching
description: “Configure Turborepo for efficient monorepo builds with local and remote caching. Use when setting up Turborepo, optimizing build pipelines, or implementing distributed caching.”
risk: critical
source: community
date_added: “2026-02-27”

Turborepo 缓存

Turborepo 构建优化的生产模式。

不要使用本技能的情况

• 任务与 turborepo 缓存无关
• 您需要此范围之外的不同领域或工具

说明

• 澄清目标、约束和所需的输入。
• 应用相关的最佳实践并验证结果。
• 提供可操作的步骤和验证方法。
• 如果需要详细示例，请打开resources/implementation-playbook.md。

何时使用本技能

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

核心概念

1. Turborepo 架构

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

2. 流水线概念

模板

模板 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":["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":["src/**","tests/**","jest.config.js"]}}}

模板 3：使用 Vercel 的远程缓存

# Login to Vercelnpx turbo login# Link to Vercel projectnpx turbolink# Run with remote cacheturbo build --remote-only# CI environment variablesTURBO_TOKEN=your-tokenTURBO_TEAM=your-team

# .github/workflows/ci.ymlname:CIon:push:branches:[main]pull_request:env:TURBO_TOKEN:${{secrets.TURBO_TOKEN}}TURBO_TEAM:${{vars.TURBO_TEAM}}jobs:build:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4-uses:actions/setup-node@v4with:node-version:20cache:'npm'-name:Install dependenciesrun:npm ci-name:Buildrun:npx turbo build--filter='...[origin/main]'-name:Testrun:npx turbo test--filter='...[origin/main]'

模板 4：自托管远程缓存

// Custom remote cache server (Express)importexpressfrom'express';import{createReadStream,createWriteStream}from'fs';import{mkdir}from'fs/promises';import{join}from'path';constapp=express();constCACHE_DIR='./cache';// Get artifactapp.get('/v8/artifacts/:hash',async(req,res)=>{const{hash}=req.params;constteam=req.query.teamId||'default';constfilePath=join(CACHE_DIR,team,hash);try{conststream=createReadStream(filePath);stream.pipe(res);}catch{res.status(404).send('Not found');}});// Put artifactapp.put('/v8/artifacts/:hash',async(req,res)=>{const{hash}=req.params;constteam=req.query.teamId||'default';constdir=join(CACHE_DIR,team);constfilePath=join(dir,hash);awaitmkdir(dir,{recursive:true});conststream=createWriteStream(filePath);req.pipe(stream);stream.on('finish',()=>{res.json({urls:[`${req.protocol}://${req.get('host')}/v8/artifacts/${hash}`]});});});// Check artifact existsapp.head('/v8/artifacts/:hash',async(req,res)=>{const{hash}=req.params;constteam=req.query.teamId||'default';constfilePath=join(CACHE_DIR,team,hash);try{awaitfs.access(filePath);res.status(200).end();}catch{res.status(404).end();}});app.listen(3000);

// turbo.json for self-hosted cache{"remoteCache":{"signature":false}}

# Use self-hosted cacheturbo build--api="http://localhost:3000"--token="my-token"--team="my-team"

模板 5：过滤和作用域

# Build specific packageturbo build--filter=@myorg/web# Build package and its dependenciesturbo build--filter=@myorg/web...# Build package and its dependentsturbo build--filter=...@myorg/ui# Build changed packages since mainturbo build--filter='...[origin/main]'# Build packages in directoryturbo build--filter='./apps/*'# Combine filtersturbo build--filter=@myorg/web--filter=@myorg/docs# Exclude packageturbo build--filter='!@myorg/docs'# Include dependencies of changedturbo 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":["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":"npm@10.0.0"}

调试缓存

# Dry run to see what would runturbo build --dry-run# Verbose output with hashesturbo build--verbosity=2# Show task graphturbo build--graph# Force no cacheturbo build--force# Show cache statusturbo build--summarize# Debug specific taskTURBO_LOG_VERBOSITY=debug turbo build--filter=@myorg/web

最佳实践

应该做的

• 定义显式 inputs- 避免缓存失效
• 使用工作区协议-"@myorg/ui": "workspace:*"
• 启用远程缓存- 在 CI 和本地之间共享
• 在 CI 中过滤- 只构建受影响的包
• 缓存构建输出- 而不是源文件

不应该做的

• 不要缓存开发服务器- 使用persistent: true
• 不要在 env 中包含机密- 使用运行时环境变量
• 不要忽略 dependsOn- 会导致竞争条件
• 不要过度过滤- 可能遗漏依赖项

资源

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

局限性

• 仅当任务与上述范围明确匹配时才使用本技能。
• 不要将输出视为特定环境验证、测试或专家审查的替代品。
• 如果缺少所需的输入、权限、安全边界或成功标准，请停下来询问澄清。