Monorepo 各包的版本管理

在 Monorepo 项目中，如何管理各包的版本一直是核心问题之一。常见做法其实就三大类，每一类适合的团队和场景都不一样，我们一起来看下。

---

一、三种主流版本管理模式

1.统一版本（Single Version / Fixed）

特点

• 整个 Monorepo 只有一个版本号，即所有包共用一个版本号
• 每次发版都一起升版本号

// 根目录 package.json
{
  "name": "repo",
  "version": "1.8.0"
}

适合场景

• 强耦合系统
• 内部项目（不对外发包）
• 公司内部平台

优点

✅ 简单

✅ 没有版本依赖地狱

✅ 原子发布

缺点

❌ 一个包改了，所有包都要升版本

❌ 对外发布体验差

---

2.独立版本（Independent） ⭐（最常见）

特点

• 每个包都有自己的版本号

// packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "2.3.1"
}

// packages/utils/package.json
{
  "name": "@repo/utils",
  "version": "1.1.0"
}

• 只有改动的包才需要发版

{
  "dependencies": {
    "@repo/utils": "^1.1.0"
  }
}

• 依赖用 semver 约束

SemVer 是 Semantic Versioning（语义化版本） 的简称，是目前最常见的软件版本号规范。

基本格式：MAJOR.MINOR.PATCH

• MAJOR（主版本） 有不兼容的破坏性变更（Breaking Change）
• MINOR（次版本） 向后兼容地新增功能
• PATCH（修订号） 向后兼容的问题修复（bug fix）

在依赖管理中的常见写法：

^18.2.0 → 允许 18.x.x（不升级 MAJOR）

~1.4.2 → 允许 1.4.x

1.4.2 → 锁死版本

适合场景

• 组件库 / 工具库
• 对外发布 npm
• 中大型团队

优点

✅ 精细化控制

✅ 符合 npm 生态

✅ 不强迫无关包升级

缺点

❌ 管理复杂

❌ 需要工具辅助

---

3.无版本（仅 workspace）

特点

• 完全不发包，只在 Monorepo 内使用

{
  "dependencies": {
    "@repo/utils": "workspace:*"
  }
}

• 不关心版本号
• 永远链接本地

适合场景

• 应用型 Monorepo
• 不对外发布
• 微前端 / 多 app

优点

✅ 最简单

✅ 无版本成本

缺点

❌ 不能单独发包

❌ 强绑定仓库

---

二、推荐的 现代组合方案（实战）

✅ 独立版本 + workspace 协议（最流行）

{
  "dependencies": {
    "@repo/ui": "workspace:^"
  }
}

workspace:^ 含义：

• 本地开发：直接用源码
• 发包后：自动对齐 semver

---

三、版本提升（version bump）怎么做？

1️⃣ 手动（❌ 不推荐）

pnpm version patch

容易错、容易忘

---

2️⃣ Changesets（强烈推荐） ⭐⭐⭐

Changesets 做什么？

• 自动管理：

  • 哪些包需要升级
  • 升 major / minor / patch

• 自动生成 changelog

• CI 自动发包

使用流程

pnpm add -D @changesets/cli
pnpm changeset

生成：
"@repo/ui": minor
"@repo/utils": patch

feat(ui): 新增 Button 主题
fix(utils): 修复 debounce bug

发布

pnpm changeset version
pnpm changeset publish

---

四、Monorepo 内部依赖版本怎么写？

推荐写法（pnpm）

{
  "dependencies": {
    "@repo/utils": "workspace:^"
  }
}

❌不推荐

"@repo/utils": "*"
"@repo/utils": "latest"

---

五、不同团队的推荐策略

团队情况	推荐方案
公司内部系统	统一版本 / 无版本
组件库	独立版本 + Changesets
多应用	workspace:*
开源项目	独立版本 + Changesets

---

六、一个标准模板（示意）

repo/
├─ apps/
│  └─ web/
├─ packages/
│  ├─ ui/
│  │  ├─ package.json (version: 2.3.1)
│  └─ utils/
│     ├─ package.json (version: 1.1.0)
├─ .changeset/
├─ pnpm-workspace.yaml
└─ package.json

---

七、总结

Monorepo 的版本管理本质上是在“协作成本”和“发布灵活性”之间取平衡。根据团队和项目使用场景选择合适的版本管理机制，因地制宜。