“Could not find package”绝大多数因包名错误、源未生效、缓存过期或稳定性约束导致；需先验证包是否存在、检查大小写与不可见字符、确认repositories配置位置及镜像是否真启用。
Composer 显示“Could not find package”或“Package not found”，**绝大多数情况不是网络不通，而是它压根没去你认为的那个源里查**——包名拼错、源未生效、缓存过期、稳定性约束卡死，这四类占 95% 以上。
包名拼写和存在性验证
别跳过这步直接改配置。Composer 对大小写、连字符、vendor 名极其敏感，且 composer search 和 composer require 查的不是同一套逻辑。
- 手动打开
https://packagist.org/packages/vendor/name（把vendor/name换成你要装的），看是否返回 404 页面 -
composer search vendor/name能搜到 ≠ 你能装——它只查 Packagist 全局索引，不校验版本、stability 或你的repositories - 复制包名时小心不可见字符：从网页、微信粘贴常带零宽空格，建议手动重打一遍
- 常见错误：
laravel/sanctum（对） vslaravel-sanctum（错）；spatie/laravel-backup（对） vsspatie/backup（错）
镜像源是否真在生效
很多人配了阿里云镜像，日志里却还是出现 Downloading https://packagist.org/——说明配置根本没生效，Composer 仍在直连官方源。
- 运行
composer config -g repos.packagist（注意是复数repos），输出必须是完整 JSON，如{"type":"composer","url":"https://mirrors.aliyun.com/composer/"}；为空或报错 = 没配成功 - 项目根目录若存在
composer.json且含"repositories"字段（哪怕只是[]），会**完全屏蔽全局镜像**；此时要查composer config repo.packagist（不加-g） - 旧地址如
https://packagist.phpcomposer.com已停用，会导致请求卡死或 404，必须删掉 - 临时切回官方源验证：
composer config -g repos.packagist composer https://packagist.org，再composer clear-cache
私有源或 VCS 仓库配置失效
私有包不会出现在 Packagist，Composer 默认根本不往你公司 GitLab 或本地路径里找。配置漏一个字段，它就静默忽略整个 repositories 区块。
-
repositories必须是数组，且{"packagist.org": false}必须作为**独立对象放在末尾**，例如：
"repositories": [
{ "type": "vcs", "url": "https://gitlab.example.com/mygroup/mylib.git" },
{ "packagist.org": false }
]
type 必须写 "vcs"，写成 "git" 或漏掉会被忽略；URL 必须是可 git clone 的地址，结尾只能是 .git，不能带 #main 或路径composer.json 中 name 字段，必须与 composer require 里的 vendor/name **完全一致**（包括大小写）auth.json 必须存在且权限正确；URL 里不能含 @username，否则 Composer 会跳过认证缓存与元数据未刷新
Composer 默认复用 15 分钟内未过期的 packages.json 缓存快照。镜像站可能已同步新版本，但 Composer 还在读旧元数据。
-
composer clear-cache只清 ZIP 和部分元数据，**不强制刷新packages.json** - 真正要删的是镜像对应的 provider 缓存子目录：
rm -rf ~/.composer/cache/repo/https---mirrors-aliyun-com-composer（Windows 路径为%APPDATA%\Composer\cache\repo\https---mirrors-aliyun-com-composer） - 删完立刻跑
composer update --dry-run -v，日志里出现Downloading https://...才算生效 - 验证镜像是否真同步：用
curl -I https://mirrors.aliyun.com/composer/p/vendor/package.json看是否返回200和较新的Last-Modified
最易被忽略的是：项目级 repositories 字段一旦存在，就会彻底接管查找逻辑，全局镜像、稳定性设置、甚至 minimum-stability 都可能被绕过——排查时务必先确认这个数组是否被意外写入。
