构建仓库

turbo 构建于工作区之上，这是 JavaScript 生态系统中包管理器的功能，允许您将多个包分组到一个仓库中。

遵循这些约定非常重要，因为它允许您：

在您仓库的所有工具中依赖这些约定
快速、渐进地将 Turborepo 采用到现有仓库中

在本指南中，我们将逐步设置多包工作区（monorepo），以便我们可以为 turbo 奠定基础。

开始使用

手动设置工作区的结构可能很繁琐。如果您是 monorepo 的新手，我们建议使用 create-turbo 立即开始使用有效的工作区结构。

终端

npx create-turbo@latest

然后，您可以查看仓库以了解本指南中描述的特征。

工作区的结构

在 JavaScript 中，工作区可以是单个包或包的集合。在这些指南中，我们将重点关注多包工作区，通常称为“monorepo”。

下面，突出显示了 create-turbo 的结构元素，使其成为有效的工作区。

package.json

package-lock.json

turbo.json

package.json

在 monorepo 中指定包

声明包的目录

首先，您的包管理器需要描述您的包的位置。我们建议首先将您的包拆分为 apps/ 用于应用程序和服务，将 packages/ 用于其他所有内容，例如库和工具。

./package.json

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

→npm 工作区文档

使用此配置，apps 或 packages 目录中每个**包含 package.json** 的目录都将被视为一个包。

由于 JavaScript 生态系统中包管理器之间的行为不明确，Turborepo 不支持嵌套包，例如 apps/** 或 packages/**。使用将包放在 apps/a 而将另一个包放在 apps/a/b 的结构将导致错误。

如果您想按目录对包进行分组，可以使用诸如 packages/* 和 packages/group/* 之类的 glob，而**不**创建 packages/group/package.json 文件。

每个包中的 `package.json`

在包的目录中，必须有一个 package.json 文件，以使包对您的包管理器和 turbo 可发现。下面是包的 package.json 的要求。

根 `package.json`

根 package.json 是您工作区的基础。以下是您在根 package.json 中找到的常见示例

./package.json

{
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint"
  },
  "devDependencies": {
    "turbo": "latest"
  },
  "packageManager": "[email protected]"
}

根 `turbo.json`

turbo.json 用于配置 turbo 的行为。要了解有关如何配置任务的更多信息，请访问配置任务页面。

包管理器锁定文件

锁定文件是您的包管理器和 turbo 实现可重现行为的关键。此外，Turborepo 使用锁定文件来了解您的工作区中内部包之间的依赖关系。

如果您在运行 turbo 时没有锁定文件，您可能会看到不可预测的行为。

包的结构

最好开始将包设计为工作区中的独立单元。在高层次上，每个包几乎都像其自己的小型“项目”，具有自己的 package.json、工具配置和源代码。这个想法是有局限性的——但这仍然是一个很好的 *起点* 心智模型。

此外，包具有特定的入口点，工作区中的其他包可以使用这些入口点来访问该包，由exports指定。

包的 `package.json`

`name`

name 字段用于标识包。它在您的工作区中应该是唯一的。

最佳实践是为您的内部包使用命名空间前缀，以避免与 npm 注册表上的其他包冲突。例如，如果您的组织名为 acme，您可能会将您的包命名为 @acme/package-name。

我们在文档和示例中使用 @repo，因为它在 npm 注册表上是未使用、不可声明的命名空间。您可以选择保留它或使用您自己的前缀。

`scripts`

scripts 字段用于定义可以在包的上下文中运行的脚本。Turborepo 将使用这些脚本的名称来标识在包中运行哪些脚本（如果有）。我们在运行任务页面上详细介绍了这些脚本。

`exports`

exports 字段用于指定要使用该包的其他包的入口点。当您想在另一个包中使用一个包中的代码时，您将从该入口点导入。

例如，如果您有一个 @repo/math 包，您可能会有以下 exports 字段

./packages/math/package.json

{
  "exports": {
    ".": "./src/constants.ts",
    "./add": "./src/add.ts",
    "./subtract": "./src/subtract.ts"
  }
}

请注意，此示例为了简单起见，使用了即时包模式。它直接导出 TypeScript，但您可以选择使用已编译包模式。

此示例中的 exports 字段需要现代版本的 Node.js 和 TypeScript。

这将允许您从 @repo/math 包导入 add 和 subtract 函数，如下所示

./apps/my-app/src/index.ts

import { GRAVITATIONAL_CONSTANT, SPEED_OF_LIGHT } from '@repo/math';
import { add } from '@repo/math/add';
import { subtract } from '@repo/math/subtract';

以这种方式使用 exports 提供了三个主要好处

避免桶文件：桶文件是重新导出同一包中其他文件的文件，为整个包创建一个入口点。虽然它们可能看起来很方便，但它们难以让编译器和捆绑器处理，并且可能很快导致性能问题。
更强大的功能：与main 字段相比，exports 还具有其他强大的功能，例如条件导出。总的来说，我们建议尽可能使用 exports 而不是 main，因为它是更现代的选择。
IDE 自动完成：通过使用 exports 指定包的入口点，您可以确保您的代码编辑器可以为包的导出提供自动完成功能。

好消息

您也可以使用通配符指定 exports。但是，由于 TypeScript 编译器的性能权衡，您会丢失一些 IDE 自动完成功能。有关更多信息，请访问TypeScript 指南。

如果您正在使用 TypeScript，您可能不需要在工作区的根目录中放置 tsconfig.json 文件。包应该独立指定它们自己的配置，通常是基于工作区中单独包的共享 tsconfig.json 文件构建的。有关更多信息，请访问TypeScript 指南。
您应该尽可能避免跨包边界访问文件。如果您发现自己正在编写 ../ 以从一个包转到另一个包，您可能有一个机会通过在需要它的地方安装该包并将其导入到您的代码中来重新考虑您的方法。

下一步

配置好工作区后，您现在可以使用您的包管理器将依赖项安装到您的包中。

这个对您有帮助吗？