先确认包名拼写完全正确：手动逐字核对vendor/name、大小写、不可见字符；访问https://www.php.cn/link/94953b1a99c64501ceb078724697224f验证是否存在；私有包需确保repositories配置正确且packagist.org已显式禁用。
包不存在，90% 是名字打错了，不是网络或镜像问题。 Composer 不会凭空“找不到”一个真实存在的包——它只认你敲进去的每一个字符，包括大小写、斜杠、不可见空格。先校对名字，比换镜像、清缓存、升级 Composer 都快。
怎么确认包名拼写完全正确
别靠记忆或网页复制粘贴，手动逐字核对：
-
composer search只查 Packagist 全局索引，不校验 name 字段是否匹配；它搜到 ≠ 你能装。比如搜laravel-swoole成功，但你要装的是swooletw/laravel-swoole，漏 vendor 就 404 - 打开 https://packagist.org/packages/
vendor/name，把vendor/name替换成你实际写的包名，看是否返回 404 页面 - 检查大小写：PHP 包名区分大小写，
monolog/monolog对，Monolog/monolog错；spatie/laravel-backup对，spatie/backup错 - 复制时易带入零宽字符或全角空格，尤其从微信、Notion、PDF 粘贴。建议在终端里手动重打一遍
composer require vendor/name
私有包或 Git 仓库报 404 的真实原因
Composer 默认根本不查你公司 GitLab 或本地路径——除非你配对了 repositories，且它被真正启用。
-
repositories必须是项目根目录composer.json里的顶层字段，不能嵌套在其他配置下 - VCS 类型必须写
"type": "vcs"，写成"git"或漏掉，整条配置被静默忽略 - URL 必须是可
git clone的地址，且结尾只能是.git，不能带分支锚点（如https://gitlab.example.com/myorg/utils.git#main❌） - 目标仓库根目录的
composer.json中"name"字段，必须和composer require里写的vendor/name完全一致（包括大小写） - 如果同时用了私有源和 Packagist，必须显式关闭官方源：
{"packagist.org": false}要作为repositories数组里的**独立对象**，且放在末尾
为什么切回官方源还报 404
不是镜像问题，而是你根本没切成功，或者包真不在 Packagist 上。
- 运行
composer config -g repos.packagist（注意是复数repos），输出应为类似{"type":"composer","url":"https://packagist.org/"}；若为空或报错，说明全局配置未生效 - 项目级
composer.json若含"repositories"字段（哪怕值是[]），会**覆盖全局镜像**，此时要查composer config repo.packagist（无-g） - 新发布的包有同步延迟：GitHub push 后，作者需主动提交到 Packagist 或配好 webhook，否则
composer require永远 404 - 某些包已被标记为
abandoned，Packagist 页面会显示替代方案，但旧名仍可访问；而有些则被彻底下架，连页面都 404
最常被忽略的一点：Composer 查包时，会严格按 minimum-stability + require 版本约束 + repositories 顺序三者共同匹配。哪怕名字、源、网络全对，只要稳定性设置卡死了（比如设了 "stable" 却 require dev-main），它就直接跳过，报 “not found”，而不是 “no matching version”。
