Monorepo是什么

Mr.lujhua2026年1月7日大约 11 分钟

Monorepo（单一代码库）是一种软件开发策略，将多个项目的代码存储在同一个版本控制系统仓库中。这种方法与传统的多仓库（Polyrepo）策略形成对比，后者为每个项目使用单独的仓库。

1. 什么是Monorepo

Monorepo是"Monolithic Repository"的缩写，指的是在一个单一的代码仓库中管理多个项目或模块的代码。这些项目可以是相关的，也可以是不相关的，但它们共享同一个版本控制系统、构建工具和工作流。

1.1 Monorepo的核心特征

单一仓库：所有项目代码存储在同一个Git仓库中
共享工具链：统一的构建、测试、部署工具和配置
代码共享：项目之间可以轻松共享代码和依赖
原子提交：跨项目的更改可以在单个提交中完成
统一版本控制：所有项目共享同一个版本历史

1.2 Monorepo vs Polyrepo

特性	Monorepo	Polyrepo
代码共享	简单，直接引用	复杂，需要发布npm包
版本控制	单一仓库，统一版本历史	多个仓库，独立版本历史
构建工具	统一配置，共享缓存	每个项目独立配置
跨项目更改	原子提交，易于跟踪	需要多个PR，难以协调
依赖管理	统一安装，避免重复	每个项目独立安装，可能重复
权限管理	相对复杂	简单，基于仓库粒度
仓库大小	通常较大	通常较小

2. Monorepo的优势

2.1 代码共享与复用

Monorepo允许在项目之间轻松共享代码和组件，无需将它们发布为npm包。这减少了代码重复，提高了开发效率和代码一致性。

// Monorepo中共享组件示例
// packages/ui-components/src/Button.jsx
export const Button = ({ children, onClick }) => {
  return <button onClick={onClick}>{children}</button>;
};

// apps/web-app/src/App.jsx
import { Button } from '@my-org/ui-components';

function App() {
  return <Button onClick={() => alert('Clicked')}>Click me</Button>;
}

2.2 简化依赖管理

在Monorepo中，所有项目共享同一个依赖树，可以避免重复安装相同的依赖，减少磁盘空间占用和安装时间。同时，升级依赖变得更加容易，只需在一个地方更新版本。

// package.json (根目录)
{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "workspaces": [
    "packages/*",
    "apps/*"
  ]
}

2.3 跨项目更改的原子性

在Monorepo中，可以在单个提交中完成跨多个项目的更改，确保相关更改始终保持同步。这对于API变更、重构或依赖升级特别有用。

# 单个提交中更新API和所有使用它的项目
git commit -m "Update user API and all consuming projects"

2.4 统一的开发工作流

Monorepo允许在整个代码库中使用统一的构建、测试、 linting和部署工具，确保所有项目遵循相同的标准和最佳实践。

// turbo.json (Turborepo配置)
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": []
    },
    "lint": {
      "outputs": []
    }
  }
}

2.5 更好的协作和可见性

Monorepo提供了整个代码库的完整视图，使团队成员能够更容易地了解项目之间的关系和依赖。这促进了更好的协作和知识共享。

3. Monorepo的挑战

3.1 仓库大小和性能问题

随着项目数量和代码量的增长，Monorepo的大小可能会变得非常大，导致克隆、拉取和构建速度变慢。

3.2 构建时间优化

在大型Monorepo中，构建所有项目可能需要很长时间。需要实现智能缓存和增量构建来提高效率。

3.3 权限管理复杂性

在Monorepo中，实现细粒度的权限控制（如限制某些团队只能访问特定项目）可能变得更加复杂。

3.4 CI/CD配置复杂性

为Monorepo配置CI/CD流程需要更多的工作，以确保只有更改的项目被重新构建和测试。

3.5 版本控制策略

在Monorepo中，需要决定是使用单一版本号（如Lerna的fixed模式）还是为每个项目使用独立版本号（如Lerna的independent模式）。

4. 主流Monorepo工具

4.1 Lerna

Lerna是一个流行的JavaScript Monorepo管理工具，由Babel团队创建。它提供了版本管理、依赖管理和发布功能。

核心特性

版本管理和发布
依赖链接
并行执行命令
支持fixed和independent版本模式

安装和使用

# 安装Lerna
npm install -g lerna

# 初始化Lerna仓库
lerna init

# 安装所有依赖
lerna bootstrap

# 运行所有项目的测试
lerna run test

# 发布所有更改的包
lerna publish

4.2 Nx

Nx是一个功能强大的Monorepo构建系统，专注于性能和可扩展性。它提供了智能缓存、增量构建和代码生成功能。

核心特性

智能缓存和增量构建
代码生成和脚手架
依赖图可视化
分布式任务执行
支持多种框架（React、Vue、Angular等）

安装和使用

# 安装Nx
npm install -g nx

# 创建Nx工作区
npx create-nx-workspace@latest

# 生成新的React应用
nx g @nrwl/react:app my-app

# 运行应用
nx serve my-app

# 构建应用
nx build my-app

# 运行所有测试
nx run-many --target=test

4.3 Turborepo

Turborepo是一个高性能的Monorepo构建系统，由Vercel创建。它专注于速度和简单性，提供了智能缓存和并行执行功能。

核心特性

极快的构建速度
智能缓存（本地和远程）
并行任务执行
依赖图优化
与npm/yarn/pnpm工作区兼容

安装和使用

# 安装Turborepo
npx create-turbo@latest

# 构建所有项目
turbo build

# 运行所有测试
turbo test

# 运行特定项目的开发服务器
turbo dev --filter=web-app

4.4 Yarn Workspaces

Yarn Workspaces是Yarn的内置功能，允许在Monorepo中管理多个包。它提供了依赖链接和统一安装功能。

核心特性

依赖链接
统一安装
避免依赖重复
与Yarn无缝集成

配置示例

// package.json (根目录)
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": [
    "packages/*",
    "apps/*"
  ],
  "scripts": {
    "build": "yarn workspace @my-org/ui-components build && yarn workspace web-app build"
  }
}

5. Monorepo的最佳实践

5.1 合理组织目录结构

采用清晰的目录结构，将不同类型的项目分开管理。

my-monorepo/
├── apps/              # 应用程序
│   ├── web-app/       # Web应用
│   └── mobile-app/    # 移动应用
├── packages/          # 可共享的包
│   ├── ui-components/ # UI组件库
│   ├── utils/         # 工具函数库
│   └── api/           # API客户端
├── package.json       # 根package.json
└── turbo.json         # Turborepo配置

5.2 实现智能缓存

使用工具如Nx或Turborepo的智能缓存功能，避免重复构建和测试未更改的代码。

// turbo.json
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": [],
      "inputs": ["src/**/*.ts", "src/**/*.tsx", "test/**/*.ts"]
    }
  }
}

5.3 建立清晰的版本控制策略

根据项目需求选择合适的版本控制策略：

Fixed模式：所有包使用相同的版本号（适合紧密相关的项目）
Independent模式：每个包使用独立的版本号（适合相对独立的项目）

5.4 优化CI/CD流程

配置CI/CD流程，只构建和测试更改的项目和其依赖项。

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

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm install
      - run: npx turbo build --filter=...[HEAD^1]

5.5 建立代码规范和质量检查

在整个Monorepo中实施统一的代码规范、linting和类型检查。

// .eslintrc.js (根目录)
module.exports = {
  root: true,
  extends: ['@my-org/eslint-config'],
  overrides: [
    {
      files: ['*.ts', '*.tsx'],
      parserOptions: {
        project: './tsconfig.json'
      }
    }
  ]
};