composer why-not 是诊断依赖冲突的工具，用于查明为何指定包无法安装，通过回溯依赖图指出PHP版本、扩展或根需求等具体冲突点。
composer why-not 是什么，能解决什么问题
它不是用来“安装失败后自动修复”的命令，而是专门查依赖冲突的诊断工具。当你执行 composer require some/package 报错说“could not find a version matching…” 或 “your requirements could not be resolved”，composer why-not 就是第一反应该用的命令——它告诉你：**为什么当前项目环境里无法满足这个包的依赖条件**。
基本用法和常见错误现象
直接运行 composer why-not vendor/package:version（版本可省略），Composer 会回溯整个依赖图，找出哪个已安装包或 root 要求挡住了目标包的安装。典型输出像：
myapp/myproject dev-main requires php (^8.1) monolog/monolog 3.5.0 requires php (^8.0) some/package 2.0.0 requires php (^7.4)
这时你就知道：不是 some/package 本身坏了，而是它要求 PHP 7.4，而你的项目锁定了 PHP 8.1 —— 冲突根源在 PHP 版本约束上。
容易踩的坑：
- 忘记加版本号，比如写
composer why-not guzzlehttp/guzzle而不是composer why-not guzzlehttp/guzzle:^7.0，可能返回“no matching package”，因为默认查 latest stable，而你本地已装的是 ^8.0； - 误以为它能查“未声明但间接需要的包”，其实它只分析显式约束（
require和require-dev中的条目）； - 在未
composer install过的空项目里跑，会提示 “Your lock file does not contain a compatible set of packages”，因为没有依赖图可分析。
配合其他命令定位真实瓶颈
composer why-not 给的是“静态约束冲突”，但实际安装失败还可能是网络、权限、平台配置等导致。建议按顺序排查：
- 先跑
composer why-not vendor/package:desired-version看是否约束冲突； - 再跑
composer prohibits vendor/package:desired-version（功能几乎一样，但输出更紧凑，适合快速扫）； - 如果提示 “package not found”，检查是否拼错 vendor 名，或该包是否已废弃（去 packagist.org 搜确认）；
- 若输出里出现
ext-xxx（如ext-intl），说明缺 PHP 扩展，用php -m验证； - 遇到
Root composer.json requires ... but it is not satisfiable类报错，重点看why-not输出里 root 的require行（即你composer.json里写的那行）是否和其他包硬性互斥。
为什么有时候 why-not 没用，得换思路
它不处理以下情况：
- 私有仓库未配置（
repositories缺失或 type 错误），why-not根本看不到包； - 包存在但被
minimum-stability挡住（比如你要dev-master，但 stability 是stable），它不会提示“稳定性不足”，只会说“no version matches”； - 平台配置（
config.platform.php）伪造了 PHP 版本，导致实际环境和 Composer 认为的不一致——这时why-not的结论是对的，但现实运行仍可能崩。
真正卡住的时候，往往不是命令不会用，而是没意识到 Composer 的决策基于 lock 文件 + 平台配置 + 当前 require 声明三者共同作用——少看其中一环，就容易把 why-not 的输出当最终答案。
