gorilla/websocket是Go生态WebSocket服务端的事实标准，必须正确使用其原语：禁止http.HandleFunc直接注册（因连接会被自动关闭导致升级失败），需读写分离goroutine、显式设置读写deadline、校验Origin白名单，并启用ping/pong心跳机制。
gorilla/websocket 是当前 Go 生态中事实标准的 WebSocket 实现，没有“框架”层抽象——它本身就是一个轻量、直接操作连接的库。想实现高性能通信，关键不在选“框架”，而在正确使用 gorilla/websocket 的原语并规避常见并发陷阱。
为什么不能用 http.HandleFunc 直接注册 WebSocket handler
因为 http.HandleFunc 返回后，底层 HTTP 连接会被 net/http 自动关闭，而 WebSocket 升级需要接管 TCP 连接生命周期。此时调用 upgrader.Upgrade() 会失败，浏览器报 ERR_CONNECTION_CLOSED，服务端日志出现 websocket: bad handshake。
必须确保：
-
upgrader.Upgrade(w, r, nil)是 handler 中第一个且唯一写响应的操作； - Upgrade 前不能对
w调用任何Write或WriteHeader（包括空格、换行）； - Handler 必须挂载到
http.ServeMux或直接传给http.Server，而非被中间件意外拦截或提前结束。
读写必须分离 goroutine，否则会 panic
*websocket.Conn 不是线程安全的：并发调用 WriteMessage() 会触发 concurrent write to connection panic；连续在同一个 goroutine 中读完又立刻写，可能因阻塞导致其他连接饥饿。
立即学习“go语言免费学习笔记（深入）”；
正确模式是：
- 一个 goroutine 专责
conn.ReadMessage()，收到消息后转发到业务 channel 或广播队列； - 另一个 goroutine 专责从
send chan []byte拉取消息，调用conn.WriteMessage()； - 断开时记得
close(send)，避免 writer goroutine 永久阻塞； - 不要用
conn.Write()或手动拼帧——ReadMessage()才能正确处理掩码、碎片、opcode。
CheckOrigin 默认拒绝所有跨域请求
upgrader.CheckOrigin 默认实现返回 false，任何非同源请求都会被拒绝，前端控制台显示 WebSocket connection to 'ws://...' failed，但服务端无明显错误日志。
开发阶段可临时设为：
CheckOrigin: func(r *http.Request) bool { return true }但上线前必须替换为白名单校验，例如：
CheckOrigin: func(r *http.Request) bool {
origin := r.Header.Get("Origin")
return origin == "https://myapp.com" || origin == "https://admin.myapp.com"
}否则存在 CSRF 和开放重定向风险。
连接静默断开时 ReadMessage 不报错，怎么办
WiFi 切换、NAT 超时等场景下，TCP 连接可能已断，但 conn.ReadMessage() 仍阻塞不返回——这不是 bug，是 TCP 特性。靠 time.After 包裹读操作无效，因为底层 read 系统调用未超时。
必须显式设置：
-
conn.SetReadDeadline(time.Now().Add(30 * time.Second))，每次读前更新； - 捕获
net.ErrTimeout或net.OpError并主动关闭连接； - 配合心跳（ping/pong）：启用
upgrader.EnablePingPong = true，并在conn.SetPongHandler中重置读 deadline； - 注意：服务端无需发 ping，
gorilla/websocket会自动响应客户端 ping 并触发 pong handler。
真正卡住性能的从来不是协议本身，而是连接没及时清理、读写没分离、deadline 没设、origin 校验没关——这些点漏掉任意一个，都可能让服务在几十个连接时就变得不可靠。
