快速开始

添加到现有仓库

学习如何将 Turborepo 添加到现有的单包或多包仓库中

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 may only be used inside a workspace

# 全局安装
pnpm add turbo --global
# 在仓库中安装
pnpm add turbo --save-dev --workspace-root

# 全局安装
yarn global add turbo
# 在仓库中安装
yarn add turbo --dev

# 全局安装
npm install turbo --global
# 在仓库中安装
npm install turbo --save-dev

# 全局安装
bun install turbo --global
# 在仓库中安装
bun install turbo --dev

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

添加 `turbo.json` 文件

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

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

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

{
  "$schema": "https://turborepo.com/schema.json",
  "tasks": {
    "build": {
      "outputs": ["dist/**"]
    },
    "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"
  }
}

一些 Vite 启动器附带的 package.json 如下所示：

package.json

{
  "scripts": {
    "build": "tsc && vite build"
  }
}

我们建议将这些拆分为 check-types 和 build 脚本，以便 turbo 可以并行运行它们：

apps/web/package.json

{
  "scripts": {
    "build": "vite build",
    "check-types": "tsc --noEmit"
  }
}

在多包工作空间中，您可能还希望向一个或多个库包添加 check-types 脚本，以了解如何使用一个 turbo 命令运行不同包中的多个脚本。

编辑 `.gitignore`

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

.gitignore

+ .turbo

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

Turborepo 使用来自包管理器的信息来优化您的仓库。要声明您正在使用哪个包管理器，如果您还没有的话，请向根目录 package.json 添加一个 packageManager 字段。

{
  "packageManager": "pnpm@10.0.0"
}

{
  "packageManager": "yarn@1.22.19"
}

{
  "packageManager": "npm@8.5.0"
}

{
  "packageManager": "bun@1.2.0"
}

根据您的仓库情况，在迁移过程中或在无法使用 packageManager 键的情况下，您可能需要使用 dangerouslyDisablePackageManagerCheck。

设置包管理器工作空间

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

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

如果您使用的是单包仓库，可以跳过此步骤，因为不需要工作空间。

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

{
  "workspaces": [
    "apps/*",
    "packages/*"
  ]
}

{
  "workspaces": [
    "apps/*",
    "packages/*"
  ]
}

{
  "workspaces": [
    "apps/*",
    "packages/*"
  ]
}

参考文档：

有关如何构建仓库结构的更多详细信息，请参阅构建仓库结构。

使用 `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` 开始开发

在多包工作空间中，您可以运行 turbo dev 来同时启动所有包的开发任务。

turbo dev

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

请注意，此步骤在单包工作空间中不会提供太多价值，因为：

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

下一步

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

从示例开始

使用 create-turbo 引导一个包含您喜欢工具的示例。

编辑器集成

了解如何将 Turborepo 与您的编辑器集成以获得最佳开发体验。