Composer 找不到包大概率是镜像源未同步最新元数据。因国内镜像每5–15分钟同步一次，不索引-dev分支或新发布包，可通过composer show -p --no-cache直连packagist.org验证，临时禁用镜像或配置fallback源解决。
Composer 报错 could not find package，大概率不是你写错了包名，而是镜像源没同步上最新包信息。
为什么 composer require 找不到包？
Composer 默认从 packagist.org 拉取元数据，但国内用户基本都配了镜像（如阿里云、腾讯云、华为云），而这些镜像不是实时同步的——它们通常每 5–15 分钟拉一次上游，且可能跳过某些临时 tag、私有分支或未通过验证的提交。
常见诱因包括：
- 刚发布的包（
vendor/name）在 packagist.org 上显示“last updated 2 minutes ago”，但镜像还没抓到 - 你用了带
-dev后缀的开发分支（如"dev-main"），部分镜像默认不索引非稳定分支 - 镜像配置写在
composer.json的repositories里，但被config.platform或全局auth.json干扰 - 执行了
composer clear-cache却没跑composer update --no-cache，本地仍读旧索引
怎么快速确认是镜像不同步？
绕过镜像直连 packagist.org 查一次：
composer show -p vendor/name --no-cache
如果这行命令能列出包，但平时 composer require 失败，基本锁定镜像延迟。再对比：
- 访问你的镜像主页（如
https://mirrors.aliyun.com/composer/p/vendor/name.json），看返回 404 还是空 JSON - 查 packagist.org 对应页面（
https://packagist.org/packages/vendor/name），确认状态为 “active” 且有 recent release - 运行
composer config repo.packagist.org，确认当前生效的是镜像 URL（如{"url":"https://mirrors.aliyun.com/composer/","type":"composer"}），不是https://packagist.org
临时解决：跳过镜像或切回官方源
不想等同步，有三个轻量级操作可选：
- 单次命令禁用镜像：
composer require vendor/name --repository=https://packagist.org - 临时切全局源：
composer config -g repo.packagist composer https://packagist.org（之后可composer config -g --unset repo.packagist恢复） - 只对当前项目临时改源：
composer config repo.packagist composer https://packagist.org（修改的是项目级composer.json的repositories）
注意：--repository 参数优先级高于配置，但不会持久化；而 config repo.xxx 会写入配置，需手动清理。
长期建议：别全依赖单一镜像
阿里云、腾讯云镜像虽快，但同步策略保守；华为云镜像更新勤，但偶尔抽风；packagist.org 官方源最全但慢。生产环境推荐组合策略：
- 日常开发用镜像（快），但 CI 流水线中加一步
composer update --no-cache --prefer-dist，强制穿透缓存 - 在
composer.json的repositories里把官方源设为 fallback："repositories": [ {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}, {"type": "composer", "url": "https://packagist.org", "canonical": false} ]（canonical: false表示不作为主源，仅当镜像 404 时才查） - 发布新包后，主动去镜像站提交同步请求（如阿里云镜像页有「手动刷新」按钮）
最常被忽略的一点：很多团队把镜像 URL 写死在 composer.json 里，却忘了它会覆盖全局配置——一旦镜像出问题，所有成员都卡住，连 composer self-update 都可能受影响。
