PHP项目标签管理如何规范版本发布标签规则

本文目录导读：

1. 核心推荐：语义化版本控制（SemVer）
2. 完整标签命名规则（最佳实践）
3. 标签规范的“潜规则”与注意事项
4. 自动化与工具链建议
5. 针对不同规模PHP项目的建议
6. PHP项目标签管理的黄金法则
7. 一个标准的完整发布流程示例：

在PHP项目中，规范版本发布标签（Git Tag）规则的核心目标是可追溯、语义清晰、自动化友好,以下是目前业界最通用的规范及推荐实践。

核心推荐：语义化版本控制（SemVer）

v主版本.次版本.修订号 （v1.2.3）

这是最广泛的共识，适用于PHP框架、库、Composer包以及大多数业务系统。

格式详解（严格遵循 SemVer 2.0.0）：

• 主版本（MAJOR）： 当做了不兼容的 API 修改（即破坏性变更，Breaking Changes）。
• 次版本（MINOR）： 向下兼容的功能性新增。
• 修订号（PATCH）： 向下兼容的问题修正（Bug Fix）。

例子：

• v1.0.0：第一个稳定版。
• v1.0.1：修复了一个Bug。
• v1.1.0：添加了新功能，且不破坏已有的v1.0.x代码。
• v2.0.0：重构了核心逻辑,调用方式变了。

完整标签命名规则（最佳实践）

除了核心版本号,通常还需要前缀和附加信息：

稳定版标签

v<主版本>.<次版本>.<修订号>

• 推荐： v2.5.1 （不含v前缀也是常见，但加v更易识别）

预发布版标签

用于正式发布前的测试阶段（Beta、RC等）。 v<主版本>.<次版本>.<修订号>-<预发布标识>.<编号>

• Alpha（内部测试）： v1.0.0-alpha.1
• Beta（公开测试）： v1.0.0-beta.2
• RC（发布候选）： v1.0.0-rc.1

构建元数据（可选，不常用但在某些场景有用）

v<版本号>+<构建信息>

• 例子： v1.0.0+build.20250401

标签规范的“潜规则”与注意事项

1. 前缀v vs 无v：

   • 推荐使用v前缀（如v1.0.0），Composer和Packagist标准做法是加v，GitHub Release界面的版本排序也依赖v前缀进行正确语义排序。
   • 如果你的团队习惯无v（如0.0），务必统一,不可混用。

2. 标签必须对应Commit，而不是Branch：

   • 永远不要在一个“分支”上直接打标签，正确的流程：在main或release分支上，通过合并PR或特定commit后,基于那个commit打标签。
   • 操作命令：git tag -a v1.0.0 -m "Release version 1.0.0" （添加注解,而非轻量标签）

3. 标签必须与Composer.json的版本约束匹配：

   • 关键约束： 如果项目是一个Composer包（composer.json中的name为your-vendor/your-package），Composer会根据Git标签自动解析版本号。
   • 规则： Git标签名必须符合 vX.Y.Z 格式，否则Composer无法识别（除非在composer.json中显式声明version字段，但不推荐）。
   • 分支命名影响： 如果你的分支命名如5.x，Composer会认为该分支上的代码属于5.*系列，标签v2.5.0会覆盖掉该分支上的dev-2.5.x。

4. 避免删除或修改已发布的标签：

   • 标签是契约，一旦推送（git push --tags），其它开发者的composer.lock或CI/CD系统可能已经依赖了它。
   • 补救： 如果真的发布错了，使用 v1.0.1 而不是覆盖 v1.0.0，如果必须删除，立即通知所有团队成员,并更新CHANGELOG。

自动化与工具链建议

自动生成CHANGELOG

• 结合Conventional Commits（约定式提交） 规范（如feat:、fix:、BREAKING CHANGE:）。
• 工具：git-cliff / standard-version / semantic-release。
• 流程： 提交信息格式规范 → 自动解析commit类型 → 自动生成CHANGELOG → 自动打标签。

环境与部署标识

• 开发环境： 推荐使用 dev-<分支名> 格式（dev-main），Composer中这叫“开发版本”,不会污染正式版本号。
• CI/CD： 在GitHub Actions或GitLab CI中，可以通过 git describe --tags --abbrev=0 获取最近的标签,用于生成Docker镜像标签或部署版本。

针对不同规模PHP项目的建议

项目类型	推荐标签规范	核心要求
个人/小型库	v1.0.0, v1.1.0	严格SemVer，加v前缀，写CHANGELOG
中型SaaS/API系统	v2025.04.01-release (基于日期)	适合频繁发布（每日/每周），易理解，但注意SemVer版本号需要额外内部管理
大型企业级框架/平台	v1.0.0, v1.1.0, v2.0.0-rc.1	必须严格SemVer，版本号代表API兼容性，需要预发布标签（rc, beta）
Microservice 单体仓库	service-a/v1.0.0, service-b/v2.0.0	允许不同服务独立版本，避免标签冲突。

PHP项目标签管理的黄金法则

1. 坚持 SemVer 命名规则（vX.Y.Z）。
2. 只基于 Commit 打标签，且使用带注解的标签（git tag -a）。
3. 标签与 Composer.json 的版本约束保持一致。
4. 发布后永不移除或修改标签。
5. 配合 Conventional Commits 和自动化 Changelog 工具。

一个标准的完整发布流程示例：

开发人员提交代码：`git commit -m "feat: add new login method"`
2. 合并到 main 分支：`git merge feature/new-login --no-ff`
3. 创建标签：`git tag -a v1.2.0 -m "Release 1.2.0: added new login method"`
4. 推送标签：`git push origin v1.2.0`
5. CI/CD 检测到新标签 v1.2.0，自动构建并部署
6. 同时更新 Packagist / GitLab Releases / GitHub Releases

遵循这套规则，你的PHP项目版本管理将会非常清晰,团队协作效率也会大幅提升。