返回 ELI5 知识库首页 🚦 SEMANTIC VERSIONING (SEMVER 2.0.0)
🚦 SemVer · Semantic Versioning · The Traffic Light of Software APIs

什么是 SemVer(语义化版本 · 软件升级红绿灯契约)?

在开源世界里,升级第三方依赖库就像在公路上开车 —— 如果作者随便改版本号,你的项目可能在一声 npm install 之后直接白屏崩溃!而 SemVer(语义化版本,标准格式 MAJOR.MINOR.PATCH,如 2.4.1 就是“软件依赖世界的交通红绿灯与安全契约”🔴 主版本号(红灯停,有破坏性 API 改动);🟡 次版本号(黄灯走,加了兼容新特性);🟢 修订号(绿灯行,修 Bug 安全闭眼升)

💣 无规则随意发布:依赖地狱与连环雪崩

版本号纯靠心情,一次升级全家暴毙

在没有 SemVer 之前,开发者随便起名:v2.1 突然删掉了核心方法,v3.0 只是换了个图标。下游程序员升级依赖全靠祈祷,一不小心就在半夜把生产系统搞挂,陷入可怕的“依赖地狱(Dependency Hell)”!

my-lib v1.2 正常调用 getUser() 升到 v1.3 (破坏改动) 💥 TypeError: undefined ⚠️ 毫无契约精神 · 升级犹如盲盒排雷
  • API 随意破坏:小版本更新暗藏致命破坏性改动
  • 自动化受阻:CI/CD 无法安全自动拉取安全补丁
VS
🚦 SemVer 契约:MAJOR.MINOR.PATCH 严密法则

三大段位各司其职,自动化构建稳如泰山

严格遵循 X.Y.Z 契约。包管理器(npm / Cargo / pip)只需看版本号,就能在锁定 ^1.2.0 时自动享受 1.2.1 的安全补丁与 1.3.0 的新特性,而绝不会自动拉取会搞崩项目的 2.0.0

🔴 MAJOR (2) 破坏性改动 需重构迁移 . 🟡 MINOR (4) 向下兼容新特性 放宽心使用 . 🟢 PATCH (1) 修Bug与漏洞 闭眼无缝升级 ✨ 全球开发者的通用契约 · 杜绝构建雪崩!
  • 清晰风险预期:看到主版本号变化就知道必须看迁移文档
  • 全自动依赖演进:安全补丁与新功能自动平滑接入
💡

一句话顿悟:SemVer 的三大铁律(MAJOR.MINOR.PATCH)

- MAJOR(主版本号): 当你做了不向下兼容的 API 修改时必须递增(如删除函数、改变参数类型);
- MINOR(次版本号): 当你增加了向下兼容的新功能时递增(同时 PATCH 归零);
- PATCH(修订号): 当你做了向下兼容的缺陷修复(Bug Fixes)时递增!

拆解 SemVer 的 4 大核心语法与包管理规则

从 npm 匹配符号到预发布标签,彻底攻克版本依赖难题

^

1. 插入符号 (Caret ^1.2.3)

锁定主版本: 允许安装 >=1.2.3 <2.0.0 之间的任何 MINOR 和 PATCH 升级,npm 默认安装模式。

~

2. 波浪号 (Tilde ~1.2.3)

锁定主+次版本: 仅允许安装 >=1.2.3 <1.3.0 之间的 PATCH 修订补丁,更加保守稳健。

0.x

3. 初始开发阶段 (0.y.z 潜规则)

在发布 1.0.0 正式版之前,任何小版本都可能破坏兼容性0.1.00.2.0 等同于大重构。

🏷️

4. 预发布与构建元数据

格式如 1.0.0-alpha.12.0.0-beta.23.0.0-rc.1+build.2024,按字典序标定测试进度。

🕹️ SemVer 依赖升级与破坏性改动演练台

观察不同版本升级场景下,下游项目能否安全构建:

当前依赖声明 "lodash": "^1.2.0"
上游升级版本 v1.2.1 (PATCH 修复补丁)
下游项目构建状态 ✔ 自动拉取 · 100% 兼容 · 构建通过
🟢 场景 1:PATCH 补丁升级
作者修复了内部的边界 Bug,未增加任何新函数,未改变现有 API 参数。
^1.2.0 规则会自动匹配并下载 1.2.1
下游项目获得安全加固,零构建风险!
✔ 绿灯通行 · 纯 Bug 修复
🔒 package-lock.json 的守护

为什么有了 SemVer 还要 Lock 文件?

即使 SemVer 承诺兼容,上游开发者也可能误将破坏性代码作为 PATCH 发布(人非圣贤)。

Lock 文件精确锁死每一次安装的绝对哈希值,确保团队每个成员与 CI/CD 生产构建 100% 像素级一致!

⚠️ 0.x.x 版本的特殊陷阱

0.1.0 遇到 ^ 符号为什么不升 0.2.0?

在 SemVer 规范中,0 开头的版本被视为不稳定初始阶段

因此,npm 会把 ^0.1.2 自动视为等同于 ~0.1.2(即只升补丁,绝不跨越到 0.2.0),防止初期剧烈重构搞崩项目!

🤝 现代自动化:Semantic Release

结合 Conventional Commits 自动发版

- 提交包含 fix: xxx ➔ 自动发 PATCH
- 提交包含 feat: xxx ➔ 自动发 MINOR
- 提交包含 BREAKING CHANGE: xxx ➔ 自动发 MAJOR