根本原因是http.responsewriter被提前写入，导致upgrade()失败；常见于中间件调用w.write()或http.error()；升级前应检查w.header().waswritten()，升级后弃用responsewriter。
gorilla/websocket 连接升级失败：http: multiple response.WriteHeader calls
根本原因是 http.ResponseWriter 被提前写入，导致后续 Upgrader.Upgrade() 无法完成协议切换。常见于中间件（如日志、JWT 验证）中调用了 w.Write() 或 http.Error()。
- 检查所有中间件，确保在
Upgrader.Upgrade(w, r, nil)前未触发任何响应写入 - 升级前加防御性判断：
if !w.Header().WasWritten() { ... } - 避免复用
http.ResponseWriter—— 升级后它已失效，不能再用于其他 HTTP 响应 - 错误日志里若出现
http: multiple response.WriteHeader calls，基本可锁定为该问题
广播性能卡在 500+ 连接就明显延迟
直接遍历全局 map[string]*websocket.Conn 并同步调用 conn.WriteMessage()，会因锁竞争和阻塞写导致吞吐骤降。这不是网络瓶颈，而是并发模型设计缺陷。
- 每个连接绑定独立
chan []byte，启动专属writePumpgoroutine 消费消息 - 广播时只向各连接的 channel 发送消息拷贝，不触碰
conn实例本身 - 务必对每个
writePump设置conn.SetWriteDeadline()，防止慢客户端拖垮整个队列 - 避免用
sync.RWMutex保护连接 map；改用sync.Map或分片 map 减少争用
客户端收不到消息但服务端无报错
最常被忽略的是帧类型不匹配：WriteMessage(websocket.BinaryMessage, ...) 发送的数据，前端 ws.onmessage 默认只接收 TextMessage，会静默丢弃。
- 默认统一使用
websocket.TextMessage，消息体用 JSON 序列化成[]byte - 前端若设了
ws.binaryType = 'arraybuffer'，服务端才可发BinaryMessage - Chrome DevTools → Network → WS → Frames 标签页可直接查看每帧的 Type 字段，快速定位 mismatch
-
WriteJSON()底层仍是TextMessage，不是“自动适配”，勿误以为它能绕过类型校验
部署后连接频繁 1006 关闭
1006 不是协议错误，而是连接被中间代理（Nginx/ALB/Cloudflare）强制切断。空闲连接未发心跳，代理超时后单方面断连，服务端甚至收不到 CloseMessage。
- 服务端必须显式设置
conn.SetPingHandler()，并主动回PongMessage - Nginx 配置需包含
proxy_read_timeout 60和proxy_send_timeout 60，且值要 ≥ 服务端心跳间隔 - gorilla v1.5.0+ 可用
Upgrader.KeepAlive简化配置，但低版本仍需手动SetPingHandler - 注意：
SetReadDeadline()必须每次读操作前重设，不能只设一次
SET user:123 online EX 30 严格对齐，或者延迟清理 goroutine 被 GC 提前回收。这点容易被测试环境掩盖，上线后才暴露。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
