Monorepo 架构以及工具选型、搭建

Monorepo（Monolithic Repository，单体仓库）是一种代码管理策略 ，核心是将一个项目的所有相关代码（包括多个应用、库、工具链等）集中存储在单个代码仓库中，而非按模块拆分到多个独立仓库（Multirepo）。

📑 目录

• 快速参考
• [什么是 Monorepo](#什么是 Monorepo "#%E4%BB%80%E4%B9%88%E6%98%AF-monorepo")
  • [Monorepo vs Multirepo](#Monorepo vs Multirepo "#monorepo-vs-multirepo")
  • [Monorepo 的优缺点](#Monorepo 的优缺点 "#monorepo-%E7%9A%84%E4%BC%98%E7%BC%BA%E7%82%B9")
  • 经典案例
• [何时使用 Monorepo](#何时使用 Monorepo "#%E4%BD%95%E6%97%B6%E4%BD%BF%E7%94%A8-monorepo")
• 工具选型
  • 工作区管理工具
  • 任务调度工具
  • 版本管理工具
  • 代码质量工具
• 实战搭建
  • [1. 初始化基础环境](#1. 初始化基础环境 "#1-%E5%88%9D%E5%A7%8B%E5%8C%96%E5%9F%BA%E7%A1%80%E7%8E%AF%E5%A2%83")
  • [2. 配置 pnpm 工作区](#2. 配置 pnpm 工作区 "#2-%E9%85%8D%E7%BD%AE-pnpm-%E5%B7%A5%E4%BD%9C%E5%8C%BA")
  • [3. 配置 Turbo](#3. 配置 Turbo "#3-%E9%85%8D%E7%BD%AE-turbo")
  • [4. 根目录 package.json 配置](#4. 根目录 package.json 配置 "#4-%E6%A0%B9%E7%9B%AE%E5%BD%95-packagejson-%E9%85%8D%E7%BD%AE")
  • [5. 搭建核心包](#5. 搭建核心包 "#5-%E6%90%AD%E5%BB%BA%E6%A0%B8%E5%BF%83%E5%8C%85")
  • [6. 搭建文档站点](#6. 搭建文档站点 "#6-%E6%90%AD%E5%BB%BA%E6%96%87%E6%A1%A3%E7%AB%99%E7%82%B9")
  • [7. 搭建示例项目](#7. 搭建示例项目 "#7-%E6%90%AD%E5%BB%BA%E7%A4%BA%E4%BE%8B%E9%A1%B9%E7%9B%AE")
  • [8. 核心命令使用](#8. 核心命令使用 "#8-%E6%A0%B8%E5%BF%83%E5%91%BD%E4%BB%A4%E4%BD%BF%E7%94%A8")
  • [9. 版本管理与发布](#9. 版本管理与发布 "#9-%E7%89%88%E6%9C%AC%E7%AE%A1%E7%90%86%E4%B8%8E%E5%8F%91%E5%B8%83")
• 高级配置
  • [Turbo 缓存优化](#Turbo 缓存优化 "#turbo-%E7%BC%93%E5%AD%98%E4%BC%98%E5%8C%96")
  • [CI/CD 集成](#CI/CD 集成 "#cicd-%E9%9B%86%E6%88%90")
  • 依赖管理策略
• 最佳实践
• 常见问题

---

快速参考

工具选型速查表

工具类型	推荐工具	适用场景	备选方案
包管理器	pnpm workspace	磁盘效率高、安装速度快	npm workspace、yarn workspace
任务调度	Turbo	增量构建、并行任务、缓存	Nx（企业级）、Rush（大型项目）
版本管理	Changeset	monorepo 友好的版本管理	release-it（单包）、Lerna（传统）

快速开始

# 1. 初始化项目
mkdir your-project && cd your-project
pnpm init -y

# 2. 安装 Turbo
pnpm add turbo -D -w

# 3. 配置工作区
# 创建 pnpm-workspace.yaml

# 4. 配置 Turbo
# 创建 turbo.json

# 5. 创建子包
mkdir -p packages/core docs examples/basic

---

什么是 Monorepo

简单类比

• Multirepo ：像多个独立的文件夹，每个项目 / 库单独存放（比如 react、react-dom、react-router 各一个仓库）
• Monorepo ：像一个大文件夹，里面按功能分类存放所有相关项目（比如 Facebook 的 facebook/react 仓库，包含 React 核心、文档、示例、相关工具等所有代码）

常用结构

monorepo-root/
├── packages/          # 所有可复用包（库、工具）
│   ├── utils/         # 通用工具库
│   ├── components/     # UI 组件库
│   └── cli/           # 命令行工具
├── apps/              # 可部署应用
│   ├── web/           # 网页应用
│   └── admin/         # 管理后台
├── scripts/           # 全局构建/测试脚本
├── package.json       # 根项目配置（依赖、脚本）
└── pnpm-workspace.yaml # 工作区配置（pnpm 为例）

Monorepo vs Multirepo

对比维度	Multirepo（多仓库）	Monorepo（单仓库）
依赖管理	重复安装，版本不一致，易冲突	共享依赖，版本统一，减少冗余
跨项目引用	需发布 npm / 用相对路径，同步修改繁琐	本地直接引用，修改实时生效，无需发布
工程化规范	各仓库独立配置，维护成本高	根目录统一配置，所有子项目继承
代码复用	复制粘贴或发布私有包，复用成本高	仓库内直接复用，抽离库更便捷
版本管理与发布	手动协调多包版本（如 A 依赖 B，B 升级后 A 需手动更新）	工具自动管理版本依赖（如 Changeset），批量发布
协作效率	跨仓库 PR 联动复杂，代码审查分散	所有代码在一个仓库，PR 集中，协作更高效

Monorepo 的优缺点

优点：

• ✅ 高效协作：所有代码集中管理，跨项目修改无需切换仓库，PR 集中审查
• ✅ 规范统一：工程化配置（lint、测试、构建）全局统一，降低维护成本
• ✅ 依赖优化：共享依赖减少安装体积，版本统一避免冲突
• ✅ 代码复用：子包间直接引用，无需发布，迭代速度快

缺点：

• ❌ 仓库体积增大：随着项目增多，仓库体积会变大，但现代 Git（如 Git LFS）可缓解
• ❌ 构建速度：大型 Monorepo 全量构建较慢，需借助 Turborepo 等工具实现增量构建和缓存
• ❌ 权限控制：难以对单个子包进行精细化权限控制（如需控制，可结合 Git 子模块或企业级工具如 GitLab Enterprise）

经典案例

前端 Monorepo 经典案例：

• React ：facebook/react 仓库包含 React 核心、React DOM、React Server Components 等所有相关代码
• Vue ：vuejs/core 仓库包含 Vue 3 核心、编译器、运行时等
• Vite ：vitejs/vite 仓库包含 Vite 核心、官方插件（如 @vitejs/plugin-react）等
• Tailwind CSS ：tailwindlabs/tailwindcss 仓库包含核心库、CLI、插件等

---

何时使用 Monorepo

当你的项目满足以下 2 个及以上条件时，优先选择 Monorepo：

• ✅ 需拆分独立模块（核心包 + 文档 + 示例是典型场景）
• ✅ 模块间有依赖关系（如示例依赖核心包、文档引用核心包 API）
• ✅ 需统一构建、测试、发布流程
• ✅ 追求高效开发（增量构建、并行任务）

何时不使用 Monorepo：

• ❌ 单一核心包 + 简单 README 文档（单包架构足够）
• ❌ 子包之间完全独立，无依赖关系
• ❌ 团队规模小，维护成本高

---

工具选型

工作区管理工具

负责管理多包的依赖安装、路径映射、脚本执行，主流选择：

工具	磁盘效率	安装速度	monorepo 支持	适用场景
pnpm workspace	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	推荐，生态最优
npm workspace	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	npm 7+ 原生支持
yarn workspace	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	Yarn 1.x 传统方案
Lerna	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐	早期方案，已过时

选型建议：

• 推荐：pnpm workspace（磁盘效率高、安装速度快、生态完善）
• 备选：npm workspace（npm 7+ 原生支持，无需额外配置）

核心特性：

• pnpm workspace ：轻量、快速，原生支持 Monorepo，通过 pnpm-workspace.yaml 配置子项目路径，自动处理包之间的软链接，安装依赖时复用缓存，效率极高
• Yarn Workspaces ：与 pnpm 功能类似，支持 workspace:* 语法声明内部依赖
• Lerna：早期流行的 Monorepo 工具，可搭配 npm/yarn 使用，擅长版本管理和发布，但依赖安装效率不如 pnpm

---

任务调度工具

需支持「多包构建」「增量构建」「依赖顺序构建」，避免每次全量构建：

工具	增量构建	并行任务	缓存机制	配置复杂度	适用场景
Turbo	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	中小型项目（推荐）
Nx	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐	大型企业级项目
Rush	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐	超大型项目

选型建议：

• 中小型项目：Turbo（推荐，配置简单，性能优秀）
• 大型企业级项目：Nx（功能强大，但配置复杂）
• 超大型项目：Rush（微软开源，适合超大型 monorepo）

核心特性：

• Turbo：高性能构建系统，可缓存构建结果，并行执行任务（构建、测试、lint），大幅提升大型 Monorepo 的构建速度
• tsup：支持多入口、增量构建，适配 TypeScript 项目，可快速构建多个子包
• Rollup/Vite：适合构建库或应用，支持 Tree-shaking，Vite 还能提供开发时热更新

---

版本管理工具

解决多包版本联动、CHANGELOG 自动生成、npm 发布等问题：

工具	monorepo 支持	多包版本同步	自动化程度	配置复杂度	适用场景
Changeset	⭐⭐⭐⭐⭐	✅ 自动同步	⭐⭐⭐	⭐⭐⭐	多包项目（推荐）
release-it	⭐⭐⭐	❌ 需手动	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	单包项目、简单场景
Lerna	⭐⭐⭐	✅ 支持	⭐⭐⭐	⭐⭐	传统方案

选型建议：

• 多包项目、需要版本同步：Changeset（推荐）
• 单包项目、追求自动化：release-it
• 简单场景、快速发布：release-it

核心特性：

• Changeset：轻量、易用，支持按子包提交变更记录，自动计算版本号（语义化版本），生成 CHANGELOG，批量发布子包
• release-it：可搭配 Changeset 使用，提供交互式发布流程，支持 GitHub 标签、发布说明等

---

代码质量工具

统一管理 lint、测试、格式化：

工具类型	推荐工具	核心功能
代码规范	ESLint + Prettier	根目录配置，所有子项目共享规则，可通过 eslint-config-xxx 抽离自定义规则
测试框架	Vitest / Jest	统一测试框架，支持跨包测试，可在根目录运行所有子项目的测试用例
Git Hooks	Husky + lint-staged	提交代码前自动执行 lint 和测试，保障代码质量

---

实战搭建

以下是最简搭建流程，基于 pnpm（生态最优）+ Turbo + tsup（核心包打包）+ VitePress（文档）+ Vitest（测试）。

1. 初始化基础环境

# 创建项目根目录
mkdir your-project && cd your-project

# 初始化根目录 package.json
pnpm init -y

# 安装 Turbo（任务调度）
pnpm add turbo -D -w  # -w 表示安装到根目录（workspace-root）

2. 配置 pnpm 工作区

创建 pnpm-workspace.yaml：

# pnpm-workspace.yaml
packages:
  - 'packages/*' # 核心包（可发布）
  - 'docs' # 文档站点（不发布）
  - 'examples/*' # 示例项目（不发布）

3. 配置 Turbo

创建 turbo.json：

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["package.json", "turbo.json"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**", "build/**", ".vitepress/dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    },
    "clean": {
      "cache": false
    }
  }
}

配置说明：

• dependsOn: ["^build"]：构建前先构建依赖的子包
• outputs：指定构建输出目录，用于缓存判断
• cache: false：开发模式不缓存，避免热更新问题
• persistent: true：开发模式持续运行（如 watch 模式）

4. 根目录 package.json 配置

{
  "name": "your-project-monorepo",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "clean": "turbo run clean && rm -rf node_modules",
    "format": "prettier --write \"**/*.{ts,tsx,md,json}\""
  },
  "devDependencies": {
    "turbo": "^2.0.0",
    "prettier": "^3.0.0"
  },
  "packageManager": "pnpm@9.0.0",
  "engines": {
    "node": ">=18.0.0",
    "pnpm": ">=9.0.0"
  }
}

5. 搭建核心包

# 创建核心包目录并初始化
mkdir -p packages/core && cd packages/core
pnpm init -y

# 安装核心依赖（共享依赖安装到根目录）
pnpm add -D tsup typescript vitest @types/node -w

核心包 package.json：

{
  "name": "@your-org/core",
  "version": "1.0.0",
  "description": "核心功能包",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsup",
    "dev": "tsup --watch",
    "test": "vitest run",
    "test:watch": "vitest",
    "lint": "eslint src/**/*.ts",
    "clean": "rm -rf dist coverage"
  },
  "keywords": ["core", "utils"],
  "license": "MIT"
}

核心包 tsup.config.ts：

import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  clean: true,
  sourcemap: true,
  minify: true,
  splitting: false,
});

核心包 src/index.ts：

export const greet = (name: string) => {
  return `Hello, ${name}!`;
};

export const add = (a: number, b: number) => {
  return a + b;
};

6. 搭建文档站点

# 创建文档目录并初始化
mkdir docs && cd docs
pnpm init -y

# 安装文档依赖
pnpm add -D vitepress @vitepress/theme-default -w

# 初始化 VitePress 文档
npx vitepress init

文档 package.json：

{
  "name": "@your-org/docs",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "vitepress dev",
    "build": "vitepress build",
    "preview": "vitepress preview",
    "lint": "eslint . --ext .md,.ts",
    "clean": "rm -rf .vitepress/dist"
  },
  "dependencies": {
    "@your-org/core": "workspace:*"
  }
}

在 Markdown 中可直接导入核心包，用于示例演示：

# 快速使用

```ts
import { greet } from '@your-org/core';

console.log(greet('World')); // Hello, World!
```

7. 搭建示例项目

# 创建示例目录并初始化
mkdir -p examples/basic && cd examples/basic
pnpm init -y

# 安装依赖（使用工作区协议引用核心包）
pnpm add @your-org/core@workspace:* -w
pnpm add -D vite @vitejs/plugin-react -w

示例 package.json：

{
  "name": "@your-org/example-basic",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "clean": "rm -rf dist"
  },
  "dependencies": {
    "@your-org/core": "workspace:*"
  }
}

8. 核心命令使用

命令	作用
pnpm run dev	同时启动核心包监听、文档热更新、示例热更新
pnpm run build	一键构建核心包（ESM/CJS + 类型）、文档静态资源、示例
pnpm run test	运行所有子包的测试（核心包单元测试、示例冒烟测试）
pnpm run lint	统一校验所有子包的代码规范
pnpm run clean	清理所有子包的构建产物和缓存

增量构建效果示例：

• 首次执行 pnpm run build：构建所有子包（core + docs + examples）
• 修改核心包代码后再次执行 pnpm run build：仅重建 core 和依赖它的 examples，docs 未变更则直接复用缓存，构建速度提升 50%+

过滤特定子包执行任务：

# 只构建核心包
pnpm run build --filter=@your-org/core

# 只构建文档和示例
pnpm run build --filter=@your-org/docs --filter=@your-org/example-basic

# 构建核心包及其依赖者
pnpm run build --filter=@your-org/core...

9. 版本管理与发布

使用 Changeset（推荐，适合多包版本同步）

Changeset 完全支持 Turbo monorepo，可仅发布核心包（packages/core），文档和示例不发布，并支持多包版本同步：

优势：

• ✅ 专为 monorepo 设计，支持多包版本同步
• ✅ 自动更新依赖包的版本号
• ✅ 变更记录清晰，便于追溯

劣势：

• ❌ 需要手动记录变更（npx changeset）
• ❌ 流程相对复杂

安装与配置：

# 安装 Changeset 并初始化
pnpm add @changesets/cli -D -w
npx changeset init

修改 Changeset 配置（.changeset/config.json）：

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": ["@your-org/docs", "@your-org/example-basic"]
}

发布流程：

# 1. 记录核心包变更（仅选择 @your-org/core）
npx changeset

# 2. 升级版本 + 生成 CHANGELOG
npx changeset version

# 3. 构建核心包
pnpm run build --filter=@your-org/core

# 4. 发布核心包
pnpm publish --filter=@your-org/core --access public

---

使用 release-it（适合单包发布或简单场景）

release-it 也可以用于 monorepo，但主要用于单包发布场景。

优势：

• ✅ 自动化程度高，一条命令完成发布
• ✅ 配置灵活，支持自定义发布流程
• ✅ 支持 GitHub Release、npm 发布等

劣势：

• ❌ 不支持多包版本同步（需要手动处理）
• ❌ 需要为每个包单独配置或使用脚本

方式一：在子包中单独配置（推荐）

在需要发布的子包中配置 release-it：

# 在核心包目录下
cd packages/core
pnpm add release-it @release-it/conventional-changelog -D

核心包 release-it.config.js：

module.exports = {
  git: {
    commitMessage: 'chore: release @your-org/core@${version}',
    tagName: '@your-org/core@${version}',
    requireCleanWorkingDir: false,
    requireBranch: 'main',
    requireCommits: true,
  },
  github: {
    release: true,
    releaseName: '@your-org/core@${version}',
  },
  npm: {
    publish: true,
    publishPath: './',
  },
  hooks: {
    'before:init': ['pnpm run test'],
    'after:bump': ['pnpm run build'],
    'after:release': 'echo "Release @your-org/core@${version} completed!"',
  },
  plugins: {
    '@release-it/conventional-changelog': {
      preset: 'angular',
      infile: 'CHANGELOG.md',
    },
  },
};

核心包 package.json scripts：

{
  "scripts": {
    "release": "release-it",
    "release:patch": "release-it patch",
    "release:minor": "release-it minor",
    "release:major": "release-it major"
  }
}

发布流程：

# 在核心包目录下
cd packages/core
pnpm run release

方式二：在根目录统一配置（适合单包发布）

在根目录配置，配合 pnpm filter 使用：

# 在根目录安装
pnpm add release-it @release-it/conventional-changelog -D -w

根目录 release-it.config.js：

module.exports = {
  git: {
    commitMessage: 'chore: release v${version}',
    tagName: 'v${version}',
    requireCleanWorkingDir: false,
    requireBranch: 'main',
  },
  hooks: {
    'before:init': ['pnpm run test --filter=@your-org/core'],
    'after:bump': ['pnpm run build --filter=@your-org/core'],
  },
  plugins: {
    '@release-it/conventional-changelog': {
      preset: 'angular',
      infile: 'CHANGELOG.md',
    },
  },
};

根目录 package.json scripts：

{
  "scripts": {
    "release": "release-it",
    "release:core": "cd packages/core && pnpm run release"
  }
}

---

Changeset vs release-it 对比

特性	Changeset	release-it
monorepo 支持	⭐⭐⭐⭐⭐（专为 monorepo 设计）	⭐⭐⭐（需手动配置）
多包版本同步	✅ 自动同步	❌ 需手动处理
自动化程度	⭐⭐⭐（需手动记录变更）	⭐⭐⭐⭐⭐（一条命令）
配置复杂度	⭐⭐⭐	⭐⭐⭐⭐
适用场景	多包项目、版本同步需求	单包项目、简单场景

选型建议：

• 多包项目、需要版本同步：Changeset（推荐）
• 单包项目、追求自动化：release-it
• 简单场景、快速发布：release-it

---

高级配置

Turbo 缓存优化

1. 配置远程缓存（可选）

Turbo 支持远程缓存，团队共享构建缓存：

# 安装 Turbo 远程缓存客户端
pnpm add turbo -D -w

# 登录 Vercel（免费提供远程缓存）
npx turbo login

# 链接项目
npx turbo link

2. 优化缓存配置

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"],
      "env": ["NODE_ENV"], // 环境变量变化时重新构建
      "inputs": ["src/**/*.ts", "tsup.config.ts"] // 指定输入文件
    }
  }
}

CI/CD 集成

GitHub Actions 示例

创建 .github/workflows/ci.yml：

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 9

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

      - name: Install dependencies
        run: pnpm install

      - name: Build
        run: pnpm run build

      - name: Test
        run: pnpm run test

      - name: Lint
        run: pnpm run lint

依赖管理策略

1. 公共依赖提升到根目录

# 安装公共依赖到根目录
pnpm add -D typescript eslint prettier -w

# 子包无需重复安装，直接使用

2. 子包间依赖使用工作区协议

{
  "dependencies": {
    "@your-org/core": "workspace:*" // ✅ 正确
    // "@your-org/core": "1.0.0"     // ❌ 错误，无法实时同步
  }
}

3. 版本统一管理

使用 .npmrc 统一配置：

# .npmrc
shamefully-hoist=true
strict-peer-dependencies=false

---

最佳实践

1. 子包命名规范 ：使用 scope（如 @your-org/core），避免命名冲突
2. 依赖管理 ：公共依赖提升到根目录，子包间使用 workspace:* 协议
3. 任务配置 ：在 turbo.json 中准确配置 outputs，确保缓存生效
4. 版本管理：使用 Changeset 管理版本，仅发布需要发布的包
5. 目录结构：按功能拆分（packages、docs、examples），保持清晰
6. 避免过度拆分：子包数量控制在 5 个以内，过多会增加配置复杂度
7. 开发体验 ：使用 pnpm run dev 同时启动所有子包的开发模式

---

常见问题

工作区相关问题

Q: 子包间依赖如何引用？

A: 使用工作区协议 workspace:*：

{
  "dependencies": {
    "@your-org/core": "workspace:*"
  }
}

Q: 如何安装依赖到特定子包？

A:

# 安装到根目录
pnpm add -D typescript -w

# 安装到特定子包
pnpm add -D vite --filter @your-org/example-basic

# 安装到所有子包
pnpm add -D eslint --filter "./packages/*"

Q: 如何查看所有子包？

A:

pnpm list -r --depth=0

Turbo 相关问题

Q: Turbo 缓存不生效怎么办？

A:

1. 检查 turbo.json 中的 outputs 配置是否正确
2. 检查构建输出目录是否在 outputs 中声明
3. 清理缓存：pnpm run clean && rm -rf .turbo

Q: 如何只构建变更的子包？

A: Turbo 默认就是增量构建，只需执行 pnpm run build，Turbo 会自动判断哪些子包需要重新构建。

Q: 如何跳过缓存强制构建？

A:

pnpm run build --force

Q: 如何查看构建依赖关系？

A:

# 查看任务依赖图
npx turbo run build --graph

版本管理相关问题

Q: Changeset 如何只发布特定包？

A: 在 .changeset/config.json 中配置 ignore 字段，或在执行 npx changeset 时只选择需要发布的包。

Q: 如何自动化发布流程？

A: 使用 GitHub Actions + Changeset，参考 Changeset 文档。

Q: release-it 能否用于 monorepo？

A: 可以，但主要用于单包发布场景。如果项目只有一个包需要发布，release-it 更简单；如果需要多包版本同步，建议使用 Changeset。

Q: release-it 如何发布 monorepo 中的特定包？

A:

# 方式一：在子包目录下执行
cd packages/core
pnpm run release

# 方式二：使用 pnpm filter
pnpm --filter @your-org/core run release

性能优化相关问题

Q: 如何提升构建速度？

A:

1. 配置 Turbo 远程缓存（团队共享）
2. 优化 turbo.json 的 outputs 配置
3. 使用 dependsOn 合理配置任务依赖
4. 避免不必要的任务依赖

Q: 如何减少 node_modules 体积？

A:

1. 使用 pnpm（默认使用符号链接，节省磁盘空间）
2. 公共依赖提升到根目录
3. 使用 .npmrc 配置 shamefully-hoist=false

---

参考资源

• Turbo 文档
• pnpm Workspace 文档
• Changeset 文档
• VitePress 文档

---

文档版本 ：v2.0
最后更新：2024 年