必须拆分读写协程：每条WebSocket连接需两个独立goroutine，读协程专调ReadMessage并处理CloseMessage/EOF，写协程通过带缓冲channel（size≥64）异步调用WriteMessage，避免阻塞导致消息积压和goroutine泄漏。
goroutine拆分读写协程是并发稳定的前提
每条WebSocket连接必须至少拆成两个独立goroutine：一个只负责conn.ReadMessage()，另一个只负责conn.WriteMessage()或通过缓冲channel异步写。这是Go WebSocket服务不因连接数上涨而卡死的核心机制。
常见错误是把读写塞进同一个for循环里，一旦conn.WriteMessage()阻塞（比如客户端网络抖动、接收缓冲区满），整个协程挂住，导致后续消息无法读取，堆积后触发I/O等待上升甚至连接假死。
- 读协程收到
io.EOF或websocket.CloseMessage时应主动退出，不要panic或忽略 - 写协程必须用带缓冲的
chan []byte（建议buffer size ≥ 64）接收消息，避免直接调用WriteMessage阻塞读协程 - 关闭连接前，需显式调用
conn.Close()并停止读写协程，否则goroutine泄漏
Upgrader配置必须绕过非标客户端握手限制
生产环境常遇到SockJS、Spring WebFlux或某些移动端SDK封装层握手失败，根本原因不是协议错，而是gorilla/websocket.Upgrader默认校验过于严格：拒绝空Origin、强制匹配Sec-WebSocket-Protocol、校验Sec-WebSocket-Accept签名。
解决方案不是降级到HTTP轮询，而是精准放宽校验项：
立即学习“go语言免费学习笔记（深入）”；
-
CheckOrigin不能无条件返回true，至少白名单过滤：origin == "https://myapp.com" || origin == "http://localhost:3000" - 若客户端未声明子协议但服务端要求，设
Subprotocols: []string{}可跳过协商；若强依赖（如graphql-ws），则必须显式传入对应值 - 某些服务端会注入非法
Sec-WebSocket-Extensions头，此时需在客户端侧用自定义http.RoundTripper过滤响应头
连接管理必须用Hub模型而非全局map
直接用map[*websocket.Conn]bool存活跃连接看似简单，但并发读写时极易触发panic：map是不安全的。真正的高并发连接管理必须基于中心化Hub——它内部封装了sync.RWMutex或sync.Map，并提供原子注册/注销/广播接口。
典型结构包含三个核心组件：
-
clients map[uint64]*Client：每个Client封装*websocket.Conn、用户ID、房间ID等元数据 -
register和unregister通道：所有连接生命周期变更都走channel，由单一goroutine串行处理，彻底规避锁竞争 -
broadcast通道：消息统一入队，由广播goroutine按房间/标签批量分发，避免逐个WriteMessage带来的调度开销
多端在线状态同步依赖心跳与连接亲和性设计
Web、iOS、Android、桌面端同时在线时，“最后活跃设备”逻辑不能靠客户端上报，必须由服务端通过心跳维持真实连接状态。关键点在于：
- 服务端必须主动发
conn.WriteControl(websocket.PingMessage, nil, time.Now().Add(10*time.Second))，不能只依赖TCP KeepAlive——后者超时太长（通常2小时），且无法感知应用层断连 - 每个用户ID应绑定多个
clientID，而不是单个连接；上线时注册新clientID，下线时注销；同一用户多端在线时，消息需广播到所有该用户的clientID - 横向扩展时，连接状态不能只存在本地内存，需接入Redis Pub/Sub或轻量消息队列（如NATS）同步
register/unregister事件，否则跨实例消息丢失
最易被忽略的是：心跳超时阈值必须大于客户端ping间隔（比如服务端设30秒超时，客户端每15秒ping一次），且ReadMessage需设置SetReadDeadline配合，否则goroutine会在阻塞读上无限等待。
