构建 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 指南。

过滤入口点

您可以使用 --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 事件中运行良好，但在常规 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 代替。