这个报错是因包名/版本错误、环境不满足或源配置不当导致无可用候选版本；应先用 composer show -a 验证包与版本，再用 composer why-not 查具体限制，并检查 PHP 版本、扩展及镜像源配置。
直接说结论：这个报错不是 Composer 坏了，而是它认真地告诉你——你写的 vendor/package 或 "version" 在当前配置下根本“不存在可安装的候选版本”。原因通常就三类：包名/版本写错了、环境不满足要求、或源没配对。
查包名和真实版本：别靠猜，用 composer show -a
很多人输完 composer require foo/bar:^2.5 就报错，却没验证 foo/bar 是否真有 ^2.5 这个范围的版本。Packagist 上可能最新只到 1.8.0，或者作者压根没打 v2.5.0 的 tag。
- 先确认包名拼写完全一致（大小写敏感）：
composer show -a foo/bar—— 如果报Package not found，说明名字错了，立刻去 https://www.php.cn/link/5d2e892c81e5fafc51ab0973879563a0 搜 - 如果包存在，
composer show -a vendor/name会列出所有 tag 和分支，比如看到的是v1.2.3、dev-main，但你写了1.2.3（缺v前缀），就会失败 - 某些包用别名如
dev-master已被弃用，现在主流是dev-main；写dev-maste（少个r）也会静默失败
看 PHP 和扩展是否卡住了版本筛选
Composer 不会报“PHP 版本不支持”，而是直接把不兼容的版本从候选列表里剔除——你连它存在过都不知道。比如你本地是 PHP 8.3，而某包的 2.0.0 要求 "php": "^7.4 || ^8.0"，那这个版本就不会出现在 composer show -a 结果里。
- 用
composer why-not vendor/name:2.0.0查具体拦路虎：是 PHP 版本？缺ext-intl？还是某个子依赖冲突？ - 运行
php -v和php -m | grep -E "(json|mbstring|intl)"确认基础扩展已启用 - 别盲目调高
minimum-stability，先搞清是不是环境挡路
镜像源、缓存、私有包：三个最常被忽略的“隐形墙”
国内开发者尤其容易栽在这儿：阿里云镜像同步延迟、缓存未更新、私有包没加 repositories 配置——这三者会让 Composer “假装看不见”新版本。
- 临时切回官方源验证：
composer config --unset repos.packagist && composer clear-cache，再试安装 - 私有 GitHub/GitLab 包必须显式声明仓库类型：
{ "repositories": [{ "type": "vcs", "url": "https://github.com/your-org/your-package" }] }缺了这句，dev-main再对也没用 - 缓存不是“偶尔清一下”，而是每次改完
composer.json或换镜像后都该清：composer clear-cache是最低成本的排查动作
真正麻烦的从来不是报错本身，而是 Composer 把“找不到版本”的原因藏在了背后：可能是你本地 PHP 少了个扩展，可能是镜像漏同步了一个 tag，也可能是包作者把 v3.0.0 打成了 3.0.0（没加 v）。动手前，先跑一遍 composer show -a 和 composer why-not，比反复修改 composer.json 有效十倍。
