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 不受你控制，就需要采取折中方案：将你想安装的最新包降级。例如，你想安装 laravel/sanctum:^3.0，但它要求 Guzzle ^7.2，那么你可以改用 laravel/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 输出的最后一行——那才是真正的“封杀者”，找到了它，问题就解决了一半。