秒级装上新版本的前提是Packagist在5分钟内收到并解析成功，依赖git tag（带v前缀且推送到远程）、GitHub webhook（Payload URL为https://packagist.org/api/github、Content type为application/json、勾选Tag push events）和composer.json（name为小写vendor/package、psr-4 autoload末尾双反斜杠与斜杠齐全、无version字段）三者全部合规。
能秒级装上新版本的前提，是 Packagist 在 5 分钟内收到并解析成功——不是靠等缓存刷新，而是 tag、webhook、composer.json 三者全对。
git tag 必须推对，不是打对就行
Packagist 只看远程仓库里有没有那个 tag，完全不读本地。你 git tag v1.0.0 后没推，等于没发版。
- ✅ 正确命令：先提交代码 →
git tag v1.0.0（推荐轻量 tag；若用 annotated，必须带-m）→git push origin v1.0.0（注意不是--tags） - ❌ 常见错：用
1.0.0（缺v）、V1.0.0（大写 V）、v1.0.0-beta.1+build.2（含+符号） - 验证是否推成功：
git ls-remote --tags origin | grep v1.0.0，有输出才靠谱
GitHub Webhook 配错 = 白推
2023 年底起 Packagist 彻底关闭轮询，没 webhook 就不会触发更新。很多人卡在这一步，却以为是“延迟”。
- Payload URL 必须是
https://packagist.org/api/github（不是镜像站，也不是 php.cn 链接） - Content type 必须选
application/json（选错会静默失败） - Events 必须勾选
Tag push events（只勾Just the push event不管用） - 配完立刻去 GitHub Settings → Webhooks → Recent Deliveries 查状态码：200 才算通，404 或 400 表示 URL 或格式错误
composer.json 看似简单，但一个字符错就进不了 Packagist
Packagist 抓取 tag 对应 commit 的 composer.json 时，校验极严。它不报具体哪行错，只显示 “Invalid package information”。
-
name必须是小写vendor/package格式，且vendor要和你在 Packagist 注册的用户名一致（不是 GitHub 用户名） -
autoload至少配psr-4，命名空间末尾双反斜杠和路径末尾斜杠/都不能省，例如{"psr-4": {"MyOrg\Http\": "src/"}} - 删掉
version字段——Packagist 完全忽略它，留着反而可能干扰 CI 或导致校验警告 - 本地快速验证：
composer validate --strict，能提前发现 JSON 语法、缺失字段等问题
中文镜像不是“实时同步”，别指望 composer update 自动拉到
主流中文镜像（阿里云、腾讯云等）每 5–15 分钟轮询一次 Packagist，新 tag 推上去后，镜像通常要等下一周期才同步。更麻烦的是 Composer 本地还缓存 provider 数据。
- 想立刻试装：
composer clear-cache清下载包缓存 - 再手动删掉元数据缓存目录：
rm -rf ~/.composer/cache/repo/https---packagist.org（路径随当前镜像源变化） - 加
-vvv跑安装命令，观察日志里实际请求的是哪个 URL、返回是否 200 - 紧急时可临时切回官方源：
composer config -g repo.packagist composer https://packagist.org
最常被忽略的点：tag 推了、webhook 显示 200、composer.json 也过 validate，但 Packagist 页面 “Last updated” 时间没变——大概率是该 tag 对应的 commit 里，composer.json 文件压根没提交，或者被 .gitignore 忽略了。
