“Package not found”主因是源未生效或元数据不匹配：需先访问packagist.org验证包存在，再检查repositories配置（如packagist.org是否显式禁用）、minimum-stability约束、镜像同步延迟及本地缓存过期，临时切官方源并查-vvv日志可准确定位。
“Package not found”不是网络问题，而是 Composer 根本没在你预期的地方找——先确认包是否存在、再确认它是否被配置的源真正覆盖到。
怎么确认包在 Packagist 上真实存在
别靠记忆或文档，直接验证元数据源头：
- 打开
https://packagist.org/packages/vendor/name（把vendor/name换成你要装的包名），看页面是否返回 404；如果 404，说明 Packagist 压根没收录这个包 - 运行
composer search vendor/name，无输出 = 官方索引里没有，不是镜像或缓存的问题 - 检查大小写和连字符：
monolog/monolog对，Monolog/monolog或monolog-monolog错；spatie/laravel-backup对，spatie/backup错 - 复制包名时小心不可见字符：从网页、IM 工具粘贴容易带零宽空格或全角符号，建议手动重打一遍
为什么 composer search 能搜到，composer require 却报错
composer search 只查 Packagist 全局索引，不校验稳定性、PHP 版本、扩展或你的 repositories 配置；而 composer require 是真安装，会严格按以下规则匹配：
- 项目
composer.json中的"minimum-stability"（默认"stable"）会过滤掉所有dev-、beta、alpha版本 - 如果包只有
dev-main，但没加--stability=dev，就会静默跳过，报 “not found” 而非 “no matching version” -
composer show vendor/name可以验证本地是否已有该包（哪怕旧版），避免因锁版本导致新版本无法解析 - 项目级
repositories字段若存在（哪怕为空数组[]），会**完全屏蔽全局镜像配置**，此时要查composer config repo.packagist（不加-g）
怎么验证当前到底在用哪个源
很多人改了镜像却没生效，是因为配置键名、位置或覆盖逻辑错了：
- Composer ≥ 2.2 正确的全局镜像键是
repos.packagist（复数），写成repo.packagist会被静默忽略 - 运行
composer config -g repos.packagist，输出必须是完整 JSON，如{"type":"composer","url":"https://mirrors.aliyun.com/composer/"}；输出为空或报错，说明没配成功 - 私有源要生效，
{"packagist.org": false}必须是repositories数组里的一个**独立对象**，且放在数组末尾；写成"packagist": false或嵌套在其他仓库里，都会失效 - 临时切回官方源验证：
composer config -g repos.packagist composer https://packagist.org，然后立刻composer require vendor/name -vvv看日志里下载地址是不是packagist.org
镜像同步延迟和元数据缓存怎么破
阿里云、腾讯云等镜像不是实时同步，新包发布后可能延迟 5–30 分钟；更关键的是 Composer 默认复用 15 分钟内未过期的元数据缓存，即使你刚换镜像也读旧数据：
- 直接访问镜像的元数据接口验证是否同步：
https://mirrors.aliyun.com/composer/p/vendor/name.json，看返回内容是否含你要的版本 -
composer clear-cache不够，它不清元数据快照；要强制刷新，用composer update --refresh或删缓存子目录：rm -rf ~/.composer/cache/repo/https---mirrors-aliyun-com-composer - 运行
composer update --dry-run -v，观察日志里是Reading from cache还是Downloading https://...；后者才说明真在拉新数据 - 私有 VCS 仓库（Git/GitLab）报 404，大概率是
type写错（必须是"vcs"，不是"git"）或 URL 含非法路径（如带#main或多余路径）
最常被忽略的一点：私有包的 repositories 配置错一个字段，Composer 就会静默跳过整个区块，继续查 packagist.org —— 你看到的 “not found”，其实是它压根没去你写的 Git 地址里找。
