软件开发版本库命名规范说明

背景：近期一直再更新自己所开发的一个前端大文件上传npm库(enlarge-file-upload)，为了让库的发版更加规范，于是参考了各种文档写下了这篇关于软件开发库的版本命名规范，且不仅局限于前端的版本命名规范，适用于整个软件开发行业，希望对您有帮助。

Semantic Versioning (SemVer) 规范指南

适用于所有软件开发库、框架和工具包的版本命名与管理。

---

1. 版本号基本格式

遵循 主版本号.次版本号.修订号[-预发布标签] 结构：

v2.10.16            ← 正式版  v3.0.0-alpha.0      ← 预发布版

• 主版本号 (Major) ：不兼容的 API 变更时递增（如 v2 → v3）。
• 次版本号 (Minor) ：新增向后兼容的功能时递增（如 v2.9 → v2.10）。
• 修订号 (Patch) ：修复向后兼容的 bug 时递增（如 v2.10.15 → v2.10.16）。
• 预发布标签 (Pre-release Tag) （可选）：标识不稳定版本（如 alpha、beta、rc）。

---

2. 预发布版本标识（Pre-release Tags）

预发布版本表示该版本尚未稳定，适用于测试和早期试用：

标签	含义	示例	适用场景
alpha	早期内部测试版，功能可能不全	v3.0.0-alpha.1	开发团队内部验证核心功能
beta	公测版，功能基本稳定但可能有 bug	v3.0.0-beta.2	邀请社区用户参与测试
rc	候选发布版（Release Candidate）	v3.0.0-rc.3	功能冻结，仅修复关键问题

规则：

• 预发布版本号按 .0、.1、.2 顺序递增。
• 正式版发布后，预发布标签移除（如 v3.0.0-rc.3 → v3.0.0）。

---

3. 版本升级规则

(1) 生产环境选择建议

版本类型	推荐程度	说明
最新稳定版（无标签）	✅ 强烈推荐	如 v2.10.16，已通过全面测试
最新 rc 版	⚠️ 谨慎使用	接近正式版，但可能残留小问题
alpha/beta版	❌ 避免使用	仅用于开发测试，不稳定

(2) 版本锁定建议

在 package.json 中指定版本范围：

{
  "dependencies": {
    "library": "~2.10.0",   // 允许修订号更新（如 2.10.15 → 2.10.16）
    "library": "^3.0.0",    // 允许次版本号更新（如 3.0.0 → 3.1.0）
    "library": "2.10.16"    // 锁定精确版本（不推荐长期使用）
  }
}

注意：大版本升级（如 v2 → v3）需检查 升级迁移指南。

---

4. 特殊版本标识

• latest：默认安装的最新稳定版（npm install library）。
• next：预发布版的别名（如 npm install library@next）。
• 版本弃用：在 npm 中标记为 deprecated，并提示替代方案。

---

5. 版本发布流程示例

1. 开发阶段：发布 alpha 版本（v3.0.0-alpha.0）。
2. 功能测试：迭代至 beta 版本（v3.0.0-beta.1）。
3. 发布候选：推出 rc 版本（v3.0.0-rc.2）。
4. 正式发布：移除标签，发布稳定版（v3.0.0）。
5. 维护阶段：推送补丁更新（v3.0.1）。

---

6. 违反规范的常见问题

❌ 错误示例：随意跳版本号（如 v1.0.0 → v5.0.0）。
❌ 错误示例：预发布版本用于生产（如使用 beta 版上线）。
✅ 正确做法：遵循 SemVer 规范，通过 semver.org 校验版本号。

---

附：版本号对比工具

• 使用 npm semver 比较版本：

npx semver "v2.10.16" "v3.0.0-rc.3"

• 在线校验工具：SemVer Checker

---

修订记录

• v1.0.0: 2023-10-01 初版发布
• v1.1.0: 2023-11-15 增加预发布版本说明

---

本手册适用于软件开发行业维护者和使用者。建议搭配 CHANGELOG.md 记录版本变更。