构建 CI

Turborepo 加速了构建、代码检查、测试以及你在持续集成管道中需要执行的任何其他任务。通过并行化和远程缓存，Turborepo 使你的 CI 速度显著提升。

有关如何将你的 CI 供应商连接到远程缓存并运行任务的示例，请访问我们的 CI 指南。

启用远程缓存

要为你的 CI 启用远程缓存，请设置环境变量，以便 Turborepo 可以访问你的远程缓存。

环境变量	描述
`TURBO_TOKEN`	用于访问远程缓存的 Bearer 令牌
`TURBO_TEAM`	与你的仓库关联的帐户名称。当使用 Vercel 远程缓存时，这是你团队的 slug。

当你通过 turbo 运行任务时，你的 CI 将能够命中缓存，从而加速你的管道。

远程缓存托管

Vercel 的内置 CI/CD 自动连接到你管理的 Vercel 远程缓存，无需任何配置。要检索用于将你的其他 CI 供应商连接到 Vercel 远程缓存的令牌，请访问 Vercel 远程缓存文档。

有关自托管远程缓存选项，请访问 Turborepo 的远程缓存文档。

在 CI 中运行任务

通过全局安装 turbo 到你的开发和 CI 机器上，你可以使用一种心智模型来运行你的整个仓库，从开发到交付。你在 turbo.json 中注册的任务在 CI 中将完全相同地工作。

有关如何设置任务的更多信息，请访问配置任务页面。
有关在 CI 中运行任务的示例，请访问我们的 CI 指南。

过滤入口点

你可以使用 --filter 标志来过滤你的任务，这与你在本地使用 turbo 时完全相同。CI 中支持按包、目录和 Git 历史记录进行过滤。

在 CI 中使用 Git 历史记录

仅当机器上提供历史记录时，才可以使用源代码控制更改进行过滤。如果你使用的是浅克隆，则历史记录将不可用。

你还可以使用 --affected 标志仅在有更改的包中运行任务。

Docker

Docker 是许多部署管道的重要组成部分。Turborepo 的 prune 子命令通过从你的镜像中删除不必要的依赖项和代码，帮助你交付轻量级镜像。

有关如何从带有 Docker 的 Turborepo 部署的更多信息，请访问专门的 Docker 指南。

跳过任务和其他不必要的工作

仅运行受影响的任务

你可以使用 --affected 标志来仅运行具有更改的任务。

终端

turbo run build --affected

你会在以下情况下想要使用此标志：

你在你的 monorepo 中跨多个包运行许多任务，并且只想在代码已更改的包中运行这些任务。
你没有使用远程缓存，但仍然希望在 CI 中尽可能少地完成工作。
你正在使用远程缓存，并且你位于一个大型仓库中。通过最大限度地减少将从缓存还原的任务量，将减少通过网络发送的数据，从而加快缓存还原速度。
你已经在使用高级过滤技术或turbo-ignore来创建与 --affected 相同或相似的行为。你很可能有机会使用这个新标志来简化你的脚本。
- --affected 将比定制过滤更优雅地处理浅克隆，因为它会回退到运行所有任务。

在 GitHub Actions 中使用 `--affected`

CI/CD 管道是使用 --affected 的理想场所。使用 --affected，Turborepo 可以通过检查 GitHub 设置的环境变量（如 GITHUB_BASE_REF）来自动检测你是否在 GitHub Actions 中运行。

在 PR 的上下文中，这意味着 Turborepo 可以确定 PR 的基础分支和 PR 的头部分支之间哪些包发生了更改。这允许你仅为受 PR 中更改影响的包运行任务。

虽然 GITHUB_BASE_REF 在 pull_request 和 pull_request_target 事件中效果良好，但在常规推送事件中不可用。在这些情况下，我们使用 GITHUB_EVENT_PATH 来确定要将你的提交与哪个基础分支进行比较。在强制推送和推送没有额外提交的分支时，我们将与分支上第一个提交的父级进行比较。

使用 `turbo-ignore`

随着你的代码库和 CI 的增长，你可能会开始寻找更多方法来进一步加速。虽然命中缓存很有用，但你也可以完全跳过工作。使用 turbo-ignore，你可以跳过耗时的容器准备步骤，例如依赖项安装，这些步骤最终无论如何都会导致缓存命中。

检出仓库

首先克隆你的仓库。请注意，对于你计划使用的克隆深度，具有历史记录的克隆是进行比较所必需的。

须知：

默认情况下，turbo-ignore 使用父提交。要自定义更多深度，请参阅 turbo-ignore 参考。

为包和任务运行 `turbo-ignore`

默认情况下，turbo-ignore 将在当前工作目录中使用 build 任务。

要检查不同任务的更改，请使用 --task 标志。
要检查特定包及其依赖项的更改，请添加包的名称作为参数。

通过添加 web 包作为参数，检查 web 包及其依赖项的 build 任务的更改

终端

npx turbo-ignore web

处理结果

如果在包或其内部依赖项中检测到更改，turbo 将以 1 状态代码退出。如果未检测到更改，它将以 0 退出。

使用此状态代码，你可以选择 CI 管道的其余部分应该做什么。例如，1 退出代码可能意味着你应该继续安装依赖项并运行任务。

有关更高级的用例，请参阅 turbo-ignore 参考。

最佳实践

依赖缓存

Turborepo 的缓存能力使你可以创建复杂度最低的快速 CI 管道。通过远程缓存和使用 --filter 标志来定位要构建的包，Turborepo 将处理大型 monorepo 的更改检测，几乎没有开销。

例如，你的 CI 可以运行以下两个命令来快速处理质量检查并构建你的目标应用程序

turbo run lint check-types test：为你的整个仓库运行质量检查。任何未更改的包都将命中缓存。
turbo build --filter=web：使用你在 turbo.json 中注册的 build 任务构建 web 包。如果 web 包或其依赖项未更改，构建也将命中缓存。

随着你的代码库扩展，你可能会发现更多具体的优化 CI 的机会 - 但依赖缓存是一个很好的起点。

CI 中的全局 `turbo`

在 CI 工作流程中使用全局 turbo 很方便，它允许你轻松运行特定于你的 CI 的命令并利用自动工作区作用域。

但是，在某些情况下，你可能在使用包管理器安装包之前运行 turbo 命令或使用 turbo 的脚本。一个例子是使用 turbo prune 创建 Docker 镜像。在这种情况下，全局 turbo 将无法使用 package.json 中的版本，因为该版本的二进制文件尚未安装。

因此，我们鼓励你在 CI 中将全局安装的 turbo 固定到 package.json 中的主要版本，因为主要版本内不会引入重大更改。你还可以选择通过固定确切版本来增加稳定性，但需要权衡维护负担以接收补丁版本中的错误修复。

在 CI 中使用 `turbo run`

turbo run 是你在 Turborepo 中工作时最常用的命令，因此为了方便起见，它被别名为 turbo。虽然这对于本地工作非常有用，但 turbo 还有其他子命令，例如 turbo prune 和 turbo generate。

我们一直在努力使 turbo 变得更好，因此我们将来可能会添加更多子命令。因此，你可以通过在 CI 中使用 turbo run 来防止命名冲突。

例如，如果你的 CI 管道中有一个 turbo deploy 命令，它可能会与直接构建到 turbo CLI 中的潜在 deploy 子命令冲突。为避免这种情况，请在你的 CI 管道中使用 turbo run deploy 代替。