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 版本。
