本文目录导读：
在PHP项目中，语义化版本规范（Semantic Versioning，简称 SemVer）是目前最广泛采用的版本号管理标准，它通过 主版本号.次版本号.修订号 的三段式结构,清晰传达版本变更的兼容性和影响范围。
基本格式
主版本号.次版本号.修订号 [预发布标识符] [构建元数据]4.2，0.0-alpha.1，1.0+build.20250320
各段含义与迭代规则
| 段位 | 名称 | 何时递增 | 示例 |
|---|---|---|---|
| 主版本号 | Major | 做了不兼容的 API/功能修改，无法向下兼容 | 0.0 → 0.0 |
| 次版本号 | Minor | 新增向下兼容的功能或特性 | 0.0 → 1.0 |
| 修订号 | Patch | 做了向下兼容的 bug 修复或微小优化 | 0.0 → 0.1 |
迭代规则：
- 主版本递增时，次版本和修订号归零
- 次版本递增时，修订号归零
- 修订号递增时，前面不变
预发布版本与构建元数据
预发布标识符（可选）
使用连字符 附加，表示不稳定版本（开发、测试、Alpha、Beta、RC）：
0.0-alpha.1 # 内部测试
1.0.0-beta.2 # 功能完整性测试
1.0.0-rc.1 # 候选发布版排序规则：0.0-alpha < 1.0.0-beta < 1.0.0-rc < 1.0.0
构建元数据（可选）
使用加号 附加，仅用于元信息,不影响版本优先级：
0.0+build.20250320
1.0.0+sha.abc1234PHP 项目中的具体实践
1 在 composer.json 中定义版本
{
"name": "your-vendor/your-project",
"version": "1.4.2",
"require": {
"php": ">=8.0"
}
}
2 版本常量定义
在项目入口或配置文件中定义当前版本：
// src/Version.php
final class Version
{
public const VERSION = '1.4.2';
public const MAJOR = 1;
public const MINOR = 4;
public const PATCH = 2;
public const PRE_RELEASE = ''; // 'beta.1'
public const BUILD_META = ''; // 'build.20250320'
public static function getFullVersion(): string
{
$version = self::VERSION;
if (self::PRE_RELEASE) {
$version .= '-' . self::PRE_RELEASE;
}
if (self::BUILD_META) {
$version .= '+' . self::BUILD_META;
}
return $version;
}
}
3 使用 Git Tag 同步版本
每次发布正式版本时，在 Git 中打上对应标签：
git tag -a v1.4.2 -m "Release version 1.4.2" git push origin v1.4.2 # 预发布版本 git tag -a v2.0.0-beta.1 -m "Beta 1 for 2.0.0"
4 自动生成版本常量（推荐）
使用工具如 bamarni/semantic-versioning-automation 或自定义脚本，在 CI/CD 中根据 Git tag 自动注入版本。
// 在构建时自动生成的 Version.php
class Version
{
public const VERSION = '@git.tag@'; // 替换为实际 tag
public const BUILD_TIME = '@build.time@';
}
版本迭代决策流程图
flowchart TD
A[代码变更] --> B{是否破坏向下兼容?}
B -->|是| C[递增主版本号<br>次版本号/修订号归零]
B -->|否| D{是否新增功能?}
D -->|是| E[递增次版本号<br>修订号归零]
D -->|否| F{是否修复 Bug?}
F -->|是| G[递增修订号]
F -->|否| H[无需更新版本号]
常见场景示例
| 场景 | 当前版本 | 新版本 | 说明 |
|---|---|---|---|
| 修复一个 SQL 查询错误 | 2.3 |
2.4 |
兼容性修复 |
| 新增一个公开 API 方法 | 2.3 |
3.0 |
新增功能，兼容旧版本 |
| 删除或重命名一个方法 | 2.3 |
0.0 |
不兼容变更 |
| Alpha 测试阶段 | 0.0-alpha.1 |
0.0-alpha.2 |
预发布迭代 |
| 正式发布 | 0.0-rc.2 |
0.0 |
去掉预发布后缀 |
常见错误与注意事项
- 不要随意跳版本号：
0.0→0.0仅用于不兼容变更 - x.y 特殊处理：主版本 0 表示开发阶段，任何变更都可能不兼容，通常无需严格遵循 SemVer
- 版本号不要用于营销：不要为了体现“重大更新”而递增主版本号（如微信从 6.x → 7.0）
- 保持与 composer 一致：composer.json 中的 version 应与 Git tag 完全一致
- 版本号不宜过长：避免无意义的零，如
0.0.0.1不合法
工具推荐
- semver：PHP 语义化版本解析与比较库
composer require composer/semver
- auto-changelog：根据 Git 提交自动生成 CHANGELOG.md
- GitHub / GitLab Releases：结合 Git tag 管理版本发布
采用严格的语义化版本规范，能让你的 PHP 项目的依赖管理、CI/CD 自动化和用户升级体验都更加清晰和可控。
