Consul连接超时主因是host配置错误或网络不通，而非Guzzle超时设置；需分层配置connect_timeout、read_timeout及Swoole超时；必须启用连接池；长轮询请求须单独配置超时并复用客户端。
Consul连接超时根本不是Guzzle的问题
Hyperf 启动时刷 ConnectException: Connection timed out，90% 情况下跟 Guzzle 超时配置无关，而是 consul.host 配错了——比如写成 127.0.0.1，但 Consul 实际跑在另一台机器或容器里。网络不通、防火墙拦截、DNS 解析失败，这些底层连通性问题，再调 connect_timeout 也没用。
先验证基础连通性：
- 在 Hyperf 服务所在机器上执行
telnet consul.example.com 8500或nc -zv consul.example.com 8500 - 检查
config/autoload/consul.php中的host和port是否可路由、端口是否开放 - 若 Consul 启用了 ACL，确认
token字段已填且权限足够（比如有kv读权限）
Guzzle客户端必须分层设超时，单设timeout无效
Hyperf 的 hyperf/consul 客户端底层用的是 Guzzle，而它默认走 CoroutineHandler，但协程化不等于自动智能超时。只配 timeout 会导致：DNS 解析卡住、TCP 握手慢、响应流中断等场景全部挤在同一个计时器里，无法精准归因和干预。
正确做法是三层对齐：
-
connect_timeout：控制 DNS + TCP 建连耗时，建议设2～3秒（云环境略放宽） -
read_timeout：建连后等待首字节 + 完整响应的时间，建议比总超时小 1～2 秒，例如总超时 5 秒，这里设4 -
swoole.connect_timeout和swoole.timeout：Swoole 底层 HTTP 客户端的独立超时，必须显式同步设置，否则协程层超时逻辑不生效
示例配置（config/autoload/consul.php）：
'timeout' => 5,
'connect_timeout' => 3,
'read_timeout' => 4,
'swoole' => [
'connect_timeout' => 2,
'timeout' => 4,
],
Consul客户端默认没开连接池，高频请求会直接打爆
Hyperf 的 hyperf/consul 组件默认每次 new Client 都新建底层连接，没有复用。在配置热更新、服务发现轮询等场景下，短时间发起大量请求，极易触发 Too many connections 或被 Consul 限流拒绝。
必须手动启用连接池，关键点：
- 连接池需通过
PoolHandler注入到 GuzzleHandlerStack，不能只靠ClientFactory::create()默认行为 - 池大小要匹配 Consul 集群负载能力，一般
min_connections => 2、max_connections => 20足够中小规模使用 - 确保
config/autoload/consul.php中的pool配置项存在且生效（部分旧版文档漏写了这步）
补全连接池配置示例：
'pool' => [
'min_connections' => 2,
'max_connections' => 20,
'connect_timeout' => 3.0,
'wait_timeout' => 10.0,
'heartbeat' => -1,
],
长轮询阻塞请求（Blocking Query）必须单独控时
Consul 配置热更新依赖 GET /v1/kv/?wait=60s 这类阻塞请求，它的生命周期和普通 HTTP 请求完全不同：它本意就是挂起 60 秒，等变更才返回。如果沿用上面那套 timeout => 5，请求会在 5 秒内强制中断，导致监听失效、配置无法及时刷新。
解决方案是「按用途区分客户端」：
- 普通 KV 查询、服务注册用一套带连接池 + 分层超时的客户端
- 专门用于
watch的长轮询请求，单独创建一个客户端，仅调高timeout和read_timeout（如设为65），并关闭重试（retries => 0） - 不要把
wait参数塞进通用客户端配置，它只应在具体请求时动态传入
容易忽略的是：这个长轮询客户端一旦创建，应复用整个生命周期，而不是每次 watch 都 new 一个。
