Unknown MySQL server host 错误源于操作系统层 getaddrinfo() 解析失败，非 Hyperf 或 PDO 问题；应检查容器 /etc/hosts 和 /etc/resolv.conf、用 getent hosts 验证解析、优先改用 IP 直连，并避免依赖 DNS 的域名配置。
Hyperf 应用连 MySQL 报 Unknown MySQL server host 怎么办
这不是 Hyperf 的 bug，也不是 PDO 配置问题，而是客户端发起连接时，getaddrinfo() 在操作系统层解析 host 失败。Hyperf 的 mysql 组件底层仍走 PHP 的 PDO + libc DNS 查询链路，和 mysql -h db-prod 行为一致。
常见诱因：
- 容器内没配
/etc/hosts，且resolv.conf里 nameserver 不可达（比如 Docker 默认 bridge 网络下，宿主机 DNS 不通容器） - K8s 环境中 Service 域名（如
mysql.default.svc.cluster.local）在 Hyperf Pod 里能nslookup通，但 PHP 进程启动后缓存了旧解析结果（glibc 不自动刷新） - Hyperf 配置里写的是
host: 'mysql'，而实际 DNS 解析返回 IPv6 地址，但 MySQL 服务只监听 IPv4，导致连接被拒绝（错误表现仍是 host unknown）
实操建议：
- 进 Hyperf 容器执行
getent hosts mysql，比nslookup更贴近 PHP 实际调用路径；若无输出，说明解析根本没走通 - 临时改配置：把
host改成 IP（如10.244.1.5），验证是否立刻恢复；确认后固化到部署模板 - 若必须用域名（如多集群路由），在容器启动脚本里加
echo 'options timeout:1 attempts:2' >> /etc/resolv.conf，缩短 DNS 超时，避免卡住整个连接池初始化
Hyperf 启动卡在 Connecting to xxx… 是服务端反查还是客户端解析
先看现象再判断：如果日志里出现 Connecting to mysql... 卡住几秒后才报错，且 mysql -h 127.0.0.1 -u root -p 瞬连，那基本是服务端反向解析阻塞；如果连 mysql -h mysql -u root -p 也卡，但 nslookup mysql 立刻返回 IP，则是客户端本地解析慢或失败。
Hyperf 场景中更大概率是后者——因为 PHP-FPM 或 Coroutine 进程启动时一次性批量解析所有配置里的 host，glibc 缓存未更新，又没 fallback 到 /etc/hosts，就卡死在 getaddrinfo() 系统调用上。
别碰 skip_name_resolve：它只影响 MySQL 服务端对客户端 IP 的反查，对 Hyperf 连接前的正向解析毫无作用。改了反而让已有的 'app'@'web-01.example.com' 权限失效。
关键动作：
- 检查 Hyperf 所在容器的
/etc/nsswitch.conf，确认hosts: files dns（不是files [NOTFOUND=return] dns这种激进配置） - 删掉
/etc/resolv.conf里可疑的 search 域（如search default.svc.cluster.local可能导致mysql被拼成mysql.default.svc.cluster.local.，而权威服务器没这条记录） - 用
strace -e trace=getaddrinfo php bin/hyperf.php start直接抓系统调用，看卡在哪一步
Hyperf MySQL 配置里 host 写域名 vs IP 的真实代价
写域名看着优雅，但在生产环境等于把 DNS 可用性当作数据库可用性的前置条件。一次 DNS 故障，整个 Hyperf 集群连接池初始化失败，HTTP 请求全挂，比 MySQL 慢查询还致命。
IP 地址并非完全静态：K8s StatefulSet 或云厂商 RDS Proxy 场景下，IP 会变，但变更频率远低于 DNS TTL。相比 DNS 层级的不可控（TTL、缓存、递归超时、IPv6 fallback），IP 直连的失败路径更短、更可测。
Hyperf 实际适配方式：
- CI/CD 流程中，在部署前用
dig +short mysql.prod获取当前 IP，注入到config/autoload/databases.php的host字段 - 使用 Helm/Kustomize 时，通过
envFrom注入DB_HOST环境变量，Pod 启动时由 initContainer 预解析并写入配置文件 - 绝对避免在代码里硬编码域名字符串，尤其不要在
DatabaseFactory构造函数里拼接$host = $_ENV['DB_HOST'] ?? 'mysql'—— 这会让 DNS 问题逃逸到运行时
最后提醒一句：DNS 解析失败时，Hyperf 日志里不会打印具体失败原因，只会抛 PDOException，错误信息是 “SQLSTATE[HY000] [2005] Unknown MySQL server host 'mysql'”，你得往系统层挖，而不是盯着 PHP 栈跟踪看。
