packagist 同步存在 5–30 分钟延迟，新 tag 暂不可搜、不可装；确认方式为访问 packagist.org/packages/vendor/name 看是否 404，或查 github 徽章及运行 composer show -p vendor/name。
不是你输错了，也不是网络挂了，大概率是 Packagist 还没索引到那个包——新 tag 提交后常有 5–30 分钟延迟，搜不到、装不上都正常。
怎么确认是不是 Packagist 同步延迟
别信 composer search 的空结果，它查的是本地缓存，且不支持模糊匹配。真正权威的判断方式只有两个：
- 直接打开
https://www.php.cn/link/ec811d0d775adc62776ba80fadd4ed19/packages/vendor/name（把vendor/name换成你实际的包名），看是否返回 404 页面 - 在 GitHub 仓库主页右上角找 Packagist 徽章 —— 没这个图标，基本等于没绑定
- 运行
composer show -p vendor/name，如果输出为空，说明 Packagist 根本没收录该包名
新发布的包怎么让它立刻被找到
Packagist 不监听 push，靠手动提交或 webhook 触发同步。临时救急和长期方案都要做：
- 登录 packagist.org → 右上角「Submit」→ 填入 GitHub/GitLab 仓库 URL 提交
- 提交成功后，进入该包页面 → 「Edit」→ 开启
Update on Push（即配置 webhook） - 如果已提交但版本没更新，点页面上的
Force update按钮（仅对已关联包可见） - 确保你的 Git tag 是标准格式：
v1.0.0或1.0.0，不能是release-1.0、v1.0或带空格/下划线
开发阶段不想等 Packagist 怎么办
绕过 Packagist 直接从 Git 安装，但必须满足三个硬条件，缺一不可：
- 在项目根目录
composer.json的repositories字段里声明源："repositories": [ { "type": "vcs", "url": "https://github.com/yourname/your-new-package" } ] - 该 Git 仓库根目录必须有
composer.json，且其中name字段值严格等于你require时写的yourname/your-new-package - 安装时指定分支或 tag：
composer require yourname/your-new-package:dev-main（注意：若默认分支是master，就得写dev-master）
为什么换镜像也搜不到新包
国内镜像（如阿里云、腾讯云）只同步 Packagist 已索引的公开包，不代理未收录的新包，也不加速 vcs 类型源。所以：
- 执行
composer config -g repo.packagist.url确认当前镜像地址是否生效 - 新包即使上了镜像，也要等它完成同步 —— 部分镜像同步延迟可达数小时
- 如果你
require的是私有 Git 地址（比如git@gitlab.example.com:org/pkg.git），镜像完全不参与，报错一定出在 SSH 权限、URL 可达性或composer.json的name字段匹配上
真正卡住的往往不是命令怎么敲，而是盯着终端反复重试，却没打开浏览器去 packagist.org/packages/... 看一眼——那一页 404，比所有错误信息都准。
