答案是先验证包是否真实存在：访问https://packagist.org/packages/vendor/name确认页面可打开，再用composer search vendor/name和检查包名大小写、不可见字符；若存在则排查镜像失效、同步延迟、缓存残留或repositories配置错误。
包名拼错或根本不存在，先去 Packagist 确认
报 Could not find package 或 Package not found，第一反应不该是换镜像或清缓存，而是验证这个包是否真实存在。打开 https://packagist.org/packages/vendor/name（把 vendor/name 换成你实际要装的），看是否返回 404 页面。再运行 composer search vendor/name，如果没结果，说明 Packagist 根本没收录它。
常见低级错误包括：
- 大小写错误：
monolog/monolog对，Monolog/monolog错 - vendor 名写漏或写错：
spatie/laravel-backup对，spatie/backup错 - 粘贴时带入不可见字符（比如全角空格、零宽字符），建议手动重打一遍包名
镜像源没生效，或者用了已停用的旧地址
很多人改完镜像配置就跑命令，但日志里还是出现 Downloading https://packagist.org/ —— 这不是网络问题，是配置压根没生效。
检查方式很直接：
- 运行
composer config -g repos.packagist（注意是repos.packagist，复数形式），输出必须是完整 JSON，例如{"type":"composer","url":"https://mirrors.aliyun.com/composer/"}；输出为空或报错，说明全局没配成功 - 项目根目录若有
composer.json且含"repositories"字段（哪怕只是[]），就会**完全屏蔽**全局镜像；此时要查composer config repo.packagist（不加-g） - 旧模板里残留的
"url": "https://packagist.phpcomposer.com"已停用，会导致请求卡死在 404，必须手动删掉
私有包或新发布包找不到，repositories 配置漏字段或顺序错
私有包不会出现在 Packagist，Composer 默认根本不往你公司 GitLab 或本地路径里找。配置错一个字段，它就静默忽略整个 repositories 区块，继续查默认源，结果当然还是 404。
关键点：
-
{"packagist.org": false}必须是repositories数组里的一个**独立对象**，且放在私有源之后、数组末尾 - 不能写成
"packagist": false或嵌套在其他仓库对象里，否则会被静默忽略 - VCS 类型必须写对：
"type": "vcs"对应 Git/SVN 地址，"type": "composer"对应私有 Packagist 服务 - URL 必须可访问：用
curl -I或浏览器测试该 URL 是否返回 200，尤其注意认证头或 GitHub Token 是否已配
元数据缓存过期，镜像已同步但 Composer 还在读旧数据
镜像站可能已同步新版本，但 Composer 仍按本地缓存的 packages.json 元数据计算——这缓存可能 15 分钟前就失效了。
强制刷新元数据的正确姿势：
- 先执行
composer update --refresh，它会重新下载并解析所有源的元数据 - 再运行
composer require vendor/name或composer update vendor/name - 别只信镜像网页显示的版本号；最准的方式是直接请求镜像的 p2 接口，比如
https://mirrors.aliyun.com/composer/p2/monolog/monolog.json，看返回的版本列表是否含你要的
真正容易被忽略的是：即使你确认镜像 URL 正确、repositories 配置无误、包也确实存在，只要 composer update --refresh 没跑，Composer 就可能还在拿过期元数据做决策。
