Composer 识别版本依赖 Git tag 而非 composer.json 的 version 字段，必须推送 tag 至远程、配置 Packagist Webhook 并确保 name 匹配，否则 composer require 无法拉取对应版本。
Composer 包打版本标签前，必须确保 Git 仓库干净且已推送到远程
Composer 识别版本靠的是 Git 的 tag，不是 composer.json 里的 version 字段——那个字段只在本地开发或非 Git 源时起作用。如果没打 tag 或 tag 没推上去，composer require会拉不到你期望的版本，甚至报 Could not find package 或no matching package found。
- 先检查当前分支是否已提交所有变更：
git status应该显示“nothing to commit” - 确认远程仓库地址正确：
git remote get-url origin，尤其注意是 SSH 还是 HTTPS，影响后续 packagist 同步 - 打 tag 前务必推送代码：
git push origin main（或你的默认分支），否则 tag 孤立在本地 - tag 命名要符合语义化版本规范，比如
v1.2.0、v2.0.0-beta.1；1.2.0（缺v前缀）可能被 Packagist 忽略
用 git tag 命令打标签并推送到 GitHub/GitLab
打 tag 本身很简单，但推不上去就等于没打。Packagist（或私有仓库如 Satis）只监听远程 tag 创建事件，不会轮询本地。
- 打轻量标签（推荐）：
git tag v1.3.0 - 打带注释的标签（更规范，便于追溯）：
git tag -a v1.3.0 -m "release: add cache invalidation hook" - 推送单个 tag：
git push origin v1.3.0 - 推送所有本地 tag（慎用）：
git push origin --tags——如果之前打过测试 tag（如v0.1.0-rc1）又没删，会一并暴露 - 删错的 tag（本地 + 远程）：
git tag -d v1.3.0 && git push origin :refs/tags/v1.3.0
Packagist 自动更新失败？检查 Webhook 和包名匹配
打完 tag 只是第一步，Packagist 需要收到通知才能抓取新版本。很多人卡在这步，以为“打了 tag 就完了”，结果 composer update 还是拉不到最新版。
- Packagist 页面上你的包必须开启“Automatically update this package”开关（在
Edit Package里） - GitHub/GitLab 仓库的 Webhook 要指向
https://packagist.org/api/github（或对应私有仓库的 API 端点），且事件类型包含create（不是push） - 确保
composer.json里的name字段（如"myvendor/my-package"）和 Packagist 注册时填的一致，大小写敏感 - 如果用私有仓库，确认其配置支持监听
tag事件，有些 Satis 部署默认只扫描master分支
验证版本是否生效：别只信composer show
composer show myvendor/my-package显示的版本列表，可能缓存了旧数据。真正可靠的方式是让另一个项目去拉一次。
- 新建测试目录：
mkdir test-pkg && cd test-pkg && composer init -n - 强制拉指定版本：
composer require myvendor/my-package:v1.3.0，观察是否成功安装 - 如果报
Could not find a version of package matching your minimum-stability，检查composer.json里minimum-stability是否为stable，而你打的是beta或dev标签 - 想看 Packagist 实际收录了哪些版本？直接访问
https://packagist.org/packages/myvendor/my-package，页面底部有“Versions”列表，实时性比本地命令高
打 tag 不是发布终点，而是触发下游同步的起点。最容易被忽略的是 Webhook 配置失效（比如 GitHub 迁移后旧 token 过期）和 minimum-stability 与 tag 命名风格不匹配——这两个问题占了 80% 以上的“明明打了 tag 却拉不到”的案例。
