添加到现有仓库

Turborepo 可以以增量方式引入到任何存储库，无论是单包还是多包，以加速存储库的开发人员和 CI 工作流程。

安装 turbo 并在 turbo.json 中配置任务后，您会注意到缓存如何帮助您更快地运行任务。

准备单包工作区

单包工作区是例如运行 npx create-next-app 或 npm create vite 后得到的结果。您无需额外操作即可让 Turborepo 处理您的存储库，因此您可以直接跳到下面的第一步。

要了解有关单包工作区中 Turborepo 的更多信息，请访问专用指南。

准备多包工作区（monorepo）

turbo 构建在 Workspaces 之上，这是 JavaScript 生态系统中主要包管理器的一个特性。这使得它易于在现有代码库中采用。

须知：

如果您发现 turbo 存在无法在工作区中发现包或未遵循您的依赖图等问题，请访问我们的组织存储库页面以获取提示。

请注意，您不必立即开始使用 turbo 运行所有包的所有任务。您可以从几个包中的单个任务开始，随着您对 Turborepo 越来越熟悉，逐步添加更多任务和包。

将 Turborepo 添加到您的存储库

安装 `turbo`

我们建议您全局安装 turbo 并将其安装到存储库的根目录，以获得最佳开发体验。

在开始安装之前，请确保您已创建 pnpm-workspace.yaml 文件。如果缺少此文件，将导致错误提示： --workspace-root 只能在工作区内使用。

终端

# Global install
pnpm add turbo --global
# Install in repository
pnpm add turbo --save-dev --workspace-root

要了解我们为什么推荐两种安装方式的更多信息，请访问安装页面。

添加 `turbo.json` 文件

在存储库的根目录中，创建一个 turbo.json 文件。

本指南将使用 build 和 check-types 任务，但您可以将其替换为其他您感兴趣的任务，例如 lint 或 test。

./turbo.json

{
  "$schema": "https://turbo.net.cn/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "check-types": {
      "dependsOn": ["^check-types"]
    },
    "dev": {
      "persistent": true,
      "cache": false
    }
  }
}

有关配置 turbo.json 的更多信息，请参见配置选项文档。

在您的 Next.js 应用程序中，确保您有一个 check-types 脚本供 turbo 运行。

apps/web/package.json

{
  "scripts": {
+   "check-types": "tsc --noEmit"
  }
}

在多包工作区中，您可能还希望在您的一个或多个库包中添加 check-types 脚本，以查看多个脚本如何在不同包中通过一个 turbo 命令运行。

编辑 `.gitignore`

将 .turbo 添加到您的 .gitignore 文件中。 turbo CLI 使用这些文件夹来持久化日志、输出和其他功能。

.gitignore

+ .turbo

向根目录 `package.json` 添加 `packageManager` 字段

Turborepo 利用您的包管理器信息优化您的存储库。要声明您正在使用的包管理器，如果您的根目录 package.json 中尚未包含 packageManager 字段，请添加它。

package.json

{
+  "packageManager": "pnpm@10.0.0"
}

须知：

根据您的存储库，您可能需要在迁移期间或在尚不能使用 packageManager 键的情况下使用 dangerouslyDisablePackageManagerCheck。

设置包管理器工作区

对于多包工作区，您需要配置包管理器以识别您的工作区结构。

workspaces 字段告诉您的包管理器哪些目录包含您的包。常见模式包括 apps/* 用于应用程序，packages/* 用于共享库。

须知：

如果您正在使用单包存储库，可以跳过此步骤，因为不需要工作区。

pnpm-workspace.yaml

packages:
  - "apps/*"
  - "packages/*"

→ pnpm 工作区文档

有关如何构建存储库的更多详细信息，请参阅组织存储库。

使用 `turbo` 运行任务

您现在可以使用 Turborepo 运行您之前添加到 turbo.json 中的任务。使用上述示例任务：

终端

turbo build check-types

这将同时运行 build 和 check-types 任务。您的工作区的依赖图将用于以正确的顺序运行任务。

不更改代码，再次尝试运行 build 和 check-types

终端

turbo check-types build

您应该会看到如下终端输出

终端

Tasks:    2 successful, 2 total
Cached:    2 cached, 2 total
Time:    185ms >>> FULL TURBO

恭喜！您刚刚在几毫秒内完成了代码构建和类型检查。

要了解 turbo 如何实现这一点，请查阅缓存文档。

通过运行 `turbo` 启动 `dev` 进行开发

在多包工作区中，您可以运行 turbo dev 以一次性启动所有包的开发任务。

终端

turbo dev

您还可以使用过滤器来专注于特定包及其依赖项。

请注意，此步骤在单包工作区中并没有太大价值，因为

您不会缓存开发任务的输出。
只有一个开发脚本，因此没有什么可以并行运行。

后续步骤

您现在已经成功启动并运行了 Turborepo！要了解更多改进工作流程并充分利用 turbo 的方法，我们建议您查看以下页面：