composer怎么使用Git标签发布稳定版本_composer版本管理与Tag钩子【详解】

composer 稳定版发布依赖 git 标签格式（如 v1.2.0）、Packagist Webhook 同步、自动更新启用及私有仓库权限配置，任一环节失败则标签不被识别为有效版本。

Composer 本身不“发布”版本，它只消费版本；真正发布稳定版靠的是 Git 标签（git tag）+ Packagist 同步机制。你 push 一个 v1.2.0 标签到 github/gitlab，Packagist（或私有仓库如 Satis/SatisPress）收到 webhook 后自动抓取并解析为 Composer 可安装的稳定版本。

Git 标签必须符合 Composer 版本约束规则

Composer 对标签名有硬性校验：只有匹配 ^v?d+.d+.d+(-[a-zA-Z][a-zA-Z0-9.]*)?$ 的标签才会被识别为语义化版本（SemVer）。常见失败场景：

• v1.2 ❌ 缺少补丁号（第三位），会被降级为 dev-main 或忽略
• 1.2.0-rc1 ✅ 允许预发布，但需加连字符，且字母开头（rc、beta、alpha）
• release/1.2.0 ❌ 不是纯版本标签，Packagist 直接跳过
• V1.2.0 ❌ 大写 V 不在正则范围内（注意是小写 v?）

正确做法：

git tag -a v1.2.0 -m "Release version 1.2.0" git push origin v1.2.0

packagist.org 的自动更新依赖 Webhook 配置

GitHub/GitLab 仓库必须在 Packagist 上启用自动更新（即勾选 “Automatically update this package”），否则即使打了 tag，Packagist 也不会拉取。常见疏漏点：

• 新仓库首次提交后，没去 packagist.org 手动 submit，导致 webhook 无法绑定
• Webhook URL 被防火墙拦截（私有 GitLab 环境尤其常见）
• 标签 push 后立即 composer require vendor/package 失败——因为 Packagist 抓取有延迟（通常 1–30 秒），不是实时

验证是否生效：打开 https://www.php.cn/link/ec811d0d775adc62776ba80fadd4ed19/packages/vendor/package，看 “Versions” 栏是否出现新 tag，且状态为 stable。

私有包如何复现 Tag 发布流程

若用私有仓库（如 Satis、private Packagist、Toran proxy），关键不是改 Composer 配置，而是确保其源码扫描器能识别并索引你的 Git 标签。例如 Satis 配置中：

{     "repositories": [         {             "type": "vcs",             "url": "https://git.example.com/my/package.git"         }     ],     "require-all": true }

它默认会 fetch 所有 tags —— 但前提是你的 Git 服务器允许匿名 clone 或已配置好认证凭据。容易卡住的地方：

• Satis 运行用户无权读取私有仓库（ssh key 权限不对 / HTTP Token 过期）
• Git 仓库启用了 uploadarchive 禁用，导致 git archive（Satis 用它打包）失败
• 标签指向的 commit 没有 composer.json，或该文件中 "version" 字段与 tag 名冲突（应留空或删掉，让 Composer 以 tag 为准）

本地开发时用 composer require 测试 tag 是否可用

别等 CI 或线上环境才发现问题。在项目根目录执行：

composer require vendor/package:v1.2.0

如果报错 Could not find package vendor/package in a version matching v1.2.0，优先检查：

• 该 tag 是否真的存在于远程仓库：git ls-remote --tags origin | grep v1.2.0
• Packagist 页面是否显示该版本，且不是灰色（grayed out）状态
• 本地 composer clear-cache，避免缓存了旧的 metadata
• 运行 composer show vendor/package，确认当前 registry 是否是你预期的那个（比如误用了 packagist.org 而非私有源）

稳定版本的“稳定”，不在代码多健壮，而在标签格式、推送动作、webhook 响应、缓存刷新这四步闭环是否全通——任一环节断开，v1.2.0 就只是个 Git 提交，不是 Composer 版本。