PHP版本不匹配是composer require guzzlehttp/guzzle失败主因，需按PHP版本选Guzzle 6/7/8：PHP≥7.2用^7.5，≥7.4用^7.9，8.1+慎用^8.0并检查psr7 v2冲突。
PHP 版本不匹配会导致 composer require guzzlehttp/guzzle 失败
直接运行 composer require guzzlehttp/guzzle 报错，八成是 PHP 版本和 Guzzle 主版本不兼容。Guzzle 6 要求 PHP ≥ 5.5，Guzzle 7 要求 PHP ≥ 7.2，Guzzle 8 要求 PHP ≥ 7.4 —— 而当前（2026 年）主流 ThinkPHP/Laravel 项目多跑在 PHP 7.4–8.1 上，但很多人还在用旧服务器或 Docker 镜像，默认 PHP 是 7.0 或 7.1。
执行 php -v 确认版本后，按需指定子版本：
- PHP 7.2–7.3 →
composer require guzzlehttp/guzzle:^7.5 - PHP 7.4–8.0 →
composer require guzzlehttp/guzzle:^7.9（稳定、无 PSR-7 v2 冲突风险） - PHP 8.1+ 且明确需要新特性 → 可试
composer require guzzlehttp/guzzle:^8.0，但必须检查是否已有guzzlehttp/psr7v2 依赖，否则会和旧版psr7冲突 - PHP 7.0 或更低 → 不建议强行装 Guzzle 7，应先升级 PHP；若实在无法升级，仅限应急用
composer require guzzlehttp/guzzle:6.5.5
国内网络下 composer require 卡住或报 timeout 错误
默认 Packagist 源在国内响应慢、偶发中断，composer require 极易失败，表现为命令长时间无响应、提示 Connection timed out 或 Failed to decode response。
必须切换镜像并清理缓存：
- 设阿里云全局镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 清本地缓存：
composer clear-cache - 删掉项目根目录的
vendor和composer.lock（尤其之前安装失败过） - 再执行带版本号的安装命令，例如：
composer require guzzlehttp/guzzle:^7.9
Laravel/ThinkPHP 中 new Client() 报 Class 'GuzzleHttp\Client' not found
安装成功 ≠ 能用。Composer 包已下载到 vendor/，但自动加载器没被引入，类就找不到。
ThinkPHP：检查入口文件 public/index.php 是否包含 require __DIR__.'/../vendor/autoload.php';；若使用模块化控制器（如示例里的 app\huanxin\controller\Base），确保该控制器顶部有 use GuzzleHttp\Client;。
Laravel：通常没问题，但若手动修改过 composer.json 或禁用了自动发现，可运行 composer dump-autoload 强制重生成映射。
通用验证法：在任意可执行 PHP 文件里写一行 var_dump(class_exists('GuzzleHttp\Client'));，返回 true 才算真正可用。
安装后发请求仍失败，常见配置遗漏点
即使类能加载、new Client() 成功，实际调用 $client->get() 还可能失败，原因常不在 Guzzle 本身，而在基础环境或参数缺失：
- PHP 必须启用
openssl和curl扩展（Windows 查php.ini是否取消注释extension=openssl和extension=curl；Linux/macOS 用php -m | grep -E 'openssl|curl'确认） - 未设超时，导致请求卡死：
new Client(['timeout' => 10])或在request()第三个参数里加'timeout' => 10 - 没捕获异常，
RequestException直接崩掉脚本：try { ... } catch (\GuzzleHttp\Exception\RequestException $e) { ... } - HTTPS 请求被证书校验拦截（尤其测试环境）：临时加
'verify' => false（仅调试用，上线必须配好 CA 证书）
最易忽略的是 OpenSSL 扩展未启用——它不报 Class not found，而是在发起 HTTPS 请求时抛出 cURL error 60 或 77，查日志才能定位。
