本文详解 Go Web 应用中 MySQL 连接因服务端 wait_timeout 导致的“unexpected EOF”和“broken pipe”错误，提供可落地的连接池配置策略、关键参数协同逻辑及验证方法。
本文详解 go web 应用中 mysql 连接因服务端 `wait_timeout` 导致的“unexpected eof”和“broken pipe”错误，提供可落地的连接池配置策略、关键参数协同逻辑及验证方法。
在 Go 中使用 database/sql + go-sql-driver/mysql 访问 MySQL 时，长时间空闲后首次请求常触发如下错误：
[mysql] 2017/02/08 16:31:56 packets.go:33: unexpected EOF [mysql] 2017/02/08 16:31:56 packets.go:130: write tcp 127.0.0.1:49188->127.0.0.1:3306: write: broken pipe
根本原因在于 MySQL 服务端主动关闭了空闲连接（由 wait_timeout 参数控制），而 Go 的 sql.DB 连接池默认复用旧连接，未感知其已失效。
✅ 正确解法：三参数协同配置（非单点调优）
关键不是“禁用超时”，而是让客户端连接池主动淘汰即将过期的连接，使其与 MySQL 服务端策略对齐。需同时设置以下三项：
db, err := sql.Open("mysql", "user:pass@tcp(127.0.0.1:3306)/dbname?parseTime=true")
if err != nil {
log.Fatal(err)
}
// 1. 设置连接最大存活时间（核心！必须 ≤ MySQL 的 wait_timeout）
db.SetConnMaxLifetime(120 * time.Second) // 推荐设为 wait_timeout 的 60%~80%
// 2. 控制空闲连接数量（避免资源浪费，同时保证可用性）
db.SetMaxIdleConns(5) // 建议 ≥ 2，0 会导致每次查询都新建连接，性能骤降
// 3. 限制最大打开连接数（防爆库）
db.SetMaxOpenConns(20) // 根据并发量和 DB 负载调整，通常 10–50 合理⚠️ 注意：
SetConnMaxLifetime(0)（即永不过期）是常见误区——它会让连接池持续复用已被 MySQL 关闭的连接，必然触发 EOF 错误；SetMaxIdleConns(0)则强制无缓存，每次查询都建连+断连，严重拖慢性能且易触发连接数上限。
? 验证与诊断步骤
-
查 MySQL 实际超时值（单位：秒）：
SHOW GLOBAL VARIABLES LIKE 'wait_timeout'; -- 示例输出：300 → 即 5 分钟
-
观察连接状态，确认是否被 MySQL 主动回收：
SHOW PROCESSLIST; -- 查找 State = 'Sleep' 且 Time > wait_timeout 的连接（如 Time=320），说明已被服务端标记待清理
-
检查 Go 连接池健康度（可选）：
fmt.Printf("Open: %d, Idle: %d\n", db.Stats().OpenConnections, db.Stats().Idle)
? 补充最佳实践
-
Docker 环境特别注意：MySQL 官方镜像默认
wait_timeout=28800（8 小时），但部分云数据库或自定义配置可能为300（5 分钟）。务必以实际SHOW GLOBAL VARIABLES结果为准。 -
连接字符串追加参数：添加
&timeout=30s&readTimeout=30s&writeTimeout=30s可防止网络层卡死，但不能替代SetConnMaxLifetime。 -
应用启动时预热连接池（可选）：
if err := db.Ping(); err != nil { log.Fatal("Failed to ping DB:", err) }
正确配置后，连接池会在连接“自然死亡前”主动轮换，彻底规避 unexpected EOF 和 broken pipe，兼顾稳定性与性能。记住：客户端连接池的生命周期管理，必须与服务端超时策略严格对齐。
