Turborepo 缓存机制全解析从缓存方程到 global.inputs 的哈希深入指南【免费下载链接】turboBuild system optimized for JavaScript and TypeScript, written in Rust项目地址: https://gitcode.com/gh_mirrors/tu/turboTurborepo 是一个用 Rust 编写的 JavaScript/TypeScript 构建系统优化工具其最核心的设计原则是绝不重复做同样的工作never do the same work twice。本文以 skills/turborepo/references/caching/RULE.md 为骨架结合仓库内 Rust 源码turborepo-hash、turborepo-cache与集成测试global_inputs_test.rs系统讲解 Turborepo 缓存的工作机制缓存方程如何计算、全局哈希与任务哈希的输入有哪些、global.inputs如何改变哈希方程、缓存中存储什么、缓存放哪里、命中后如何恢复。读完本文你将能准确判断什么改动会让缓存失效这一 Turborepo 使用中最关键的问题并能利用futureFlags.globalConfiguration精确控制全局文件的缓存粒度。缓存方程fingerprint(inputs) → stored outputsTurborepo 缓存机制可以用一条方程概括fingerprint(inputs) → stored outputs如果某次任务的输入与上次完全一致哈希相同Turborepo 就直接从缓存恢复输出而不重新执行任务。这里的输入是一组经过哈希计算得到的指纹fingerprint输出则是构建产物与日志。缓存键由两层哈希共同决定task cache key hash(global hash, task hash)global hash全局哈希影响仓库中所有任务的公共输入。task hash任务哈希只影响某个具体任务的输入。只有两层哈希都未变化缓存才会命中。这一方程在源码中有直接对应crates/turborepo-hash/src/lib.rs中定义了GlobalHashable承载全局哈希输入与TaskHashable承载任务哈希输入两个结构体其中TaskHashable明确包含global_hash字段任务哈希计算时会把全局哈希一并卷入。全局哈希输入影响所有任务的公共因子以下输入会进入全局哈希任何一项变化都会使仓库内所有任务的缓存失效锁文件package-lock.json、yarn.lock、pnpm-lock.yaml、bun.lock。注意二进制格式的bun.lockb不受支持需要先运行bun install --save-text-lockfile将其转换为文本格式。globalDependencies中列出的文件使用globalConfiguration时改用global.inputs见下文。globalEnv中列出的环境变量使用globalConfiguration时改用global.env。turbo.json配置本身。配置示例{ globalDependencies: [.env, tsconfig.base.json], globalEnv: [CI, NODE_ENV] }从源码看锁文件并非直接以文件哈希进入全局哈希而是经过结构化处理crates/turborepo-hash/src/lib.rs中LockFilePackages会提取锁文件中每个包的key与version再通过turborepo_lockfile_hash做规范化序列化。这意味着锁文件内容的无关变化如注释、格式调整不会影响缓存只有包集合或版本变化才真正触发全局失效。GlobalHashable结构体还揭示了全局哈希的其他输入包括global_file_hash_map全局依赖文件哈希映射、root_external_dependencies_hash根外部依赖哈希、root_internal_dependencies_hash根内部依赖哈希、enginesNode 等引擎版本、env与resolved_env_vars、framework_inference框架推断开关以及global_configuration是否启用 globalConfiguration 模式。任务哈希输入决定单个任务缓存的因子以下输入会进入单个任务的任务哈希包内所有文件除非被inputs过滤。package.json内容。任务env键中列出的环境变量。任务配置本身命令command、outputs、依赖关系。依赖任务的哈希由dependsOn决定包括^build这类依赖包任务。使用futureFlags.globalConfiguration时global.inputs中的文件也会并入任务输入见下一节。配置示例{ tasks: { build: { dependsOn: [^build], inputs: [src/**, package.json, tsconfig.json], env: [API_URL] } } }源码中TaskHashable结构体逐一对应了这些输入task_dependency_hashes依赖任务哈希、hash_of_files包内文件哈希、external_deps_hash外部依赖哈希、outputs、pass_through_args、env、resolved_env_vars、command_override等。值得注意的细节是任务的实际执行命令command override也参与哈希——从源码注释看改变任务实际运行的命令必须使其缓存结果失效这保证了改动命令不会命中陈旧缓存。global.inputs如何改变哈希方程当在turbo.json中启用futureFlags.globalConfiguration后global.inputs的行为与globalDependencies有根本性差异global.inputs中的文件不再进入全局哈希而是被前置到每个任务的inputs中折叠进任务哈希。使用globalDependencies默认模式task cache key hash(global hash, task hash) ↑ 包含 globalDependencies 文件哈希在这种模式下修改globalDependencies中的任何文件都会使每一个任务失效无论任务级inputs如何设置任务都无法选择退出。集成测试 crates/turborepo/tests/global_inputs_test.rs 中的test_global_dependencies_cannot_be_excluded_by_task_inputs正是验证了这一点测试注释明确指出即使任务用取反 glob 明确排除了该文件取反也没有效果因为文件位于全局哈希而非任务输入中。使用global.inputsfutureFlags.globalConfiguration模式task cache key hash(global hash, task hash) ↑ 包含 global.inputs 文件哈希与任务 inputs 合并global.inputs的文件会合并进每个任务的输入 glob。这意味着任务可以用取反 glob 排除特定全局文件inputs: [$TURBO_DEFAULT$, !$TURBO_ROOT$/tsconfig.json]全局哈希变小它仍包含锁文件、engines、global.env等但不再包含global.inputs文件的文件哈希。任务哈希正确地把全局输入文件哈希与任务自身输入合并在一起。完整配置示例{ futureFlags: { globalConfiguration: true }, global: { inputs: [tsconfig.json, .env] }, tasks: { build: { outputs: [dist/**] }, lint: { inputs: [$TURBO_DEFAULT$, !$TURBO_ROOT$/tsconfig.json] } } }在这个例子中修改tsconfig.json会使build失效它位于该任务输入中但不会使lint失效它被显式排除。而在globalDependencies模式下两者都会被失效。这段行为差异同样有集成测试佐证global_inputs_test.rs中的test_global_inputs_can_be_excluded_and_affect_tasks验证了启用globalConfiguration后排除config.txt的任务app-b在第三次构建时命中缓存输出cache hit而未排除的任务app-a则正常失效重跑。这里涉及两个魔法变量说明如下$TURBO_DEFAULT$展开为包内全部文件的默认输入集合相当于未写inputs时的默认行为在自定义inputs时用它作为基线再叠加增删。$TURBO_ROOT$指向 monorepo 仓库根目录的绝对路径用于书写!$TURBO_ROOT$/tsconfig.json这类跨包取反表达式。缓存中存储什么Turborepo 为每个任务缓存两类内容文件输出outputs中指定的文件/目录。任务日志stdout/stderr供缓存命中时重放。{ tasks: { build: { outputs: [dist/**, .next/**] } } }关键要点缓存是内容寻址的基于输入哈希而非时间戳。空outputs数组表示任务照常运行但什么都不缓存。没有outputs键的任务不缓存任何东西如需显式表达用outputs: []。本地缓存位置默认情况下本地缓存存放在仓库根目录下.turbo/cache/ ├── hash1.tar.zst # 压缩后的输出 ├── hash2.tar.zst └── ...请务必将.turbo加入.gitignore避免缓存目录进入版本控制。源码层面本地缓存由crates/turborepo-cache/src/fs.rs中的FSCache实现fetch方法按{hash}.tar.zst拼接缓存路径并检查文件是否存在每个缓存归档还配有一个{hash}-manifest.json清单文件与-meta.json元数据记录 hash、duration、git sha 等。FSCache::new在初始化时通过create_dir_all确保缓存目录存在。整个 crate 的文档注释crates/turborepo-cache/src/lib.rs明确指出底层缓存产物是gzip 压缩的 tarball.tar.zst即 zstd 压缩的 tar 包。此外crates/turborepo-cache/src/cache_archive/目录下按职责拆分了create.rs归档写入、restore.rs归档恢复、restore_manifest.rs恢复清单等模块其中RestoreManifest支持快速路径校验若清单存在且磁盘上所有文件仍然匹配可跳过解压 tar 直接判定命中。缓存恢复流程缓存命中时Turborepo 依次执行解压归档输出到原始位置restore相关模块负责把 tar 中的文件恢复到各自路径。重放记录的 stdout/stderr日志。将任务标记为 cached在输出中显示FULL TURBO。从fs.rs的fetch实现还能看到一个性能优化细节恢复时若-manifest.json存在且磁盘上所有文件都仍然匹配manifest.validate_all(anchor)则完全跳过打开与解压 tar 的步骤——这就是缓存快速路径。示例流程从 cache miss 到 FULL TURBO# 第一次运行 - 执行 build并缓存结果 turbo build # → packages/ui: cache miss, executing... # → packages/web: cache miss, executing... # 第二次运行 - 输入未变从缓存恢复 turbo build # → packages/ui: cache hit, replaying output # → packages/web: cache hit, replaying output # → FULL TURBO关键要点速查缓存是内容寻址的基于输入哈希而不是时间戳。空outputs数组意味着任务会运行但不缓存任何东西。没有outputs键的任务同样不缓存如需显式表达请写outputs: []。任何输入变化都会使缓存失效——这是缓存正确性的基石。全局哈希与任务哈希共同决定缓存键task cache key hash(global hash, task hash)。globalDependencies模式下任务无法排除全局文件启用futureFlags.globalConfiguration后global.inputs会并入任务输入从而允许用取反 glob如!$TURBO_ROOT$/tsconfig.json精确控制失效范围。进一步阅读本文骨架文档skills/turborepo/references/caching/RULE.md缓存常见陷阱skills/turborepo/references/caching/gotchas.md远程缓存skills/turborepo/references/caching/remote-cache.md哈希实现crates/turborepo-hash/src/lib.rs全局哈希/任务哈希结构体与 Capn Proto 序列化缓存实现crates/turborepo-cache/src/fs.rs、crates/turborepo-cache/src/lib.rs、crates/turborepo-cache/src/cache_archive/缓存配置解析local:rw,remote:r等crates/turborepo-cache/src/config.rsglobal.inputs 行为验证测试crates/turborepo/tests/global_inputs_test.rs【免费下载链接】turboBuild system optimized for JavaScript and TypeScript, written in Rust项目地址: https://gitcode.com/gh_mirrors/tu/turbo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考