composer require找不到包但search能搜到，是因为search仅查packagist.org全局索引且不校验本地配置，而require严格按repositories顺序+minimum-stability+元数据匹配；私有源未生效、packagist.org未禁用或VCS配置错误是主因。
为什么 composer require 找不到包，但 composer search 能搜到
因为 composer search 只查 packagist.org 全局索引，不读你本地的 repositories 配置，也不校验 PHP 版本、扩展或稳定性设置；而 composer require 是真安装，会严格按 repositories 顺序 + minimum-stability + 实际元数据匹配执行。
常见现象包括：
- 私有包名和 Packagist 上某个废弃空包同名，
search返回了它，但require根本没访问你的私有源 -
composer show vendor/name显示“Package not found”，但composer search vendor/name有结果——说明包只存在于 Packagist，你的自定义源压根没生效 - 运行
composer config repositories，输出里仍含"https://repo.packagist.org"，代表packagist.org没被禁用，所有请求都会优先兜底到官方源
检查 repositories 配置是否生效且顺序正确
Composer 查源是「从上到下，命中即停」，但这个逻辑**仅在 packagist.org 被显式关闭后才启用**。否则它永远先走官方源。
必须满足两个硬性条件：
-
{"packagist.org": false}必须是repositories数组里的一个**独立对象**，不能嵌套进其他仓库配置里 - 它必须放在私有源之后、数组末尾（不是开头），例如：
"repositories": [ {"type":"composer","url":"https://pkg.myorg.com/"}, {"packagist.org": false} ] - 写成
"packagist": false或"packagist.com": false会被静默忽略；用composer config --global repos.packagist false是全局污染，其他项目会崩
VCS 类型仓库（Git/GitLab）报 404 的真实原因
VCS 仓库不参与全局元数据索引，只在你明确 require vendor/name 时才触发拉取。报 404 往往不是网络不通，而是第一步元数据读取失败。
关键检查点：
-
type必须写"vcs"，写成"git"、"github"或漏掉，整条配置被忽略 - URL 必须是可
git clone的地址，且结尾**不能带.git后缀以外的路径**（如https://gitlab.example.com/myorg/utils.git✅，https://gitlab.example.com/myorg/utils.git#main❌） - 目标仓库根目录必须有合法
composer.json文件，且name字段与require中的 vendor/name 完全一致（大小写敏感） - 分支或 tag 名必须真实存在——
"dev-main"要求远程有main分支，"1.2.3"要求有对应 Git tag，不能是release-1.2.3或v1.2.3-final
如何验证当前到底在用哪个源
别信 composer.json 里写的 repositories，它优先级低于全局配置，且容易被 fallback 掉。最可靠的方式是直接看运行时实际加载的源：
- 运行
composer config -g repos.packagist（注意是复数repos，Composer ≥ 2.2 正确键名）；输出为空或不是 JSON，说明全局镜像没配成功 - 若项目根目录有
composer.json且含"repositories"字段（哪怕只是[]），就会**完全屏蔽**全局镜像；此时要查composer config repos.packagist（不加-g） - 加
-vvv运行composer require vendor/name，观察日志里实际请求的是哪个 URL；如果出现Downloading https://repo.packagist.org/，说明你的私有源根本没被访问 - 临时切回官方源验证：
composer config -g repos.packagist composer https://packagist.org，再composer clear-cache，排除镜像同步延迟干扰
多源配置下最易被忽略的点：你以为自己在用私有源，其实 Composer 一直在走 packagist.org，连 {"packagist.org": false} 都没写对位置或类型。这种错误不会报错，只会静默跳过你的配置。
