语义化版本规范（SemVer）
1、SemVer 定义与格式规范
- 版本格式：
主版本号.次版本号.修订号（X.Y.Z）
（1）主版本号（Major）：
- 递增条件：进行不兼容的 API 修改或重大变更（如删除功能、架构重构）。
- 影响：用户需主动检查兼容性（例如
2.0.0 → 3.0.0）。
（2）次版本号（Minor）：
- 递增条件：新增向下兼容的功能或优化（如新 API 接口）。
- 关键原则：旧版本代码无需修改即可适配新版本（例如
1.2.0 → 1.3.0）。
（3）修订号（Patch）：
- 递增条件：修复向下兼容的缺陷或安全问题（如 Bug 修复）。
- 示例：
1.0.1 → 1.0.2 仅修正内部逻辑错误。
（4）特殊规则
- 版本 0.Y.Z（初始开发阶段）：API 不稳定，任何变更均可能发生，不建议生产环境使用。
- 版本号归零：主版本升级后，次版本和修订号重置为
0（如 1.9.0 → 2.0.0）。
2、预发布与元数据标签（扩展标识）
（1）预发布标签（Pre-release Tags）：
- 格式：`X.Y.Z-标签`（例如 `1.0.0-alpha`、`2.1.0-rc.1`）。
- 优先级规则： * 预发布版本优先级低于正式版（`1.0.0-alpha` < `1.0.0`）。 * 标签顺序：`alpha` → `beta` → `rc`（候选版本）。
- 用途：标识内测（Alpha）、公测（Beta）等非稳定版本。
（2）构建元数据（Build Metadata）：
- 格式：`X.Y.Z+元数据`（例如 `1.0.0+20240716`）。
- 特性：仅提供编译信息，不影响版本优先级。
（3）注意事项
- 禁止在数字前补零（如
1.07.0 无效）。 - 标签字符仅允许
[0-9A-Za-z-]（如 1.0.0-beta.1 合法）。
3、为何需要 SemVer？依赖管理实战
（1）解决 “依赖地狱”
# 示例：依赖声明
- 允许 `^3.1.0`（兼容 `3.1.0` 至 `4.0.0` 以下的所有版本）
- 禁止 `*`（全版本匹配，易引发兼容风险）
（2）自动化工具支持
- npm、Composer 等包管理器依赖 SemVer 解析版本。
- 如
webman-jwt 插件通过 SemVer Checker 验证兼容性。
4、最佳实践与常见陷阱
（1）版本发布流程
（2）避坑指南
- 避免非标准标签：如
next、canary 可能导致工具解析错误（参考 trpc 项目教训）。 - 禁用已发布版本的修改：错误修复需发布新版本。
- 预发布版本慎用：生产环境应依赖正式版（
X.Y.Z）。
