根本原因是repositories配置错误或目标结构不合规：type必须与源类型严格匹配（path/vcs/composer），url格式需正确（如vcs必须带.git），且目标目录/仓库必须含合规composer.json，name字段须与require完全一致。
私有库依赖包找不到，根本不是网络或权限问题，而是 Composer 根本没去你放包的地方找——repositories 配置漏了、写错了，或目标结构不合规，它就会静默跳过，直接报 Could not find package。
检查 repositories 是否显式声明且类型匹配
Composer 默认只查 Packagist，本地路径、Git 仓库、Satis 服务等必须手动加进 repositories，且 type 必须与实际一致：
-
type: "path"用于本地文件夹（如../my-package），url必须是相对路径，不能以/开头 -
type: "vcs"用于 Git 仓库（GitHub/GitLab），url必须带.git后缀（GitLab 和自建 Git 强制要求） -
type: "composer"用于私有 Packagist 类服务（如 Satis、Private Packagist），url是该服务的packages.json地址 - 配置错一个字段（比如把
"type":"path"写成"type":"package"），Composer 就会整个忽略这个源
验证目标目录/仓库是否含有效 composer.json
就算 repositories 写对了，目标位置没有合规的 composer.json，Composer 也读不出包信息：
- 本地
path目录下必须存在composer.json，且其中"name"字段格式为vendor/name（全小写、用斜杠、不能有空格），必须和require里写的完全一致 - Git 仓库根目录也要有
composer.json，且"name"同样需严格匹配；分支名（如dev-main）或 tag（如v1.2.3）必须真实存在，不能是main-dev或1.2.3-release - 如果本地包用了
"minimum-stability": "dev"，而主项目没设--stability=dev或没配"minimum-stability": "dev"，Composer 会过滤掉所有分支版本
排查认证与镜像干扰
私有 Git 仓库报 404，90% 是认证失败或镜像屏蔽了请求，不是 URL 写错了：
- GitHub 私有库要用 token 认证：确保
auth.json存在且格式正确，url中不能带@username（例如用https://github.com/org/repo.git，而不是https://user:token@github.com/org/repo.git） - GitLab 私有库若启用了 HTTP Basic Auth，需在
auth.json中配置对应域名的http-basic条目 - 国内镜像（如阿里云）不会同步私有仓库，也不支持
vcs或path类型源——换镜像无效，必须关掉：composer config -g repo.packagist composer https://packagist.org - 执行
composer clear-cache后再试，旧缓存可能仍指向失效地址
快速定位是否真“不存在”还是“没找对地方”
别靠报错猜原因，用这几条命令直击本质：
- 运行
composer show -a vendor/name：如果返回空，说明当前所有已启用源里都没这个包 - 运行
composer config -g repo.packagist：确认没被全局镜像劫持；如果是{"url":"https://packagist.phpcomposer.com"}这类已停用地址，立刻换掉 - 直接访问
https://packagist.org/packages/vendor/name：404 就是真的不在 Packagist；能打开但没你要的版本，就说明得靠repositories或放宽稳定性 - 删掉
vendor/和composer.lock，再跑composer install -vvv：详细日志里会打印 Composer 实际尝试访问的每个源 URL，一眼看出它到底连了哪儿、为什么跳过你的本地路径
最容易被忽略的是：Composer 对 repositories 的加载是“全有或全无”的——哪怕只多了一个逗号、少了一个引号，整个区块都会被忽略，然后继续查 Packagist。别信配置“看起来没问题”，用 composer validate 检一遍，比反复重装快得多。
