答案是镜像同步延迟导致“package not found”最常见，确认方法为查看镜像站底部「最后同步时间」、用curl验证p2接口、对比官方与镜像源版本列表，并排除配置失效、私有源顺序错误及插件干扰。
镜像源同步延迟是导致“Package not found”最常见却最容易被误判为配置错误的原因——你配对了、清了缓存、重装了 vendor，但新发布的包就是搜不到，问题不在你，而在镜像站本身。
怎么确认是镜像同步延迟，不是配置失效
别急着改命令或删 config.json，先看镜像站自己有没有同步成功：
- 打开
https://mirrors.aliyun.com/composer/，页面底部找「最后同步时间」——若超过 2 小时未更新，基本可判定滞后 - 用
composer show -p vendor/package-name查本地镜像是否收录；返回空但 Packagist 页面能打开，就是镜像没同步 - 执行
composer require vendor/package-name -vvv，日志里若出现Could not find package且请求域名确实是镜像地址（如mirrors.aliyun.com），说明镜像已生效，只是还没拉到新包
临时绕过镜像拉取最新包的实操方法
等同步太被动，开发中需要快速验证新功能时，可临时切回官方源，但必须精准控制范围，避免污染 lock 文件：
- 只对当前命令生效：
composer require vendor/package-name --repository=https://packagist.org - 不改全局、不改项目配置，也不影响后续 install —— 这种方式只覆盖本次请求的元数据源
- 如果连
--repository都报错，说明问题出在更底层（如 OpenSSL 未启用、allow_url_fopen关闭），先运行composer diagnose看红字提示
私有包和镜像共存时的 404 根本不是网络问题
镜像不代理私有仓库，但 Composer 默认按 repositories 数组顺序查找包。一旦把镜像写在私有源前面，它就会先去镜像查你的私有包，结果当然是 404：
- 必须把私有源放在
repositories数组首位：[{"type": "composer", "url": "https://your-private.com"}, {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}] -
repo.packagist字段对私有源完全无效，它只接管packagist.org流量 - 运行
composer show -p your-private/package -vvv，看日志里是否跳过了私有源（Skipping repository due to missing provider），这说明它的packages.json没正确返回或没声明该包
插件（如 prestissimo）会让镜像彻底失效
这类插件会绕过 Composer 原生 HTTP 客户端，直接调系统 curl 或 wget 请求 GitHub API，完全不读 repo.packagist 配置：
- 典型报错：
The "https://api.github.com/repos/hirak/prestissimo/zipball/" file could not be downloaded - 立即停用：
composer install --no-plugins，再试一次；如果成功，说明插件是罪魁祸首 - CI 或宝塔环境务必显式加
--no-plugins，因为旧版插件与 Composer 2.x 并发机制冲突，容易引发静默失败
同步延迟、私有源顺序、插件接管——这三个点不排查清楚，换十次镜像都没用。尤其注意：镜像站页面显示“同步完成”，不代表所有子包都已入库，packages.json 的增量更新可能滞后数分钟，这是正常行为，不是故障。
