使用Turborepo管理Monorepo前端项目2026

本文详解使用Turborepo管理前端Monorepo的完整方案。

什么是Monorepo

多仓库(Multi-repo) Monorepo
各项目独立仓库 所有项目在一个仓库
依赖重复安装 依赖共享
跨项目修改困难 原子性提交
CI/CD各自配置 统一CI/CD流水线

为什么选择Turborepo

工具 缓存 分布式缓存 配置复杂度
Lerna ❌ ❌ 高
Nx ✅ ✅ (付费) 高
Turborepo ✅ ✅ (免费) 低

初始化Turborepo项目

快速启动

# 使用官方模板
npx create-turbo@latest

# 选择：
# - 包管理器：pnpm（推荐）
# - 项目名：my-turbo-app

目录结构

my-turbo-app/
├── apps/
│   ├── web/          # Next.js 网站
│   ├── docs/         # VitePress 文档
│   └── admin/        # React 管理后台
├── packages/
│   ├── ui/           # 共享UI组件
│   ├── utils/         # 共享工具函数
│   └── config/       # 共享ESLint/TS配置
├── turbo.json         # Turborepo配置
├── package.json
└── pnpm-workspace.yaml

配置 turbo.json

{
  "$schema": "https://turborepo.org/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  },
  "remoteCache": {
    "enabled": true
  }
}

配置说明

// pipeline 定义任务依赖
"build": {
  "dependsOn": ["^build"],  // 先构建依赖包
  "outputs": [".next/**"],   // 缓存这些输出
}

// dev 任务不缓存（持久运行）
"dev": {
  "cache": false,
  "persistent": true
}

添加共享包

创建UI组件包

# 创建 packages/ui
mkdir -p packages/ui/src

# 初始化 package.json
cd packages/ui
npm init -y

// packages/ui/package.json
{
  "name": "@myapp/ui",
  "version": "0.0.1",
  "main": "./src/index.ts",
  "scripts": {
    "build": "tsc",
    "lint": "eslint ."
  }
}

// packages/ui/src/button.tsx
import React from 'react';

export const Button = ({ children, onClick }) => (
  <button onClick={onClick} style={{ padding: '8px 16px' }}>
    {children}
  </button>
);

在应用中使用共享包

// apps/web/package.json
{
  "dependencies": {
    "@myapp/ui": "workspace:*"
  }
}

// apps/web/pages/index.tsx
import { Button } from '@myapp/ui';

export default function Home() {
  return (
    <div>
      <h1>My Site</h1>
      <Button onClick={() => alert('Clicked!')}>Click me</Button>
    </div>
  );
}

远程缓存配置（Vercel/自定义）

使用Vercel远程缓存

# 登录Vercel
npx turbo login

# 链接项目
npx turbo link

# 现在 turbo run build 会自动使用远程缓存
npm run build

自托管远程缓存（Docker）

# docker-compose.yml
version: '3.8'
services:
  turborepo-cache:
    image: vercel/turb_repo-remote-cache:latest
    environment:
      - TURBO_TOKEN=your-secret-token
    ports:
      - "8080:8080"
    volumes:
      - cache:/cache

volumes:
  cache:

# 配置环境变量
export TURBO_REMOTE_ONLY=true
export TURBO_TOKEN=your-secret-token
export TURBO_API=http://localhost:8080

# 运行构建（使用自托管缓存）
turbo run build

优化构建速度

1. 精确配置 outputs

// turbo.json
{
  "pipeline": {
    "build": {
      "outputs": [
        "dist/**",          // 确保只缓存构建输出
        ".next/**",         // Next.js 构建输出
        "!dist/**/*.map"    // 排除 source maps（不需要缓存）
      ]
    }
  }
}

2. 使用 pnpm 的严格模式

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

# .npmrc
strict-peer-deps=true
auto-install-peers=true

3. 并行执行任务

# Turborepo 自动并行独立任务
turbo run build  # 所有应用的 build 并行执行

# 限制并行数量（防止内存不足）
turbo run build --concurrency=4

CI/CD 集成（GitHub Actions）

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - uses: pnpm/action-setup@v2
        with:
          version: 8

      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'pnpm'

      - run: pnpm install

      - run: pnpm turbo run build --cache-dir=.turbo
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ secrets.TURBO_TEAM }}

      - run: pnpm turbo run lint test  # 并行执行 lint 和 test

常见问题

问题 原因 解决方案
缓存不生效 outputs 配置错误 检查 turbo.json 中的 outputs 路径
构建顺序错误 dependsOn 配置错误 使用 ^build 表示先构建依赖
远程缓存失败 TURBO_TOKEN 未设置 检查 CI 环境变量
pnpm 依赖错误 workspace:* 未正确解析 运行 pnpm install -r

最佳实践

  1. 小而专注的包：每个包只做一件事
  2. 明确的依赖关系：使用 dependsOn 定义任务依赖
  3. 充分利用缓存：确保 outputs 配置正确
  4. 远程缓存：团队共享缓存，加速 CI/CD
  5. 渐进迁移：从单个仓库开始，逐步拆分包

性能对比

操作 无缓存 本地缓存 远程缓存
首次构建 10min 10min 10min
二次构建（无变更） 10min 30s 30s
团队成员首次构建 10min 10min 30s

Turborepo 通过智能缓存和并行执行，可以将 Monorepo 的构建时间从 10 分钟减少到 30 秒。

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。