Monorepo 构建缓存命中率优化Turborepo 配置的常见陷阱续篇Turborepo 的缓存命中率从 90% 降到 30%——你加了一个 env 变量所有 task 的缓存全废了。一、场景痛点你的团队用 Turborepo 管理 Monorepo10 个包 1 个共享 UI 库。CI 的构建缓存命中率 90%平均构建时间 3 分钟。某天你在共享 UI 库加了一个THEME_MODE环境变量提交后 CI 的缓存命中率暴跌到 30%构建时间变成 15 分钟。你排查发现THEME_MODE被加到了globalEnv里所有依赖共享 UI 库的 task 都因为这个新 env 变量而缓存失效——即使这些 task 的输出与THEME_MODE完全无关。更常见的陷阱你在turbo.json的inputs里写了src/**但src目录下有一个stories/子目录存放了上百个 Storybook 文件。这些文件不影响构建输出但每次修改都会导致相关 task 的缓存失效。核心矛盾Turborepo 的缓存依赖输入的完整性——输入越精确缓存命中率越高但输入太粗包含无关文件命中率就低输入太细遗漏关键文件缓存就不正确。二、底层机制与原理剖析2.1 Turborepo 缓存的工作原理2.2 缓存 Hash 的计算规则Turborepo 的缓存 Hash 由三部分组成inputs hashturbo.json中inputs配置指定的所有文件内容的 hash。默认包含package.json、turbo.json和所有源码文件。env hashglobalEnv和每个 task 的env配置指定的环境变量值。这些变量会影响构建输出必须纳入 hash。依赖 hash当前 task 的上游依赖 task 的输出 hash。如果上游 task 的缓存失效下游 task 也会失效——因为输入变了。关键规则任何影响 hash 的变化都会导致缓存失效即使变化不影响输出。这是 Turborepo 的保守策略——宁可多失效不能缓存错误输出。2.3 缓存命中率的影响因素因素对命中率的影响优化方向globalEnv 变量数变量越多失效范围越大只包含真正影响输出的变量inputs 文件范围范围越粗无关文件越多精确指定影响输出的文件依赖链深度底层改动影响整条链减少共享依赖的改动频率分支差异不同分支的 env/inputs 可能不同统一分支的 env 配置三、生产级代码实现3.1 优化后的 turbo.json 配置// turbo.json —— 优化缓存命中率的配置 { $schema: https://turbo.build/schema.json, globalEnv: [ // 陷阱不要把所有 env 变量都加到 globalEnv // globalEnv 里的变量变化会导致所有 task 缓存失效 // 只包含真正影响所有 task 输出的变量 NODE_ENV // 错误示范不要加这些 // THEME_MODE ← 只影响 UI 库不应该 global // CI ← CI 环境标识不影响构建输出 // VERBOSE ← 日志级别不影响构建产物 ], globalPassThroughEnv: [ // passThroughEnv这些 env 变量不纳入 hash 计算 // 用途CI 标识、日志级别等不影响输出的变量 CI, TURBO_TEAM, TURBO_TOKEN, VERBOSE ], pipeline: { build: { dependsOn: [^build], outputs: [dist/**, .next/**], // 精确指定 inputs只包含影响构建输出的文件 // 不要用 src/** 这种粗粒度通配符 inputs: [ src/**/*.ts, src/**/*.tsx, src/**/*.css, // 排除不影响构建的文件storybook、测试文件 // 这些文件修改不应该导致构建缓存失效 !src/**/*.stories.tsx, !src/**/*.test.ts, !src/**/*.spec.ts, // 必须包含的配置文件 package.json, tsconfig.json ], // task 级 env只包含影响此 task 输出的变量 // 不影响其他 task 的缓存 env: [ THEME_MODE // 只影响 UI 库的构建不影响其他包 ], outputMode: new-only // 只输出新产生的文件减少缓存传输量 }, test: { dependsOn: [build], outputs: [], inputs: [ // 测试的 inputs包含测试文件测试修改应该触发重跑 src/**/*.test.ts, src/**/*.spec.ts, src/**/*.ts, src/**/*.tsx, package.json ] }, lint: { dependsOn: [^build], outputs: [], inputs: [ src/**/*.ts, src/**/*.tsx, package.json, .eslintrc.js ] }, dev: { cache: false, // dev 模式不缓存每次都实时运行 persistent: true // dev 是长运行进程不会结束 } } }3.2 缓存命中率分析脚本# cache_analyzer.py —— Turborepo 缓存命中率分析工具 import json import subprocess import logging from collections import defaultdict logger logging.getLogger(cache-analyzer) class CacheAnalyzer: 分析 Turborepo 的缓存命中率定位缓存失效原因 def analyze_cache_performance(self) - dict: 获取最近一次 CI 构建的缓存统计 # turbo run --dryjson 输出 task 执行计划 # 包含每个 task 的 hash 和缓存状态 try: result subprocess.run( [turbo, run, build, --dryjson], capture_outputTrue, textTrue, timeout30, ) plan json.loads(result.stdout) except (subprocess.TimeoutExpired, json.JSONDecodeError) as e: logger.error(fFailed to get turbo plan: {e}) return {} # 分析每个 task 的缓存状态 stats { total_tasks: 0, cached_tasks: 0, executed_tasks: 0, hit_rate_percent: 0, task_details: [], } for task in plan.get(tasks, []): task_id task.get(taskId, ) cached task.get(cache, {}).get(status, ) hit stats[total_tasks] 1 if cached: stats[cached_tasks] 1 else: stats[executed_tasks] 1 stats[task_details].append({ task_id: task_id, cached: cached, hash: task.get(hash, ), dependency_hashes: task.get(dependencyHashes, []), }) # 计算命中率 if stats[total_tasks] 0: stats[hit_rate_percent] ( stats[cached_tasks] / stats[total_tasks] * 100 ) return stats def diagnose_cache_misses(self, stats: dict) - list[str]: 诊断缓存失效的原因 diagnoses [] # 1. 找出所有未缓存的 task missed_tasks [ t for t in stats[task_details] if not t[cached] ] if not missed_tasks: return [All tasks cached — no issues detected] # 2. 分析失效模式 # 如果多个 task 同时失效可能是 globalEnv 变量变化 # 如果只有特定包的 task 失效可能是该包的 inputs 变化 # 如果整条依赖链失效可能是底层包改动 missed_packages defaultdict(list) for t in missed_tasks: # task_id 格式package#task parts t[task_id].split(#) package parts[0] if parts else unknown missed_packages[package].append(t) # 全局失效几乎所有包都失效 if len(missed_packages) stats[total_tasks] * 0.7: diagnoses.append( ⚠️ Global cache miss: Most packages affected. Likely cause: globalEnv variable changed or root config file modified. ) diagnoses.append( Fix: Review globalEnv in turbo.json. Only include variables that affect ALL task outputs. ) # 局部失效只有特定包失效 for package, tasks in missed_packages.items(): if len(tasks) 1: diagnoses.append( f Package {package}: Only this task missed cache. fLikely cause: Input file changed or task-specific env changed. ) else: # 依赖链失效底层包改动导致整条链失效 diagnoses.append( f Package {package}: Multiple tasks in dependency chain missed. fLikely cause: Shared dependency modified, cascading through chain. ) # 3. 建议 if len(missed_tasks) stats[total_tasks] * 0.3: diagnoses.append( Overall hit rate 70%. Recommended actions:\n 1. Check globalEnv — remove variables that dont affect outputs\n 2. Refine inputs — exclude non-output files (*.stories, *.test)\n 3. Check dependency chain — reduce shared package change frequency ) return diagnoses3.3 inputs 精细化工具// inputs-refiner.ts —— 自动分析并优化 inputs 配置 import { glob } from glob; import fs from fs; import path from path; interface InputAnalysis { currentInputs: string[]; suggestedInputs: string[]; excludedFiles: string[]; reason: string; } export class InputsRefiner { /** 分析当前 inputs 配置建议更精确的替代方案 */ async refineInputs( packageDir: string, currentInputs: string[] ): PromiseInputAnalysis { const suggestion: InputAnalysis { currentInputs: currentInputs, suggestedInputs: [], excludedFiles: [], reason: , }; // 检查当前 inputs 是否包含过于粗粒度的通配符 const broadPatterns currentInputs.filter( (p) p.includes(**) !p.startsWith(!) ); if (broadPatterns.length 0) { // 找出粗粒度通配符匹配到的文件分类影响和非影响 for (const pattern of broadPatterns) { const files await glob(pattern, { cwd: packageDir }); // 分类文件哪些影响构建输出哪些不影响 const outputRelevant files.filter((f) // 源码文件影响构建输出 /\.(ts|tsx|js|jsx|css|scss|vue)$/.test(f) // 排除测试和 storybook 文件不影响构建输出 !f.includes(.test.) !f.includes(.spec.) !f.includes(.stories.) !f.includes(.storybook) ); const outputIrrelevant files.filter((f) !outputRelevant.includes(f) ); // 建议精确 inputs用具体的文件类型替代粗粒度通配符 suggestion.suggestedInputs.push( ...outputRelevant.map((f) f.replace(packageDir /, )), ); // 排除列表不影响输出的文件用 ! 排除 for (const f of outputIrrelevant) { const relativePath f.replace(packageDir /, ); suggestion.excludedFiles.push(relativePath); suggestion.suggestedInputs.push(!${relativePath}); } } suggestion.reason Broad pattern ${broadPatterns.join(, )} matches ${suggestion.excludedFiles.length} non-output files. Excluding them improves cache hit rate by avoiding unnecessary cache invalidation when these files change.; } return suggestion; } }四、边界分析与架构权衡4.1 inputs 过细的风险如果 inputs 太细只列了几个关键文件遗漏了一个影响输出的文件缓存就会命中但输出错误。比如你只写了src/**/*.tsx但忘记写tailwind.config.js——修改 Tailwind 配置后缓存仍然命中但构建输出的 CSS 没有更新。对策在 CI 中加一步缓存正确性验证——缓存命中后比较输出文件的 hash 与上次真实构建的输出 hash。如果不一致说明 inputs 配置有遗漏。4.2 依赖链的级联失效共享 UI 库10 个包都依赖它改一行代码10 个包的 build task 缓存全部失效。这不是 inputs 配置的问题而是架构问题——共享依赖的改动频率太高。对策将共享 UI 库拆分为更小的独立包。每个包只依赖它实际使用的组件而不是整个 UI 库。这样单个组件的改动只影响依赖该组件的包。4.3 适用边界与禁用场景适用Monorepo 中包数量 ≥5、CI 频繁构建、缓存命中率 80%禁用单包项目不需要 Monorepo 缓存、构建时间 30 秒的项目缓存收益小、输出随时间变化的项目比如包含时间戳的版本号4.4 远程缓存的成本Turborepo 的远程缓存Vercel 提供的免费额度有限存储了每个 task 的输出文件。10 个包 × 3 个 task × 平均 5MB 输出 150MB/次构建。日构建 20 次 3GB/天。远程缓存按存储量收费超出免费额度后需要付费。五、结语Turborepo 缓存命中率优化的核心是精确 inputs 最小 env 短依赖链。globalEnv 只放真正影响所有 task 的变量如 NODE_ENVtask 级 env 只放影响本 task 的变量。inputs 精确指定影响输出的文件类型排除 storybook、测试等非输出文件。依赖链的级联失效是架构问题拆分共享依赖包可以减少影响范围。缓存正确性需要验证——inputs 遗漏会导致缓存命中但输出错误。命中率低于 70% 时应该优先检查 globalEnv 和 inputs 配置。