英文文档
构建您的仓库

构建 CI

了解如何在持续集成管道中使用 Turborepo 来加速构建、代码检查、测试和其他任务。

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

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

启用远程缓存

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

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

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

Vercel 的内置 CI/CD 会自动连接到您的托管 Vercel 远程缓存，无需任何配置。要获取用于将其他 CI 供应商连接到 Vercel 远程缓存的 token，请访问 Vercel 远程缓存文档。

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

在 CI 中运行任务

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

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

过滤入口点

您可以使用--filter 标志过滤任务，就像在本地使用 turbo 时一样。在 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。

故障排除

命中缓存导致构建失败

如果您的任务在错过缓存时通过但在命中缓存时失败，您可能没有正确配置任务的 outputs 键。

使用错误环境变量的部署

如果您没有为任务定义 env 或 globalEnv 键，Turborepo 将无法在创建哈希时使用它们。这意味着您的任务可以命中缓存，尽管处于不同的环境中。

检查您的 env 和 globalEnv 键的配置。

下一步

您现在拥有使用 Turborepo 发布应用程序所需的一切。要了解更多关于特定用例的信息，查看指南或深入了解核心概念。

使用环境变量

了解如何在 Turborepo 中配置和使用环境变量，包括任务哈希、环境模式和 .env 文件处理。

了解您的仓库

了解 Turborepo 提供的用于理解仓库结构的工具，帮助您使用和优化代码库。