多包工作区使用#

官方文档中，关于 在多包工作区（monorepo）中添加 Turborepo 的部分，核心步骤如下：

1. 前提准备
   Turborepo 基于包管理器的 Workspaces 功能，因此你需要确保仓库已配置好 workspaces（如 pnpm-workspace.yaml 或 package.json 中的 workspaces 字段）。

2. 安装 turbo
   推荐在仓库根目录安装 turbo 作为开发依赖，同时全局安装以获得更好体验：

   1
   # 以 pnpm 为例
   2
   pnpm add turbo --save-dev --workspace-root
   3
   pnpm add turbo --global

3. 配置 turbo.json
   在根目录创建 turbo.json，定义任务（如 build、check-types）。关键配置包括：

1
{
2
  "$schema": "https://turborepo.dev/schema.json",
3
  "tasks": {
4
    "build": {
5
      "dependsOn": ["^build"],
6
      "outputs": [".next/**", "!.next/cache/**"]
7
    },
8
    "check-types": {
9
      "dependsOn": ["^check-types"]
10
    },
11
    "dev": {
12
      "persistent": true,
13
      "cache": false
14
    }
15
  }
16
}

• dependsOn: ["^build"]：表示任务的依赖（^build 表示依赖上游包的 build 任务）。
• outputs：指定缓存输出目录。
• 对于开发任务设置 persistent: true 和 cache: false。

4. 调整包脚本
   确保各包的 package.json 中包含与 turbo.json 中任务对应的脚本（如 check-types）。建议将组合命令（如 tsc && vite build）拆分为独立的 check-types 和 build 脚本。

1
{
2
  "scripts": {
3
    "check-types": "tsc --noEmit",
4
    "build": "vite build"
5
  }
6
}

5. 忽略 turbo 缓存目录
   在 .gitignore 中添加 .turbo，避免缓存文件被提交。

6. 声明包管理器
   在根 package.json 中添加 packageManager 字段（如 "pnpm@10.0.0"），帮助 Turborepo 优化行为。

7. 配置包管理器 workspaces
   在 pnpm-workspace.yaml 或 package.json 中声明子包目录模式（如 "apps/*"、"packages/*"），让包管理器识别所有包。

8. 运行任务
   使用 turbo build check-types 等命令运行任务。Turborepo 会根据依赖图并行执行，并利用缓存加速（第二次运行可能仅需 185ms）。

终端输出结果:

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

9. 启动开发环境
   运行 turbo dev 可同时启动所有包的开发任务，或使用 --filter 参数聚焦特定包。

在单一包工作区#

单一包工作区,指的是运行 npx create-next-app 或 npm create vite 后得到的。

1
pnpm add turbo --save-dev
2

3
yarn add turbo --dev
4

5
npm install turbo --save-dev
6

7
bun install turbo --dev

1
{
2
  "scripts": {
3
    "dev": "next dev",                    // 最终要运行的开发服务器
4
    "db:up": "docker-compose up -d",     // 启动数据库容器
5
    "db:push": "your-orm-tool schema-push", // 推送数据库结构
6
    "db:seed": "node ./db-seed.js"       // 填充初始数据
7
  }
8
}

1
{
2
  "$schema": "https://turborepo.dev/schema.json",
3
  "tasks": {
4
    "dev": {
5
      "dependsOn": ["db:seed"],
6
      "cache": false,
7
      "persistent": true
8
    },
9
    "db:seed": {
10
      "dependsOn": ["db:push"],
11
      "cache": false
12
    },
13
    "db:push": {
14
      "dependsOn": ["db:up"],
15
      "cache": false
16
    },
17
    "db:up": {
18
      "cache": false
19
    }
20
  }
21
}

1
# 串行执行方式（慢）
2
npm run lint && npm run check-types && npm run format
3
# 总耗时 = lint时间 + check-types时间 + format时间

1
turbo lint check-types format
2
# 总耗时 ≈ max(lint时间, check-types时间, format时间)

1
{
2
  "scripts": {
3
    "lint": "eslint .",
4
    "format": "prettier .",
5
    "check-types": "tsc --noEmit"
6
  }
7
}

1
{
2
  "$schema": "https://turborepo.dev/schema.json",
3
  "tasks": {
4
    "lint": {},
5
    "format": {},
6
    "check-types": {}
7
  }
8
}

1
turbo run lint check-types format