Monorepo 构建缓存命中率优化：Turborepo 配置的常见陷阱（续篇）
Turborepo 的缓存命中率从 90% 降到 30%——你加了一个 env 变量，所有 task 的缓存全废了。
一、场景痛点
你的团队用 Turborepo 管理 Monorepo，10 个包 + 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 hash：
turbo.json中inputs配置指定的所有文件内容的 hash。默认包含package.json、turbo.json和所有源码文件。 - env hash：
globalEnv和每个 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 --dry=json 输出 task 执行计划 # 包含每个 task 的 hash 和缓存状态 try: result = subprocess.run( ['turbo', 'run', 'build', '--dry=json'], capture_output=True, text=True, timeout=30, ) plan = json.loads(result.stdout) except (subprocess.TimeoutExpired, json.JSONDecodeError) as e: logger.error(f"Failed 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. " f"Likely cause: Input file changed or task-specific env changed." ) else: # 依赖链失效：底层包改动导致整条链失效 diagnoses.append( f"🔗 Package '{package}': Multiple tasks in dependency chain missed. " f"Likely 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 don't 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[] ): Promise<InputAnalysis> { 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_ENV），task 级 env 只放影响本 task 的变量。inputs 精确指定影响输出的文件类型，排除 storybook、测试等非输出文件。依赖链的级联失效是架构问题，拆分共享依赖包可以减少影响范围。缓存正确性需要验证——inputs 遗漏会导致缓存命中但输出错误。命中率低于 70% 时应该优先检查 globalEnv 和 inputs 配置。
