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 構(gòu)建優(yōu)化的生產(chǎn)模式。不要使用本技能的情況任務(wù)與 turborepo 緩存無關(guān)您需要此范圍之外的不同領(lǐng)域或工具說明澄清目標(biāo)、約束和所需的輸入。應(yīng)用相關(guān)的最佳實(shí)踐并驗(yàn)證結(jié)果。提供可操作的步驟和驗(yàn)證方法。如果需要詳細(xì)示例請打開resources/implementation-playbook.md。何時(shí)使用本技能設(shè)置新的 Turborepo 項(xiàng)目配置構(gòu)建流水線實(shí)現(xiàn)遠(yuǎn)程緩存優(yōu)化 CI/CD 性能從其他 monorepo 工具遷移調(diào)試緩存未命中核心概念1. Turborepo 架構(gòu)Workspace Root/ ├── apps/ │ ├── web/ │ │ └── package.json │ └── docs/ │ └── package.json ├── packages/ │ ├── ui/ │ │ └── package.json │ └── config/ │ └── package.json ├── turbo.json └── package.json2. 流水線概念概念描述dependsOn必須先完成的任務(wù)cache是否緩存輸出outputs要緩存的文件inputs影響緩存鍵的文件persistent長時(shí)間運(yùn)行的任務(wù)開發(fā)服務(wù)器模板模板 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 的遠(yuǎn)程緩存# 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自托管遠(yuǎn)程緩存// 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 設(shè)置{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}調(diào)試緩存# 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最佳實(shí)踐應(yīng)該做的定義顯式 inputs- 避免緩存失效使用工作區(qū)協(xié)議-myorg/ui: workspace:*啟用遠(yuǎn)程緩存- 在 CI 和本地之間共享在 CI 中過濾- 只構(gòu)建受影響的包緩存構(gòu)建輸出- 而不是源文件不應(yīng)該做的不要緩存開發(fā)服務(wù)器- 使用persistent: true不要在 env 中包含機(jī)密- 使用運(yùn)行時(shí)環(huán)境變量不要忽略 dependsOn- 會導(dǎo)致競爭條件不要過度過濾- 可能遺漏依賴項(xiàng)資源Turborepo 文檔緩存指南遠(yuǎn)程緩存局限性僅當(dāng)任務(wù)與上述范圍明確匹配時(shí)才使用本技能。不要將輸出視為特定環(huán)境驗(yàn)證、測試或?qū)＜覍彶榈奶娲?。如果缺少所需的輸入、?quán)限、安全邊界或成功標(biāo)準(zhǔn)請停下來詢問澄清。