答案是源配置失效、镜像未同步或稳定性约束拦截：Composer require严格按repositories顺序（需packagist.org显式关闭且置末）、minimum-stability过滤、元数据匹配执行，而search仅查Packagist全局索引，不校验任何本地配置。
“Package not found”不是包真没了，而是 Composer 根本没去你配的源里找——90% 是源配置失效、镜像未同步、或稳定性约束拦住了。
为什么 composer search 能搜到，composer require 却报错？
因为 composer search 只查 packagist.org 全局索引，不看你的 PHP 版本、扩展、minimum-stability，也不读 repositories 配置；而 composer require 是真安装，会严格按以下顺序匹配：
- 从
repositories数组**从上到下扫描**，但前提是{"packagist.org": false}已显式关闭（且必须是独立对象、放在数组末尾） - 过滤掉所有低于
minimum-stability的版本（默认是"stable"，dev-main/beta/RC 全被跳过） - 校验目标源返回的元数据是否包含该包名+可用版本，URL 是否可访问、格式是否合法（如 VCS 类型必须写
"vcs"，不能写"git"）
检查 repositories 配置是否真正生效
运行 composer config repositories，重点看三点：
- 输出里是否还存在
"https://repo.packagist.org"—— 如果有，说明packagist.org没关，私有源再靠前也白搭 -
{"packagist.org": false}是否作为**独立对象**出现在数组末尾（不是开头，也不能嵌套在其他仓库里） - VCS 类型仓库的
url是否以.git结尾、且**无路径后缀**（如https://gitlab.example.com/myorg/utils.git✅，...utils.git#main❌）
镜像源不同步导致新包“不存在”
国内镜像（阿里云、腾讯云等）同步 packagist.org 有 5–30 分钟延迟。验证方法：
- 浏览器打开
https://mirrors.aliyun.com/composer/p/vendor/name.json（替换为你要装的包），404 或内容不含目标版本 → 镜像未同步 - 同时打开
https://packagist.org/packages/vendor/name确认官网已发布 - 执行
composer update --dry-run -v，看日志是Reading from cache还是Downloading https://...—— 前者说明缓存没刷新，后者才是真拉新数据 - 临时切回官方源快速验证：
composer config --global repo.packagist composer https://packagist.org，再composer require vendor/name -vvv
清理缓存和元数据要清对地方
composer clear-cache 不会删掉远程 packages.json 缓存（它默认复用 15 分钟内未过期的快照）。真正要清的是：
- 对应镜像子路径下的缓存目录，例如：
rm -rf ~/.composer/cache/repo/https---mirrors-aliyun-com-composer - 项目级
composer.lock和vendor/目录（尤其当锁文件残留旧约束时） - 别用
composer config --global repos.packagist false—— 这是全局污染，其他项目会崩
最干净的重建路径：删 vendor/ + 删 composer.lock + 清对应镜像缓存子目录 + composer install -v。
