name: turborepo-cachingdescription: “Configure Turborepo for efficient monorepo builds with local and remote caching. Use when setting up Turborepo, optimizing build pipelines, or implementing distributed caching.”risk: criticalsource: communitydate_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.json2. 流水线概念概念描述dependsOn必须先完成的任务cache是否缓存输出outputs要缓存的文件inputs影响缓存键的文件persistent长时间运行的任务开发服务器模板模板 1turbo.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_TOKENyour-tokenTURBO_TEAMyour-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/checkoutv4-uses:actions/setup-nodev4with: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)importexpressfromexpress;import{createReadStream,createWriteStream}fromfs;import{mkdir}fromfs/promises;import{join}frompath;constappexpress();constCACHE_DIR./cache;// Get artifactapp.get(/v8/artifacts/:hash,async(req,res){const{hash}req.params;constteamreq.query.teamId||default;constfilePathjoin(CACHE_DIR,team,hash);try{conststreamcreateReadStream(filePath);stream.pipe(res);}catch{res.status(404).send(Not found);}});// Put artifactapp.put(/v8/artifacts/:hash,async(req,res){const{hash}req.params;constteamreq.query.teamId||default;constdirjoin(CACHE_DIR,team);constfilePathjoin(dir,hash);awaitmkdir(dir,{recursive:true});conststreamcreateWriteStream(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;constteamreq.query.teamId||default;constfilePathjoin(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--apihttp://localhost:3000--tokenmy-token--teammy-team模板 5过滤和作用域# Build specific packageturbo build--filtermyorg/web# Build package and its dependenciesturbo build--filtermyorg/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--filtermyorg/web--filtermyorg/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:npm10.0.0}调试缓存# Dry run to see what would runturbo build --dry-run# Verbose output with hashesturbo build--verbosity2# Show task graphturbo build--graph# Force no cacheturbo build--force# Show cache statusturbo build--summarize# Debug specific taskTURBO_LOG_VERBOSITYdebug turbo build--filtermyorg/web最佳实践应该做的定义显式 inputs- 避免缓存失效使用工作区协议-myorg/ui: workspace:*启用远程缓存- 在 CI 和本地之间共享在 CI 中过滤- 只构建受影响的包缓存构建输出- 而不是源文件不应该做的不要缓存开发服务器- 使用persistent: true不要在 env 中包含机密- 使用运行时环境变量不要忽略 dependsOn- 会导致竞争条件不要过度过滤- 可能遗漏依赖项资源Turborepo 文档缓存指南远程缓存局限性仅当任务与上述范围明确匹配时才使用本技能。不要将输出视为特定环境验证、测试或专家审查的替代品。如果缺少所需的输入、权限、安全边界或成功标准请停下来询问澄清。
