Node.js Turbo 包入门教程

一、Turbo 是什么？

Turbo 是 Vercel 开发的高性能构建工具，专为 Monorepo（多包仓库）设计，核心功能包括：

• 任务并行执行：自动解析任务依赖，并行运行独立任务。
• 智能缓存：复用上一次成功执行的结果，加速 CI/CD。
• 依赖图管理：通过 turbo.json 定义任务流程，支持全局依赖。
• 跨平台兼容：支持 Windows、macOS、Linux。

二、快速入门：从安装到第一个任务

1. 安装 Turbo

全局安装（推荐）

npm install turbo --global
# 或
yarn global add turbo

本地安装（项目内使用）

npm install turbo --save-dev
# 或
yarn add turbo --dev

2. 初始化 Turbo 配置

在项目根目录运行：

turbo init

此命令会生成 turbo.json 文件，定义任务管道和全局依赖。

3. 创建示例 Monorepo 项目

项目结构

my-project/
├── packages/
│   ├── app1/
│   │   └── package.json
│   └── app2/
│       └── package.json
├── package.json
└── turbo.json

示例 turbo.json

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

三、核心命令：turbo run 详解

1. 基本用法

并行执行任务

turbo run build

Turbo 会自动解析依赖关系，并行执行无依赖冲突的任务。

指定目标包

turbo run build --filter=app1

仅构建 app1 包。

过滤文件变更

turbo run build --filter=...[origin/main]

仅构建自 main 分支以来有变更的包。

2. 高级参数

并行执行（强制）

turbo run test --parallel

忽略任务依赖，强制并行执行（需谨慎使用）。

跳过依赖解析

turbo run build --no-deps

不解析任务依赖，直接执行（适合独立任务）。

清理缓存

turbo run build --force

跳过缓存，强制重新执行任务。

3. 输出与日志

简化日志

turbo run build --log-prefix=none

隐藏日志前缀，适合 CI/CD 流水线。

生成 JSON 输出

turbo run build --json > output.json

获取结构化任务执行结果，便于自动化处理。

四、实战示例：构建 Monorepo 项目

1. 定义任务管道

在 turbo.json 中定义 build 和 test 任务：

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

2. 执行构建与测试

turbo run build test

Turbo 会先执行所有包的 build 任务，再并行执行 test 任务。

3. 利用缓存加速

首次执行

turbo run build --cache

Turbo 会缓存构建结果到 node_modules/.turbo。

后续执行

turbo run build --cache

仅重新执行变更的包，复用缓存结果。

五、Turbo vs Lerna：为何选择 Turbo？

六、最佳实践与常见问题

1. 最佳实践

• 定义全局依赖：在 turbo.json 中声明 .env 等全局文件，避免重复执行。
• 合理拆分任务：将耗时任务（如构建）与快速任务（如 lint）分离。
• 利用缓存：在 CI/CD 中启用 --cache，减少重复构建。

2. 常见问题

Q: 如何排除特定包？

A: 使用 --filter=!app1 排除 app1 包：

turbo run build --filter=!app1

Q: 如何传递参数给任务？

A: 通过 -- 传递参数：

turbo run build -- --scope=app1

Q: 如何清理 Turbo 缓存？

A: 删除 node_modules/.turbo 目录：

rm -rf node_modules/.turbo

七、总结

Turbo 是 Node.js Monorepo 项目的终极工具，通过 turbo run 命令可实现：

• 智能任务调度：自动解析依赖，并行执行。
• 极速构建：利用缓存复用结果，减少重复工作。
• 跨包依赖管理：通过 turbo.json 统一配置。

掌握 Turbo 后，可显著提升大型项目的开发效率，尤其适合前端工程化场景。