turborepo-monorepo

Turborepo Monorepo

概述

提供 Turborepo Monorepo 管理指南：创建工作区、配置 turbo.json 任务、集成 Next.js/NestJS、设置测试流水线（Vitest/Jest）、配置 CI/CD，以及优化构建性能。

适用场景

• 创建或初始化 Turborepo 工作区
• 配置带有依赖项和输出的 turbo.json 任务
• 在 Monorepo 结构中设置 Next.js/NestJS 应用
• 配置 Vitest/Jest 测试流水线
• 构建 CI/CD 工作流（GitHub Actions、GitLab CI）
• 使用 Vercel Remote Cache 实现远程缓存
• 优化构建时间和缓存命中率
• 调试任务依赖或缓存问题
• 从其他 Monorepo 工具迁移到 Turborepo

操作说明

创建工作区

1. 创建新工作区：

   pnpm create turbo@latest my-workspace
   cd my-workspace
   

2. 在现有项目中初始化：

   pnpm add -D -w turbo
   

3. 在根目录创建 turbo.json（最小配置）：

   {
     "$schema": "https://turborepo.dev/schema.json",
     "pipeline": {
       "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"] },
       "lint": { "outputs": [] },
       "test": { "dependsOn": ["build"], "outputs": ["coverage/**"] }
     }
   }
   

4. 在根目录的 package.json 中添加脚本：

   { "scripts": { "build": "turbo run build", "dev": "turbo run dev", "lint": "turbo run lint", "test": "turbo run test", "clean": "turbo run clean" } }
   

5. 在 CI 运行前验证任务图：

   turbo run build --dry-run --filter=...  # Verify task execution order
   

任务配置

1. 在 turbo.json 中配置任务：

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

2. 运行任务：

   turbo run build                      # All packages
   turbo run lint test build           # Multiple tasks
   turbo run build --filter=web       # Specific package
   

3. 并行进行类型检查（使用中转节点以避免缓存问题）：

   { "pipeline": { "transit": { "dependsOn": ["^transit"] }, "typecheck": { "dependsOn": ["transit"] } } }
   

4. 提交前验证：

   turbo run build --dry-run  # Check task order and affected packages
   

框架集成

**Next.js：**输出 ".next/**"，环境变量 ["NEXT_PUBLIC_*"] ——参见 references/nextjs-config.md

**NestJS：**输出 "dist/**"，dev 任务使用 cache: false, persistent: true ——参见 references/nestjs-config.md

测试设置

1. Vitest 配置：

   {
     "pipeline": {
       "test": {
         "outputs": [],
         "inputs": ["$TURBO_DEFAULT$", "vitest.config.ts"]
       },
       "test:watch": {
         "cache": false,
         "persistent": true
       }
     }
   }
   

2. 运行受影响的测试：

   turbo run test --filter=[HEAD^]
   

   有关完整的测试设置，请参见 references/testing-config.md。

包配置

1. 创建包专属的 turbo.json：

   {
     "extends": ["//"],
     "tasks": {
       "build": {
         "outputs": ["$TURBO_EXTENDS$", ".next/**"]
       }
     }
   }
   

   有关详细的包配置模式，请参见 references/package-configs.md。

CI/CD 设置

1. 带有验证检查点的 GitHub Actions：

   - name: Install dependencies
     run: pnpm install
   
   - name: Validate affected packages (dry-run)
     run: pnpm turbo run build --filter=[HEAD^] --dry-run
     # VALIDATE: Review output to confirm only expected packages will build
   
   - name: Run tests
     run: pnpm run test --filter=[HEAD^]
   
   - name: Build affected packages
     run: pnpm run build --filter=[HEAD^]
   
   - name: Verify cache hits
     run: pnpm turbo run build --filter=[HEAD^] --dry-run | grep "Cache"
     # VALIDATE: Confirm cache hits for unchanged packages
   

2. 设置远程缓存：

   # Login to Vercel
   npx turbo login
   
   # Link repository
   npx turbo link
   

   有关完整的 CI/CD 设置示例，请参见 references/ci-cd.md。

任务属性参考

属性	描述	示例
dependsOn	必须先完成的任务	["^build"] - 先处理依赖项
outputs	要缓存的文件/文件夹	["dist/**"]
inputs	用于生成缓存哈希的文件	["src/**/*.ts"]
env	会影响哈希的环境变量	["DATABASE_URL"]
cache	启用/禁用缓存	true 或 false
persistent	长时间运行的任务	dev 服务使用 true
outputLogs	日志详细程度	"full"、"new-only"、"errors-only"

依赖模式

• ^task - 先按拓扑顺序在依赖项中运行任务
• task - 先在同一包中运行任务
• package#task - 运行指定包的任务

筛选语法

筛选器	描述
web	仅 web 包
web...	web 包及其所有依赖项
...web	web 包及所有依赖它的包
...web...	web 包、其依赖项及所有依赖它的包
[HEAD^]	自上次提交以来发生变更的包
./apps/*	apps/ 中的所有包

最佳实践

性能优化

1. 使用明确的 outputs - 只缓存所需内容
2. 精细调整 inputs - 排除不会影响输出的文件
3. 中转节点 - 启用并行类型检查
4. 远程缓存 - 在团队和 CI 之间共享缓存
5. 包配置 - 自定义各包的行为

缓存策略

{
  "pipeline": {
    "build": {
      "outputs": ["dist/**"],
      "inputs": ["$TURBO_DEFAULT$", "!README.md", "!**/*.md"]
    }
  }
}

任务组织

• 独立任务 - 不设置 dependsOn：lint、format、spellcheck
• 构建任务 - dependsOn: ["^build"]：build、compile
• 测试任务 - dependsOn: ["build"]：test、e2e
• dev 任务 - cache: false, persistent: true：dev、watch

常见问题

任务未按顺序运行

**问题：**任务执行顺序错误

**解决方案：**检查 dependsOn 配置

{
  "build": {
    "dependsOn": ["^build"]
  }
}

未更改文件的缓存未命中

问题： 缓存意外失效

解决方案： 检查 globalDependencies 和 inputs

{
  "globalDependencies": ["tsconfig.json"],
  "pipeline": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", "!*.md"]
    }
  }
}

缓存命中后出现类型错误

问题： 缓存导致 TypeScript 错误未被捕获

解决方案： 使用中间节点进行类型检查

{
  "transit": { "dependsOn": ["^transit"] },
  "typecheck": { "dependsOn": ["transit"] }
}

示例

示例 1：创建新工作区

输入：“创建一个使用 Next.js 和 NestJS 的 Turborepo”

pnpm create turbo@latest my-workspace
cd my-workspace

# Add Next.js app
pnpm add next react react-dom -F apps/web

# Add NestJS API
pnpm add @nestjs/core @nestjs/common -F apps/api

示例 2：配置测试流水线

输入：“为所有包设置 Vitest”

{
  "pipeline": {
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "inputs": ["$TURBO_DEFAULT$", "vitest.config.ts"]
    },
    "test:watch": {
      "cache": false,
      "persistent": true
    }
  }
}

示例 3：在 CI 中运行受影响的测试

输入：“在 CI 中只测试有更改的包”

pnpm run test --filter=[HEAD^]

示例 4：调试缓存问题

输入：“为什么我的缓存未命中？”

# Dry run to see what would be executed
turbo run build --dry-run --filter=web

# Show hash inputs
turbo run build --force --filter=web

限制和警告

• Turborepo 需要 Node.js 18+
• 根目录的 package.json 中必须包含 Package manager 字段
• 必须指定 输出内容，缓存才能正常工作
• 持久任务不能有依赖项
• Windows：建议使用 WSL 或 Git Bash
• 远程缓存需要 Vercel 账户或可自托管的解决方案
• 大型单体仓库可能需要调高 concurrency 设置

参考文件

如需了解特定主题的详细指导，请参阅：

主题	参考文件
turbo.json 模板	references/turbo.json
Next.js 集成	references/nextjs-config.md
NestJS 集成	references/nestjs-config.md
Vitest/Jest/Playwright	references/testing-config.md
GitHub/CircleCI/GitLab CI	references/ci-cd.md
包配置	references/package-configs.md