“Package not found”错误主因是Composer未触发包搜索，常见于无composer.json、repositories为空数组、全局源被覆盖或私有源配置失效；需先验证项目上下文与源配置有效性。
“Package not found”不是包真没了，而是 Composer 在当前上下文里压根没去 Packagist 或你配的仓库里查——它可能被跳过、被锁死、或根本没触发搜索。
composer require 报错 “Could not find package”
这错误最常发生在你敲完 composer require vendor/name 后，终端直接返回找不到，连网络请求痕迹都没有。根本原因往往不是网络或仓库挂了，而是本地配置或命令上下文出了问题。
- 检查当前目录是否有
composer.json：没有就报这个错，composer require必须在有composer.json的项目根目录运行 - 确认
composer.json里没写死"repositories": []且为空数组——这会清空默认 Packagist 源，导致所有包“查无此库” - 运行
composer config --list | grep repositories，看是否全局配置了私有源但没配好 URL 或认证，把默认源覆盖掉了 - 临时绕过自定义源试一下：
composer require vendor/name --repository=https://packagist.org
composer install 卡在 “Loading composer repositories” 或超时
这不是包找不到，是 Composer 连不上仓库。Packagist 官方源（https://packagist.org）在国内访问不稳定，但很多人误以为是包本身不存在。
- 先验证网络通不通：
curl -I https://packagist.org/packages/list.json，如果超时或返回 403，就是源的问题 - 切国内镜像（推荐阿里云）：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - Windows 用户注意：如果用 WSL，别只在 Windows 里配了镜像，WSL 的
~/.composer/config.json也要单独配 - 不建议用
--prefer-dist强制走 zip 包下载来“绕过”，它解决不了源不可达的本质问题
包明明在 Packagist 上，却提示 “No version match”
这是版本约束和 PHP 环境不匹配导致的“逻辑性找不到”。Composer 找得到包，但筛不出可用版本。
- 运行
composer show vendor/name，如果返回空，说明该包在当前 PHP 版本 + 扩展组合下没有任何可安装版本 - 重点看
composer check-platform-reqs输出：比如包要求ext-gd，而你 CLI 的 PHP 没开，那它所有版本都会被过滤掉 - 检查
composer.json里的"php"和"ext-*"约束是否过严，例如写了"php": "^8.2"，但你本地是 8.1 —— Composer 不会降级适配，直接跳过整个包 - 想看包有哪些真实可用版本？用浏览器打开
https://packagist.org/packages/vendor/name，点开每个 release，看右下角 “Requires” 里写的 PHP 和扩展要求
私有包 404 或 “Package not found”
私有 Git 仓库、Satis 或 Private Packagist 配置出错时，错误表现和公共包一样，但排查路径完全不同。
- 确保
composer.json里"repositories"的url是完整可访问的 HTTPS 地址，末尾不要加/（很多 Satis 实例不认带斜杠的 URL） - Git 类型仓库必须包含
composer.json文件，且该文件里"name"字段要和你在require中写的完全一致（包括大小写） - 私有 Git 需认证？确认已配置 SSH key 或运行过
git config --global url."https://token:x-oauth-basic@github.com/".insteadOf "https://github.com/" - 运行
composer diagnose，它会明确告诉你哪个repositoryURL 返回了 404 或 401
真正卡住的点，往往不在“包在哪”，而在“Composer 是否认为它该出现”——环境约束、源配置、锁文件残留、甚至大小写拼写，都可能让一个存在的包彻底隐身。动手前先跑 composer check-platform-reqs 和 composer diagnose，比盲目删 lock 或换镜像更省时间。
