Hyperf局域网连不上MySQL的根本原因是协程Hook失效、host配置错误或Docker网络隔离；应改host为宿主机IP或服务名，启用Swoole协程驱动，并确保max_idle_time小于MySQL的wait_timeout。
局域网连不上 MySQL，不是网络不通，而是 Hyperf 的连接池默认用 127.0.0.1 或 localhost 解析失败、协程 Hook 失效、或 Docker 网络隔离导致的——直接改 host 为宿主机真实 IP 或服务名，再确认 Swoole 协程驱动已启用。
为什么 ping 通但 Hyperf 连不上 MySQL？
常见现象是：ping mysql-host 成功，mysql -h mysql-host -u root -p 也能连，但 Hyperf 启动报 Connection refused 或卡在 connect_timeout。根本原因不是网络层断开，而是：
- Hyperf 默认走 Swoole 协程 Hook，但若 MySQL 客户端扩展（如
mysqli）未被正确 Hook，就会退化为同步阻塞调用，超时后直接失败 -
host配成localhost时，PHP 会走 Unix socket（而非 TCP），而容器内通常没挂载 socket 文件，导致连接被静默拒绝 - Docker Compose 中服务名（如
mysql）在 Hyperf 容器里能 DNS 解析，但若没指定network_mode: "bridge"或没共用自定义网络，解析可能返回127.0.0.11（Docker 内置 DNS）而非真实容器 IP
Hyperf 配置 host 必须填什么？
别填 localhost 或 127.0.0.1，除非 MySQL 和 Hyperf 在同一容器里（不推荐）。正确填法取决于部署方式：
- 本地 WSL2 + Docker Desktop：填宿主机 Windows 的局域网 IP（如
192.168.50.1），并在 MySQL 配置里开bind-address = 0.0.0.0、授权'root'@'192.168.%' - Docker Compose 同一 network：填服务名，如
mysql（前提是hyperf和mysql在同一networks下，且没用network_mode: host） - Kubernetes 或跨主机：填 Service ClusterIP 或 Headless Service DNS 名，避免硬编码 Pod IP
验证方式：进 Hyperf 容器执行 nslookup mysql 或 getent hosts mysql，确认返回的是目标 MySQL 容器的真实 IP（非 127.0.0.11）。
如何确认协程 Hook 生效？
Hyperf 的 MySQL 协程化依赖 Swoole 对 socket 系统调用的劫持。若失效，所有 DB 操作都会变同步阻塞。检查点：
- 确保
swoole.enable_coroutine为On（php --ri swoole查看） - 确认没加载
mysqlnd以外的旧驱动（如mysqli扩展版本过低，或启用了mysqlnd_ms等冲突扩展） - 在配置中显式启用协程驱动：
'driver' => 'pdo_mysql'（不要用mysqli），并确保pool.connect_timeout设为5.0而非默认10.0，便于快速暴露 Hook 失效问题 - 加一行测试代码：
var_dump(\Swoole\Coroutine::getuid());，若返回整数说明当前在协程上下文；若为false，说明 DB 调用没跑在协程里
局域网连接超时的三个关键 timeout 参数
connect_timeout、wait_timeout、max_idle_time 含义完全不同，配错一个就卡死：
-
connect_timeout（默认10.0）：只控制「建立 TCP 连接」耗时上限。局域网建议降到5.0，避免因 DNS 解析慢或中间网络抖动导致协程假死 -
wait_timeout（默认3.0）：控制「从连接池取连接」的排队等待时间。局域网延迟低，可保持3.0，但若并发高、连接池小，需提至5.0防止满屏wait timeout -
max_idle_time（默认60.0）：空闲连接存活秒数。局域网稳定，可设30.0～45.0，避免连接长期滞留后被 MySQL 的wait_timeout主动踢掉
注意：max_idle_time 必须严格小于 MySQL 的 wait_timeout（查法：SHOW VARIABLES LIKE 'wait_timeout';），否则连接池里“睡过头”的连接取出即失效。
最容易忽略的是：局域网看似稳定，但 Docker 网络桥接、WSL2 虚拟网卡、防火墙规则这些中间层，会让连接行为变得不可预测。别信 ping，要用 nc -zv mysql-host 3306 测端口级连通性，再用 DB::connection()->getPdo()->getAttribute(\PDO::ATTR_CONNECTION_STATUS) 确认连接对象真实可用。
