“Package not found”本质是Composer未在配置源中检索到包，主因是包名拼写/大小写错误、私有包未配repositories、minimum-stability或PHP版本约束导致包被过滤，而非网络问题。
“Package not found”不是网络卡了，而是 Composer 根本没在你配置的源里查到这个包名——90% 是拼写、源配置或稳定性设置的问题，和镜像速度无关。
包名拼错或大小写不对是最常见原因
Composer 不做模糊匹配，也不自动纠正大小写。输错一个字符、斜杠方向反了、漏 vendor 名，都会直接报 “Could not find package”。
- 去 https://www.php.cn/link/5d2e892c81e5fafc51ab0973879563a0 搜你输的完整
vendor/package，确认存在且格式完全一致（比如laravel/sanctum不是laravel-sanctum或sanctum/laravel） -
vendor名必须全小写，package名按 Packagist 上注册的来（spatie/laravel-backup不能简写成spatie/backup） - 别用中文输入法——全角
/、空格混入命令行会导致解析失败，错误可能不提示“拼写”，而是Invalid argument
私有包或 GitHub 仓库没配 repositories 就等于不存在
Composer 默认只查 Packagist，你写了 myorg/my-private-package，但它既没上 Packagist，又没告诉 Composer “去哪找”，那它就真找不到。
- 检查
composer.json里有没有repositories段，且类型明确为"type": "vcs"，不能只写 URL - 正确写法示例：
"repositories": [ { "type": "vcs", "url": "https://github.com/myorg/my-private-package" } ] - 配完必须运行
composer clear-cache，否则旧缓存会继续忽略新源 - 用
git ls-remote --heads https://github.com/myorg/my-private-package main手动验证 Git 地址是否可访问、凭据是否有效
源地址没生效或镜像已失效
很多人改了镜像但没加 -g，或者以为装了插件就自动启用，结果实际还在直连 packagist.org。
- 运行
composer config -g repo.packagist查全局源；composer config repo.packagist查项目级源——两者都得看 - 如果输出是
{"type": "composer", "url": "https://packagist.org"}，说明根本没切成功 - 阿里云镜像同步有最多 30 分钟延迟，新发布的包可能还没同步；腾讯云镜像不支持自动 fallback，挂了就是 404
- 临时切回官方源验证：
composer config -g repo.packagist composer https://packagist.org，再clear-cache重试
minimum-stability 和平台约束让包“隐形”
包明明存在，composer search 也能搜到，但 require 就报错——大概率是你项目的稳定性策略或 PHP 版本把它过滤掉了。
- 默认
"minimum-stability": "stable"，会跳过所有dev-、beta、rc版本；想装dev-main得加--stability=dev - 运行
composer show --platform看当前识别的 PHP 版本和扩展，和目标包的composer.json中"php"、"ext-xml"等约束对不上，就会静默跳过 -
composer require vendor/name --no-update先写进composer.json，再单独composer update vendor/name，能绕过 lock 文件固化的老路径
最麻烦的是多个包对同一依赖提出互斥要求，比如一个要 symfony/console:^5.4，另一个要 ^6.2——这时报错还是 “Package not found”，但真实拦路的是依赖图里的冲突，得用 composer prohibits 或 why-not 挖到底层。
