构建 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 中运行任务

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

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

过滤入口点

您可以像在本地使用 turbo 时一样，使用--filter 标志过滤任务。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 事件中运行良好，但在常规的 push 事件中不可用。在这种情况下，我们使用 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。