Hyperf 3.1.67 中 Guzzle 持久化 Cookie 需显式配置 FileCookieJar 实例、确保路径权限（chmod 600）、复用单例 jar 以避免协程写入冲突，并注意 JSON 存储格式与旧版 serialize 的兼容性断层。
Hyperf 3.1.67 中的 Guzzle 持久化 Cookie 不是“开箱即用”的自动行为，而是依赖 GuzzleHttp\Cookie\FileCookieJar 显式配置 + 正确路径权限 + 协程安全写入控制，缺一不可。
FileCookieJar 实例必须手动传入 client 配置
Hyperf 默认的 ClientFactory 不会自动启用持久化 Cookie，它只提供协程封装，底层仍走 Guzzle 原生逻辑。要启用持久化，必须在创建 client 时显式注入 FileCookieJar 实例：
- 错误做法：仅设置
cookies => true—— 这只会启用内存 CookieJar，进程重启即丢 - 正确做法：构造
FileCookieJar并传入cookies选项：$jar = new FileCookieJar('/tmp/cookie-store.json', true); $client = $this->clientFactory->create([ 'cookies' => $jar, 'base_uri' => 'https://api.example.com', ]); - 路径必须可写且仅所有者可读（
chmod 600），否则 Guzzle 会在 PHP 8.2+ 下静默失败或抛出RuntimeException
协程环境下写入冲突会导致 Cookie 丢失
FileCookieJar 默认不是协程安全的，多个并发请求同时写入同一文件时，后写入的会覆盖前写入的内容，最终只保留最后一次的 Cookie。
- 现象：登录后调用多个接口，部分请求携带旧 session 或无 Cookie
- 根本原因：Guzzle 内部调用
file_put_contents($file, $data, LOCK_EX)，但 Hyperf 协程调度下LOCK_EX无法跨协程生效 - 解决方式：改用单例共享的
FileCookieJar实例，并确保所有 client 复用同一个实例（不要每次 new） - 额外加固：在
onWorkerStart中预创建 jar 实例并绑定到 DI 容器，避免 worker 启动时并发初始化冲突
Cookie 存储格式变更影响兼容性
v3.1.67 使用的 Guzzle 8.0+ 将 FileCookieJar 底层存储从 PHP serialize() 改为 JSON，这是安全加固措施，但也带来兼容断层：
- 旧版本（Guzzle 7.x）生成的
.txt文件无法被新版本直接读取，会抛出JsonException或空 jar - 迁移方案：用旧版 Guzzle 加载原文件 → 导出为数组 → 用新版
FileCookieJar::fromArray()重建 - 注意
expires字段在 JSON 中是整型时间戳（秒级），不是字符串；domain和path必须严格匹配，大小写敏感 - 若需降级兼容，可自定义
CookieJar实现，但不推荐——放弃安全加固得不偿失
真正踩坑的点不在“怎么配”，而在“谁在写、何时写、写到哪”。持久化 Cookie 的可靠性，取决于你是否控制了 jar 实例生命周期、文件权限和协程写入顺序，而不是仅仅调对了一个构造函数。
