缓存

Turborepo 使用缓存来加速构建，确保你不会重复执行相同的工作。当你的任务可缓存时，Turborepo 将使用任务首次运行时的指纹从缓存中恢复任务结果。

¥Turborepo uses caching to speed up builds, ensuring you never do the same work twice. When your task is cacheable, Turborepo will restore the results of your task from cache using a fingerprint from the first time the task ran.

12 tasks are being ran in 3 packages, resulting in a ">>> FULL TURBO" cache hit. The total time it takes to restore these tasks from cache is 80 milliseconds.

Turborepo 的缓存功能可在本地工作时节省大量时间。 - 启用远程缓存后，其功能将更加强大，可以在你的整个团队和 CI 之间共享缓存。

¥Turborepo's caching results in significant time savings when working locally - and is even more powerful when Remote Caching is enabled, sharing a cache among your entire team and CI.

在本页，你将了解：

¥On this page, you'll learn:

Good to know:

Turborepo 假定你的任务是确定性的。如果任务能够根据 Turborepo 识别的输入集产生不同的输出，则缓存可能无法按预期工作。

¥Turborepo assumes that your tasks are deterministic. If a task is able to produce different outputs given the set of inputs that Turborepo is aware of, caching may not work as expected.

访问你的第一个 Turborepo 缓存

¥Hit your first Turborepo cache

你可以通过三个步骤尝试 Turborepo 的缓存行为：

¥You can try out Turborepo's caching behavior in three steps:

创建一个新的 Turborepo 项目

¥Create a new Turborepo project

使用 npx create-turbo@latest 并按照提示创建一个新的 Turborepo。

¥Use npx create-turbo@latest and follow the prompts to create a new Turborepo.

Terminal

npx create-turbo@latest

首次运行构建

¥Run a build for the first time

如果你有全局安装的 turbo，请在你的存储库中运行 turbo build。

¥If you have turbo installed globally, run turbo build in your repository.

或者，你可以使用软件包管理器在 package.json 中运行 build 脚本。

¥Alternatively, you can run the build script in package.json using your package manager.

Terminal

pnpm run build

这将导致缓存未命中，因为你之前从未在此存储库中使用输入集运行过 turbo。输入将转换为哈希值，以便在本地文件系统缓存或远程缓存中进行检查。

¥This will result in a cache miss, since you've never ran turbo before with this set of inputs in this repository. The inputs are turned into a hash to check for in your local filesystem cache or in the Remote Cache.

访问缓存

¥Hit the cache

再次运行 turbo build。你将看到如下消息：

¥Run turbo build again. You will see a message like this:

A terminal window showing two tasks that have been ran through turbo. They successfully complete in 116 milliseconds.

由于输入的指纹已在缓存中，因此无需再次从零开始重建应用。你可以从缓存中恢复上次构建的结果，从而节省资源和时间。

¥Because the inputs' fingerprint is already in the cache, there's no reason to rebuild your applications from zero again. You can restore the results of the previous build from cache, saving resources and time.

远程缓存

¥Remote Caching

Turborepo 将任务结果存储在你计算机上的 .turbo/cache 目录中。但是，你可以通过与团队成员和持续集成 (CI) 共享此缓存，进一步加快整个组织的运行速度。

¥Turborepo stores the results of tasks in the .turbo/cache directory on your machine. However, you can make your entire organization even faster by sharing this cache with your teammates and CI.

要了解更多关于远程缓存及其优势的信息，请访问远程缓存页面。

¥To learn more about Remote Caching and its benefits, visit the Remote Caching page.

启用远程缓存

¥Enabling Remote Cache

首先，使用你的远程缓存提供程序进行身份验证：

¥First, authenticate with your Remote Cache provider:

Terminal

npx turbo login

然后，将你机器上的仓库链接到远程缓存：

¥Then, link the repository on your machine to Remote Cache:

Terminal

npx turbo link

现在，当你运行任务时，Turborepo 会自动将任务的输出发送到远程缓存。如果你在另一台也已通过远程缓存身份验证的计算机上运行相同的任务，它将在第一次运行该任务时命中缓存。

¥Now, when you run a task, Turborepo will automatically send the outputs of the task to Remote Cache. If you run the same task on a different machine that is also authenticated to your Remote Cache, it will hit cache the first time it runs the task.

有关如何将你的 CI 机器连接到远程缓存的信息，请访问构建 CI 指南。

¥For information on how to connect your CI machines to Remote Cache, visit the Constructing CI guide.

默认情况下，Turborepo 使用零配置的 Vercel 远程缓存。如果你想使用其他远程缓存，请访问远程缓存 API 文档

¥By default, Turborepo uses Vercel Remote Cache with zero configuration. If you'd like to use a different Remote Cache, visit the Remote Caching API documentation

哪些内容会被缓存？

¥What gets cached?

Turborepo 缓存两种类型的输出：任务输出和日志。

¥Turborepo caches two types of outputs: Task outputs and Logs.

任务输出

¥Task outputs

Turborepo 会缓存在 turbo.json 的 outputs 键中定义的任务的文件输出。当缓存命中时，Turborepo 将从缓存中恢复文件。

¥Turborepo caches the file outputs of a task that are defined in the outputs key of turbo.json. When there's a cache hit, Turborepo will restore the files from the cache.

outputs 键是可选的，请参阅 API 参考了解 Turborepo 在这种情况下的行为。

¥The outputs key is optional, see the API reference for how Turborepo behaves in this case.

Providing file outputs

如果你没有为任务声明文件输出，Turborepo 将不会缓存它们。对于某些任务（例如 linters）来说，这可能没问题。 - 但许多任务会生成你希望缓存的文件。

¥If you do not declare file outputs for a task, Turborepo will not cache them. This might be okay for some tasks (like linters) - but many tasks produce files that you will want to be cached.

如果你在缓存时遇到文件不可用的错误，请确保你已定义任务的输出。

¥If you're running into errors with files not being available when you hit cache, make sure that you have defined the outputs for your task.

日志

¥Logs

Turborepo 始终捕获任务的终端输出，并从任务首次运行时将这些日志恢复到你的终端。

¥Turborepo always captures the terminal outputs of your tasks, restoring those logs to your terminal from the first time that the task ran.

你可以使用 --output-logs 标志或 outputLogs 配置选项配置重放日志的详细程度。

¥You can configure the verbosity of the replayed logs using the --output-logs flag or outputLogs configuration option.

任务输入

¥Task inputs

Turborepo 会对输入进行哈希处理，从而为任务运行创建一个 "fingerprint" 文件。当 "fingerprints" 匹配时，运行任务将会命中缓存。

¥Inputs are hashed by Turborepo, creating a "fingerprint" for the task run. When "fingerprints" match, running the task will hit the cache.

Turborepo 在底层创建了两个哈希值：一个全局哈希和一个任务哈希。如果其中一个哈希值发生变化，任务将丢失缓存。

¥Under the hood, Turborepo creates two hashes: a global hash and a task hash. If either of the hashes change, the task will miss cache.

全局哈希输入

¥Global hash inputs

输入	示例
从根目录 `turbo.json` 和软件包 `turbo.json` 解析任务定义	在根 `turbo.json` 或软件包配置中更改 `outputs`
影响工作区根目录的锁文件变更	更新根 `package.json` 中的依赖将导致所有任务缓存丢失
`globalDependencies` 文件内容	当 `./.env` 在 `globalDependencies` 中列出时，更改 `./.env` 将导致所有任务缓存丢失
`globalEnv` 中列出的变量值	当 `GITHUB_TOKEN` 在 `globalEnv` 中列出时，更改 `GITHUB_TOKEN` 的值
标记影响任务运行时的值	使用行为更改标志，例如 `--cache-dir`、`--framework-inference` 或 `--env-mode`
任意传递参数	与 `turbo build` 或 `turbo build -- --arg=diff` 相比，`turbo build -- --arg=value` 将丢失缓存。

软件包哈希值输入

¥Package hash inputs

输入	示例
软件包配置更改	更改软件包的 `turbo.json`
影响软件包的锁文件变更	更新包的 `package.json` 中的依赖
包的 `package.json` 更改	更新包的 `package.json` 中的 `name` 字段
源代码管理中的文件变更	在 `src/index.ts` 中编写新代码

故障排除

¥Troubleshooting

使用试运行

¥Using dry runs

Turborepo 有一个 --dry 标志，可用于查看在不实际运行任务的情况下运行任务时会发生什么。当你不确定正在运行哪些任务时，这对于调试缓存问题非常有用。

¥Turborepo has a --dry flag that can be used to see what would happen if you ran a task without actually running it. This can be useful for debugging caching issues when you're not sure which tasks you're running.

更多详情，请访问 --dry API 参考。

¥For more details, visit the --dry API reference.

使用运行摘要

¥Using Run Summaries

Turborepo 有一个 --summarize 标志，可用于概览任务的所有输入、输出等。比较两个摘要将显示两个任务哈希值不同的原因。这可以用于：

¥Turborepo has a --summarize flag that can be used to get an overview of all of a task's inputs, outputs, and more. Comparing two summaries will show why two task's hashes are different. This can be useful for:

调试输入：Turborepo 中的任务有很多输入。如果任务在你预期命中时丢失了缓存，你可以使用运行摘要来检查哪些输入与你预期的不同。

¥Debugging inputs: There are many inputs to a task in Turborepo. If a task is missing cache when you expect it to hit, you can use a Run Summary to check which inputs are different that you weren't expecting.
调试输出：如果缓存命中未恢复你期望的文件，运行摘要可以帮助你了解从缓存中恢复的输出。

¥Debugging outputs: If cache hits aren't restoring the files you're expecting, a Run Summary can help you understand what outputs are being restored from cache.

Summaries viewer

虽然没有 Turborepo 原生的运行摘要 UI 查看器，但如果你想以 Web 视图的形式查看运行摘要，我们建议你使用社区构建的 https://turbo.nullvoxpopuli.com。

¥While there is not a Turborepo-native Run Summaries UI viewer, we encourage you to use the community-built https://turbo.nullvoxpopuli.com if you would like to view your Run Summaries as a web view.

关闭缓存

¥Turning off caching

有时，你可能不想将任务的输出写入缓存。这可以永久设置为使用 "cache": false 的任务或使用 --cache <options> 标志的整个运行。

¥Sometimes, you may not want to write the output of tasks to the cache. This can be set permanently for a task using "cache": false or for a whole run using the --cache <options> flag.

覆盖缓存

¥Overwriting a cache

如果你想强制 turbo 重新执行已缓存的任务，请使用 --force 标志。请注意，这将禁用读取缓存，而不是写入缓存。

¥If you want to force turbo to re-execute a task that has been cached, use the --force flag. Note that this disables reading the cache, not writing.

缓存任务比执行任务慢

¥Caching a task is slower than executing the task

也有可能出现缓存比不缓存更慢的情况。这种情况很少见，但以下是一些示例：

¥It's possible to create scenarios where caching ends up being slower than not caching. These cases are rare, but a few examples include:

执行速度极快的任务：如果任务的执行速度快于与远程缓存的网络往返速度，则应考虑不缓存该任务。

¥Tasks that execute extremely fast: If a task executes faster than a network round-trip to the Remote Cache, you should consider not caching the task.
输出资源巨大的任务：有可能创建一个非常大的工件，以至于上传或下载它的时间超过了重新生成它的时间，例如一个完整的 Docker 容器。在这些情况下，你应该考虑不缓存该任务。

¥Tasks whose output assets are enormous: It's possible to create an artifact that is so big that the time to upload or download it exceeds the time to regenerate it, like a complete Docker Container. In these cases, you should consider not caching the task.
具有自身缓存的脚本：某些任务有自己的内部缓存行为。在这些情况下，为了使 Turborepo 的缓存和应用缓存协同工作，配置很快就会变得复杂。

¥Scripts that have their own caching: Some tasks have their own internal caching behavior. In these cases, configuration can quickly become complicated to make Turborepo's cache and the application cache work together.

虽然这些情况很少见，但请务必测试项目的行为，以确定在特定位置禁用缓存是否能带来性能提升。

¥While these situations are rare, be sure to test the behavior of your projects to determine if disabling caching in specific places provides a performance benefit.

后续步骤

¥Next steps

现在你已经了解了 Turborepo 的缓存如何使你的存储库更快，让我们来看看如何在 Turborepo 中开发应用和库。

¥Now that you've seen how Turborepo's caching makes your repository faster, let's take a look at how to develop applications and libraries in your Turborepo.