缓存
Turborepo 使用缓存来加速构建，确保你永远不会重复相同的工作。当你的任务可缓存时，Turborepo 将使用首次运行任务时的指纹从缓存中恢复任务结果。
当在本地工作时，Turborepo 的缓存可以显著节省时间 - 并且当启用远程缓存时会更加强大，可以在你的整个团队和 CI 之间共享缓存。
在本页，你将学习
须知：
Turborepo 假设你的任务是确定性的。如果一个任务在 Turborepo 已知的输入集下能够产生不同的输出，则缓存可能无法按预期工作。
命中你的第一个 Turborepo 缓存
你可以通过三个步骤尝试 Turborepo 的缓存行为
首次运行构建
如果你已全局安装了 turbo，请在你的仓库中运行 turbo build。
或者，你可以使用你的包管理器在 package.json 中运行 build 脚本。
这将导致缓存未命中，因为你以前从未在这个仓库中使用这组输入运行过 turbo。输入被转换为哈希，以便在你的本地文件系统缓存或远程缓存中进行检查。
由于输入的指纹已在缓存中，因此无需再次从头开始重新构建你的应用程序。你可以从缓存中恢复先前构建的结果，从而节省资源和时间。
远程缓存
Turborepo 将任务结果存储在你机器上的 .turbo/cache 目录中。但是，你可以通过与你的团队成员和 CI 共享此缓存，使你的整个组织运行得更快。
要了解有关远程缓存及其优势的更多信息，请访问远程缓存页面。
启用远程缓存
首先，使用你的远程缓存提供商进行身份验证
然后，将你机器上的仓库链接到远程缓存
现在，当你运行任务时，Turborepo 将自动将任务的输出发送到远程缓存。如果你在另一台也已通过身份验证连接到你的远程缓存的机器上运行相同的任务，它将在首次运行该任务时命中缓存。
有关如何将你的 CI 机器连接到远程缓存的信息，请访问构建 CI 指南。
默认情况下，Turborepo 使用Vercel 远程缓存，无需任何配置。如果你想使用不同的远程缓存，请访问远程缓存 API 文档
什么会被缓存？
Turborepo 缓存两种类型的输出：任务输出和日志。
任务输出
Turborepo 缓存任务的文件输出，这些文件输出在 turbo.json 的 outputs 键中定义。当缓存命中时，Turborepo 将从缓存中恢复文件。
outputs 键是可选的，有关 Turborepo 在这种情况下如何表现，请参阅API 参考。
提供文件输出
如果你没有为任务声明文件输出，Turborepo 将不会缓存它们。对于某些任务（如 linters）来说，这可能没问题 - 但许多任务会生成你希望被缓存的文件。
如果你在缓存命中时遇到文件不可用的错误，请确保你已为你的任务定义了输出。
日志
Turborepo 始终捕获你的任务的终端输出，并将这些日志从任务首次运行时恢复到你的终端。
你可以使用--output-logs 标志或outputLogs 配置选项来配置重放日志的详细程度。
任务输入
输入由 Turborepo 哈希处理，为任务运行创建一个“指纹”。当“指纹”匹配时，运行任务将命中缓存。
在底层，Turborepo 创建两个哈希：全局哈希和任务哈希。如果任何一个哈希发生更改，任务将缓存未命中。
全局哈希输入
| 输入 | 示例 |
|---|---|
从根目录 turbo.json 解析的任务定义和包 turbo.json | 更改根目录 turbo.json 或包配置中的outputs |
| 影响 Workspace 根目录的锁定文件更改 | 更新根目录 package.json 中的依赖项将导致所有任务缓存未命中 |
globalDependencies 文件内容 | 当 ./.env 列在 globalDependencies 中时，更改它将导致所有任务缓存未命中 |
在 globalEnv 中列出的变量的值 | 当 GITHUB_TOKEN 列在 globalEnv 中时，更改其值 |
| 影响任务运行时的标志值 | 使用行为更改标志，如 --cache-dir、--framework-inference 或 --env-mode |
| 任意传递参数 | 与 turbo build 或 turbo build -- --arg=diff 相比，turbo build -- --arg=value 将缓存未命中 |
包哈希输入
| 输入 | 示例 |
|---|---|
| 包配置更改 | 更改包的 turbo.json |
| 影响包的锁定文件更改 | 更新包的 package.json 中的依赖项 |
包的 package.json 更改 | 更新包的 package.json 中的 name 字段 |
| 源代码控制中的文件更改 | 在 src/index.ts 中编写新代码 |
问题排查
使用模拟运行
Turborepo 有一个 --dry 标志，可用于查看如果你运行一个任务但不实际运行它会发生什么。当你无法确定你正在运行哪些任务时，这对于调试缓存问题非常有用。
有关更多详细信息，请访问 --dry API 参考。
使用运行摘要
Turborepo 有一个 --summarize 标志，可用于获取任务的所有输入、输出等的概述。比较两个摘要将显示为什么两个任务的哈希不同。这对于以下方面非常有用
- 调试输入：Turborepo 中的任务有很多输入。如果任务在你期望命中的时候缓存未命中，你可以使用运行摘要来检查哪些输入与你预期的不同。
- 调试输出：如果缓存命中没有恢复你期望的文件，运行摘要可以帮助你了解哪些输出正在从缓存中恢复。
摘要查看器
虽然没有 Turborepo 原生的运行摘要 UI 查看器，但如果你想将你的运行摘要作为 Web 视图查看，我们鼓励你使用社区构建的 https://turbo.nullvoxpopuli.com。
关闭缓存
有时，你可能不想将任务的输出写入缓存。可以使用 "cache": false 为任务永久设置此项，或使用 --no-cache 标志为整个运行设置此项。
覆盖缓存
如果你想强制 turbo 重新执行已缓存的任务，请使用 --force 标志。请注意，这会禁用读取缓存，而不是写入。
缓存任务比执行任务慢
可能会创建一些场景，在这些场景中，缓存最终比不缓存更慢。这些情况很少见，但一些示例包括
- 执行速度极快的任务：如果任务的执行速度比到远程缓存的网络往返时间还快，你应该考虑不缓存该任务。
- 输出资产巨大的任务：可能会创建一个非常大的工件，以至于上传或下载它的时间超过了重新生成它的时间，例如完整的 Docker 容器。在这些情况下，你应该考虑不缓存该任务。
- 具有自己缓存的脚本：某些任务具有自己的内部缓存行为。在这些情况下，配置可能会很快变得复杂，以使 Turborepo 的缓存和应用程序缓存协同工作。
虽然这些情况很少见，但请务必测试你的项目的行为，以确定在特定位置禁用缓存是否能提供性能优势。
下一步
既然你已经了解了 Turborepo 的缓存如何使你的仓库更快，那么让我们看看如何在你的 Turborepo 中开发应用程序和库。