composer search 与 require 行为不一致，是因为 search 仅查 packagist.org 全局索引且不校验环境，而 require 严格按 repositories 顺序（需显式禁用 packagist.org 并置于末尾）、minimum-stability 规则及镜像同步状态执行安装。
“composer search 能搜到，但 require 就报 Package not found”——这不是网络或拼写问题，而是 Composer 根本没按你预期的源去查元数据。
为什么 composer search 和 require 行为不一致
composer search 只访问 packagist.org 全局索引，不校验 PHP 版本、扩展、minimum-stability，也不读你项目里的 repositories 配置；而 composer require 是真安装流程，会严格按以下顺序执行：
- 从
composer.json的repositories数组从上到下扫描 - 前提是
{"packagist.org": false}已显式禁用（且是独立对象、位于数组末尾） - 否则它永远先 fallback 到官方源，你的私有源或镜像配置可能被跳过
- 再叠加
minimum-stability过滤（默认"stable"，会直接忽略dev-main或v3.0.x-dev）
检查 repositories 配置是否生效
运行 composer config repositories，重点看输出里是否还存在 https://repo.packagist.org —— 如果有，说明 {"packagist.org": false} 没生效，或者写错了位置。
- 必须是
{"packagist.org": false}，不是"packagist": false或"packagist.com": false - 必须是
repositories数组里的一个**独立对象**，不能嵌套在其他仓库配置里 - 必须放在私有源之后、数组末尾，例如：
[{"type":"composer","url":"https://pkg.myorg.com/"},{"packagist.org": false}] - 别用
composer config --global repos.packagist false，这是全局污染，其他项目会崩
确认包版本是否被 stability 规则过滤
即使包存在，只要它的版本标记不是 stable（比如只有 dev-main、v4.0.0-beta），而你项目设了 "minimum-stability": "stable"，Composer 就会跳过它，报 “Package not found”，而不是 “no matching version”。
- 运行
composer show -a vendor/name查看该包所有可用版本及稳定性标记 - 临时允许非 stable 版本：
composer require vendor/name --stability=dev --no-update，再单独composer update vendor/name - 不推荐长期把
minimum-stability改成dev，容易引发其他依赖升级失控 - 若只用某个分支，直接写
"vendor/name": "dev-main"，比降级全局 stability 更安全
验证镜像源是否同步延迟
国内镜像（如阿里云、腾讯云）对 packagist.org 同步有 5–30 分钟延迟。新发布的包或刚打的 tag，在镜像里可能还没出现。
- 浏览器打开
https://mirrors.aliyun.com/composer/p/vendor/name.json，看是否返回 404 或内容缺失目标版本 - 同时打开
https://packagist.org/packages/vendor/name确认官网已发布 - 临时切回官方源验证：
composer config --global repo.packagist composer https://packagist.org，再试composer require - 注意：
composer clear-cache不会强制刷新远程packages.json，缓存未过期（15 分钟内）就继续读旧数据
最常被忽略的是：repositories 顺序 + packagist.org 开关必须**同时满足**，缺一不可；而很多人只改了顺序，忘了关兜底源，或者关了但没放对位置。这导致你以为配好了私有源，其实 Composer 一次都没访问过它。
