GuzzleHttp\Client 是独立的出站 HTTP 客户端，非 CodeIgniter 自带；需通过 Composer 安装，推荐在服务类或容器中单例化；get() 返回 ResponseInterface，须手动解析 body 并检查状态码；POST 时 form_params 与 json 不可混用；默认不抛异常，需显式配置 http_errors。
GuzzleHttp\Client 不是 CodeIgniter 自带的 HTTP 客户端库，CodeIgniter 本身提供的是 \CodeIgniter\HTTP\IncomingRequest 和 \CodeIgniter\HTTP\Response，用于处理入站请求和构建出站响应；而 GuzzleHttp\Client 是一个独立的、面向出站请求（即你主动调用第三方 API） 的 PHP HTTP 客户端。两者职责完全不同，不能混淆。
要在 CodeIgniter 中使用 Guzzle，必须手动引入并管理它——不是“集成进框架”，而是“在框架里用它”。
怎么装 Guzzle 到 CodeIgniter 项目里
CodeIgniter 4 默认用 Composer 管理依赖，所以直接装就行：
- 确保项目根目录有
composer.json（CI4 项目默认就有） - 运行：
composer require guzzlehttp/guzzle - 安装后，
vendor/autoload.php会自动加载 Guzzle 类，无需额外require
注意：不要用 require './vendor/autoload.php' 手动引入——CI4 的 autoloader 已经接管了，手动加反而可能破坏命名空间解析。
在哪实例化 GuzzleHttp\Client
别在控制器方法里每次 new 一个 Client。它内部维护连接池和 handler stack，频繁新建浪费资源、还可能触发 DNS 超时或连接数耗尽。
- 推荐放在服务类中（如
app/Services/ApiService.php），构造函数里初始化一次 - 或注册为 CI4 的服务容器单例：
$services->add('guzzle', function() { return new \GuzzleHttp\Client(['timeout' => 10]); }); - 避免在
BaseController的__construct()里 new，除非你明确需要每个请求都隔离配置
get() 返回的是 ResponseInterface，不是数组
这是最常踩的坑：你以为 $client->get('https://api.example.com/users') 返回 JSON 数组，其实返回的是 Guzzle 的响应对象。
- 要取原始响应体字符串：
$res->getBody()->getContents() - 要转成 PHP 数组（假设是 JSON）：
json_decode($res->getBody()->getContents(), true) - 别漏判状态码：
if ($res->getStatusCode() !== 200) { /* 处理错误 */ } - 如果目标接口返回 GBK 编码，
getContents()拿到的是乱码字节，得补一句：mb_convert_encoding($res->getBody()->getContents(), 'UTF-8', 'GBK')
POST 提交数据时，form_params 和 json 别混用
很多开发者以为传个数组就行，结果接口收不到字段——因为底层 Content-Type 和序列化方式完全不同。
- 发表单数据（
application/x-www-form-urlencoded）：['form_params' => ['username' => 'foo', 'token' => 'bar']] - 发 JSON（
application/json）：['json' => ['username' => 'foo', 'token' => 'bar']] - 传文件必须用
multipart，form_params里塞CURLFile会变成字符串字面量，上传失败 -
json选项不接受资源句柄（比如fopen()返回值），只认数组或标量
Guzzle 在 CodeIgniter 里就是个“外部工具”，没有魔法集成。真正容易被忽略的点是：它默认不把 404/500 当异常抛出，http_errors => false 是默认行为——这意味着你得自己检查 getStatusCode()，或者显式配 ['http_errors' => true] 再用 try-catch 捕获 RequestException。
