Composer why命令排查由于多版本 Guzzle 冲突导致的 cURL 异常

Composer的依赖冲突问题，说来也简单，根子往往在一处：项目中不同的包，同时要求了Guzzle，但偏偏要的是互不兼容的版本。一个要6.x，一个非7.x不可，神仙打架，Composer只好两手一摊，罢工了事。要治这个毛病，得顺着Composer给的线索，一步步往回倒查。

composer why guzzlehttp/guzzle 显示多个版本路径，但项目只用一个

这个提示通常意味着，不同层级的包各自拉了一个Guzzle版本进来，而且互相不认。比如你的主框架要求了Guzzle ^7.4，但某个测试工具通过它的HTTP客户端，又间接依赖了Guzzle ^6.5。倒霉的PHP只能同时加载一个Guzzle版本，一旦运行到调用v6特有方法（比如HandlerStack::push()）的代码，而实际加载的是v7，就会直接炸掉，常见的错误就是Call to undefined method，或者是cURL相关的异常，比如curl_setopt_array(): CURLOPT_HEADERFUNCTION is not supported。

• 排查的时候，先留意一下composer why guzzlehttp/guzzle的输出里，是不是出现了require-dev里的包（比如orchestra/testbench、mockery/mockery）。遇到这种情况，优先加个--no-dev参数验证一下：跑一遍composer update --no-dev --dry-run -v，看看问题是不是没了。
• 如果去掉dev包后冲突消失，那恭喜你，问题不在业务代码里，八成是测试工具链把版本选择搅浑了。
• 别急着把require-dev删掉。先查查是哪个测试工具干的：运行composer show --tree phpunit/phpunit | grep guzzle，看它到底依赖了Guzzle的哪个版本。

composer why-not guzzlehttp/guzzle:^7.5 报 “because your-project requires guzzlehttp/guzzle ^6.5”

这个报错信息里的your-project，大概率不是你亲手在composer.json里写的。它往往是某个私有的SDK、或者一个老旧的组件，在它的composer.json里把Guzzle版本写死了。好比说，一个叫acme/payment-sdk的包，里面直接写了"guzzlehttp/guzzle": "6.5.4"，那Composer无论如何也升不到7.x。

• 运行composer why-not guzzlehttp/guzzle:^7.5，看看输出结果的最后一行，是不是指向了你项目里的某个私有包（比如acme/payment-sdk）。
• 如果确认是它，就得去那个SDK的仓库里改它的composer.json：把"guzzlehttp/guzzle": "6.5.4"放宽成"guzzlehttp/guzzle": "^6.5 || ^7.0"。当然，前提是这个SDK的代码本身能兼容两套Client API。
• 万一这个SDK不受你控制，那就得走个折中方案：把你想装的那个最新包降级。比如你想装lara vel/sanctum:^3.0，但它非要Guzzle ^7.2，那你就换用lara vel/sanctum:^2.15，这个版本是支持Guzzle ^6.5的。

composer show --tree guzzlehttp/guzzle 显示两个不同版本被同时锁定

这种情况比较隐蔽，属于“隐式多版本冲突”。Composer实际上只会装一个版本，但composer.lock文件里却记录了多个路径指向不同版本。这通常说明之前执行过不干净的composer update，或者混用了--with-all-dependencies参数。结果就是vendor/目录下的Guzzle文件可能残缺不全，自动加载机制随机抓一个版本，导致cURL行为完全随机——超时设置失效了、header处理错乱了，什么怪事都可能发生。

• 先跑一下composer show guzzlehttp/guzzle，确认当前实际安装的是哪个版本（注意看末尾的(locked to X.Y.Z)）。
• 如果show和show --tree显示的版本不一致，说明composer.lock文件已经损坏了。别犹豫，直接删掉vendor/和composer.lock，然后重新跑composer install，这是最稳妥的修复方式。
• 千万别用composer update guzzlehttp/guzzle来单点升级。这招只能更新最顶层的引用，而底下的间接依赖锁死的旧版本纹丝不动，最后还是可能导致自动加载冲突。

PHP cURL 扩展版本与 Guzzle 运行时行为不匹配

Guzzle v7+ 默认启用了很多新选项，比如CURLOPT_HEADERFUNCTION。但有些PHP环境——特别是老旧的cURL库，或者Alpine Linux上用的musl libc——压根不支持这些新特性。结果就是运行时直接触发warning，或者静默失败，表现为HTTP请求没有响应、重定向丢失、header乱码等等。

• 检查一下PHP的cURL版本：运行php -r "echo curl_version()['version'] . "\n";"。如果版本低于7.64.1，建议把系统cURL升级一下。
• 临时绕过：在创建Guzzle Client的时候手动禁用新特性：new GuzzleHttp\Client(['curl' => [CURLOPT_HEADERFUNCTION => null]])。
• 但归根结底，最好的办法是统一环境。CI和生产环境都使用相同的基础镜像（比如php:8.2-apache，而不是php:8.2-cli），避免因为构建环境差异导致cURL行为不一致。

说一千道一万，真正卡住你的往往不是Guzzle本身，而是它上下游某个没打tag的私有包，或者require-dev里一个三年没更新的mock工具。排查的时候，盯住composer why-not输出的最后一行——那才是真正的“封杀者”，找到了它，问题就解决了一半。