composer 报“包未找到”错误的根本原因是包名格式错误、仓库未正确配置、版本约束不匹配、php/composer 版本不兼容或缓存干扰，需逐项排查大小写、斜杠、repositories、dev-前缀、minimum-stability 及镜像设置。
这个错误不是网络连不上，也不是权限被拒，而是 Composer 根本没在它配置的任何仓库里查到你写的包名——连发起请求的机会都没有。
包名大小写或 vendor/name 格式写错了
Composer 对 vendor/name 是严格大小写敏感的，且必须带斜杠分隔。Packagist 内部会强制小写化注册名，但你输入时必须完全匹配官方页面 URL 路径。
- 错例：
GuzzleHttp/guzzle、monolog、laravel\scout（反斜杠）、phpmailer（漏 vendor） - 对例：
guzzlehttp/guzzle、monolog/monolog、laravel/scout、phpmailer/phpmailer - 验证方式：打开 https://www.php.cn/link/6644eaf8176718ed4e1656418ab3628a，复制地址栏完整路径作为包名
- 注意 GitHub 仓库名 ≠ Packagist 包名（比如
laravel-scout仓库对应的是laravel/scout）
私有包或 Git 仓库没配 repositories 或配错了
Composer 默认只查 packagist.org，不会自动扫描 GitHub/GitLab 或本地路径。没声明 repositories，就等于告诉它“别去那儿找”。
-
type必须是vcs（不是git或空着），URL 必须是可 clone 的地址，如"https://github.com/yourname/package.git"，不能是网页链接 - 私有源要放
repositories数组最前面，否则 Composer 查完 packagist.org 就停了，根本不会往后看 - 如果同时禁用了默认源，必须显式写
{"packagist.org": false}，而不是删掉整个字段 - 本地
path类型要求目标目录存在且含合法composer.json，name字段必须和require里完全一致（包括大小写）
版本约束不匹配或分支名没加 dev-
即使包存在，指定一个不存在的 tag、branch 或 stability 级别，也会触发 “not found” —— 因为 Composer 解析后发现“没有满足条件的版本”。
- 分支名必须加
dev-前缀，如dev-main、dev-develop，不能直接写main - 运行
composer show vendor/name（需先配好仓库）查看真实可用版本；若报错，说明仓库还没生效 -
minimum-stability设为stable时，dev-main不会被接受，得显式写dev-main as 1.0.x-dev或临时加--stability=dev - PHP 或 Composer 版本不满足包的
require约束（如包要求 PHP ≥ 8.2，你用的是 8.1），Composer 会跳过所有版本，结果就是“找不到”
缓存或镜像源干扰了判断
旧缓存可能固化错误索引，国内镜像有时不同步新包或特定 tag，导致本地查不到但官方源能装上。
- 先跑
composer clear-cache，再试composer require - 检查当前镜像：
composer config -g repo.packagist；临时切回官方源：composer config -g repo.packagist https://repo.packagist.org - 确认没误设
"packagist.org": false却又没配替代源——这等于关掉了唯一默认仓库 - CI 或 Docker 环境下，尤其要注意路径是否跨出项目根目录（
../开头的path会被拒绝）
最容易被忽略的是：你以为在查包，其实 Composer 连包名都没认出来；你以为在装 dev 分支，其实它根本没去 Git 仓库查——所有这些，都藏在 repositories 配置和 require 写法的细节里。
