git tag 必须严格使用 vx.y.z 格式（如v1.2.0），带v前缀、无空格/下划线/额外横线，且需推送至远程并清除composer缓存，私有包composer.json中不得声明version字段，repositories必须配置为vcs类型。
Git tag 必须用 vX.Y.Z 格式，否则 Composer 不识别
Composer 默认只认符合语义化版本（SemVer）的 tag，且必须带 v 前缀。比如 v1.2.0 可以，1.2.0、release-1.2.0、1.2 全部无效。
常见错误现象：composer require vendor/package 报错 Could not find a matching version of package vendor/package，但 git ls-remote --tags 明明能看到 tag。
- 必须用
git tag v1.2.0，不能漏掉v - tag 名里不能含空格、下划线、横线（除了
v后那个点分隔符），v1.2.0-beta也不行 —— Composer 会跳过它 - 打完 tag 一定要
git push origin v1.2.0，只本地打没用 - 如果已有不合规 tag（如
1.2.0），删掉重打：git tag -d 1.2.0 && git push origin :refs/tags/1.2.0
私有包的 composer.json 里 version 字段要删掉
如果你在私有包的根目录 composer.json 中手动写了 "version": "v1.2.0"，Composer 会优先读这个字段，而不是 Git tag —— 这会导致版本混乱，甚至安装失败。
使用场景：你维护一个内部工具包，用 Git 仓库托管，通过 repositories 配置引入。
- 私有包的
composer.json中不要出现version字段 - 确保
type字段存在（如"type": "library"），否则 Packagist 兼容逻辑可能异常 - 如果用了
composer install --no-dev，记得 tag 对应的代码状态不含 dev-only 依赖或配置
composer.json 的 repositories 配置必须设为 vcs 类型
很多私有包直接扔在 GitLab 或 GitHub 私有库，但 Composer 不会自动扫描这些地址 —— 必须显式声明为 VCS 源，它才会去解析 tag。
错误配置：{"type": "package", "url": "https://gitlab.example.com/group/pkg.git"} —— 这种写法把仓库当静态包处理，完全忽略 tag。
- 正确写法是：
{"type": "vcs", "url": "https://gitlab.example.com/group/pkg.git"} - URL 必须指向 Git 仓库地址（支持 HTTPS / SSH），不能是网页链接
- 如果用 SSH，确保运行
composer install的机器已配置对应密钥并能git clone成功 - 执行
composer clear-cache再composer update vendor/package，避免旧缓存干扰
验证 tag 是否生效：用 composer show 和 composer depends
别光看 git ls-remote 或 GitHub 页面 —— 那只是 Git 层面存在，不等于 Composer 能解析出可用版本。
性能影响：首次加载 VCS 包时 Composer 会 fetch 所有 tags，私有库 tag 太多（几百个）会明显变慢；建议定期清理无用 tag。
- 运行
composer show vendor/package --all，输出里应列出v1.2.0、v1.1.0等 tag 版本 - 如果只看到
dev-main或dev-master，说明 tag 没被识别，回头检查前三个环节 -
composer depends vendor/package能确认当前项目是否真在用该 tag 版本，而非 fallback 到 dev 分支
最容易被忽略的是：tag 推送后没清 Composer 缓存，或者 repositories 配置写在了子项目里却忘了同步到父项目 composer.json —— 这类路径和作用域问题，比语法错误更难排查。
