Turborepo 使用指南：提升 JavaScript 和 TypeScript 项目的构建效率

Turborepo 是一个高性能的构建系统，专为 JavaScript 和 TypeScript 项目设计，特别适合管理多包（monorepo）项目。它通过优化构建和任务执行流程，显著提升了开发效率和构建速度。以下是对 Turborepo 的详细使用指南：

1. 安装与初始化

首先，确保你已经安装了 Node.js 和 npm 或 Yarn。然后，可以通过以下命令安装 Turborepo：

npm install turbo --global

或者使用 Yarn：

yarn global add turbo

接下来，初始化一个新的 Turborepo 项目：

npx create-turbo@latest

这将引导你完成项目的初始化过程，并生成一个基本的项目结构。

2. 项目结构

Turborepo 项目通常包含多个包（packages），每个包可以是一个独立的应用程序或库。典型的项目结构如下：

my-turborepo/
├── apps/
│   ├── web/
│   └── api/
├── packages/
│   ├── ui/
│   └── utils/
├── package.json
└── turbo.json

• apps/ 目录包含应用程序（如前端应用、后端服务等）。
• packages/ 目录包含共享的库或工具。
• turbo.json 是 Turborepo 的配置文件。

3. 配置 turbo.json

turbo.json 文件用于定义 Turborepo 的构建和任务执行策略。以下是一个简单的配置示例：

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": []
    },
    "lint": {
      "outputs": []
    }
  }
}

• pipeline 定义了任务及其依赖关系。
• dependsOn 指定任务依赖的其他任务。^build 表示依赖所有包的 build 任务。
• outputs 指定任务生成的文件或目录。

4. 运行任务

Turborepo 提供了 turbo run 命令来执行定义的任务。例如，运行所有包的 build 任务：

turbo run build

你也可以指定特定的包来运行任务：

turbo run build --filter=web

5. 缓存与增量构建

Turborepo 通过缓存机制实现了增量构建，显著提升了构建速度。每次任务执行后，Turborepo 会缓存输出文件。下次运行相同任务时，如果输入文件没有变化，Turborepo 会直接使用缓存结果。

你可以通过以下命令清理缓存：

turbo run clean

6. 与 CI/CD 集成

Turborepo 可以轻松集成到 CI/CD 流程中。通过 turbo run 命令，你可以在 CI 环境中并行执行任务，从而加快构建和测试过程。

例如，在 GitHub Actions 中集成 Turborepo：

name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install dependencies
        run: yarn install
      - name: Build
        run: turbo run build
      - name: Test
        run: turbo run test

7. 高级配置

Turborepo 支持多种高级配置选项，如自定义缓存目录、并行任务数等。你可以在 turbo.json 中进一步配置这些选项：

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"],
      "cache": {
        "enabled": true,
        "path": ".turbo-cache"
      },
      "parallel": true
    }
  }
}

• cache.enabled 控制是否启用缓存。
• cache.path 指定缓存目录。
• parallel 控制是否并行执行任务。

8. 最佳实践

• 模块化设计：将共享代码提取到 packages/ 目录中，以便在多个应用程序中复用。
• 任务依赖管理：合理定义任务依赖关系，避免不必要的重复构建。
• 缓存优化：确保 outputs 配置正确，避免缓存无效文件。
• CI/CD 集成：在 CI/CD 流程中充分利用 Turborepo 的并行执行能力，提升构建效率。

9. 常见问题与解决方案

• 缓存失效：确保 outputs 配置正确，避免缓存无效文件。
• 任务执行顺序：通过 dependsOn 明确任务依赖关系，避免任务执行顺序错误。
• 性能瓶颈：合理配置 parallel 选项，避免过度并行导致资源竞争。

通过以上指南，你可以充分利用 Turborepo 的强大功能，提升多包项目的开发效率和构建速度。