PHP项目版本号如何语义化规范迭代编号

本文目录导读：

1. 基本格式
2. 各段含义与迭代规则
3. 预发布版本与构建元数据
4. PHP 项目中的具体实践
5. 版本迭代决策流程图
6. 常见场景示例
7. 常见错误与注意事项
8. 工具推荐

在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.abc1234

PHP 项目中的具体实践

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	去掉预发布后缀

常见错误与注意事项

1. 不要随意跳版本号：0.0 → 0.0 仅用于不兼容变更
2. x.y 特殊处理：主版本 0 表示开发阶段，任何变更都可能不兼容，通常无需严格遵循 SemVer
3. 版本号不要用于营销：不要为了体现“重大更新”而递增主版本号（如微信从 6.x → 7.0）
4. 保持与 composer 一致：composer.json 中的 version 应与 Git tag 完全一致
5. 版本号不宜过长：避免无意义的零，如 0.0.0.1 不合法

工具推荐

• semver：PHP 语义化版本解析与比较库

  composer require composer/semver

• auto-changelog：根据 Git 提交自动生成 CHANGELOG.md
• GitHub / GitLab Releases：结合 Git tag 管理版本发布

采用严格的语义化版本规范，能让你的 PHP 项目的依赖管理、CI/CD 自动化和用户升级体验都更加清晰和可控。