必须用gorilla/websocket，因其完整实现RFC 6455：解析帧、处理掩码、管理心跳、校验控制帧；标准库net/http仅支持Upgrade握手，手动实现易崩溃。
为什么必须用 gorilla/websocket 而不是标准库
Go 标准库 net/http 只能完成 WebSocket 协议的 HTTP 握手（即 Upgrade 请求），但**不解析帧、不处理掩码、不管理心跳、不校验控制帧**。硬用标准库写，等于手动实现 RFC 6455 的二进制协议解析——极易在连接中断、浏览器重连、长消息分片等场景崩溃。
- 常见现象：
websocket: bad write message type或read tcp: i/o timeout频发，且无法定位是协议层还是业务层问题 - 生产环境必须依赖成熟封装：
gorilla/websocket提供SetReadDeadline、WriteJSON、自动 PING/PONG 等关键能力 - 它还默认禁用并发写保护，这反而是好事——逼你主动设计写入串行化逻辑，避免
concurrent write to websocket connectionpanic
upgrader.Upgrade() 报错 http: response.WriteHeader called multiple times 怎么办
这个 panic 几乎必现于新手代码，根本原因是：WebSocket 升级本身是一次完整的 HTTP 响应（含状态码 101 和响应头），upgrader.Upgrade() 内部已调用过 w.WriteHeader()；若你在它前后又调用了 http.Error()、w.Write() 或任何其他写响应操作，就会触发重复写头。
- 正确姿势：升级前不做任何
w.Write，升级失败后直接return，不要试图渲染错误页 - 升级成功后，
*http.ResponseWriter和原始*http.Request**立即失效**，后续通信全部走返回的*websocket.Conn - 开发阶段可设
CheckOrigin: func(r *http.Request) bool { return true }，但上线前必须替换为白名单域名校验
func chatHandler(w http.ResponseWriter, r *http.Request) {
conn, err := upgrader.Upgrade(w, r, nil)
if err !
= nil {
return // ❌ 不要 http.Error(w, err.Error(), 500)
}
defer conn.Close()
// ✅ 后续只操作 conn.ReadMessage() / conn.WriteMessage()
}
如何安全广播消息而不 panic concurrent write
*websocket.Conn 的读写方法**不是 goroutine 安全的**。聊天室里，“系统通知”“群聊消息”“私聊回执”可能同时触发对同一连接的写操作，直接遍历 clients 并调用 conn.WriteMessage() 必然 panic。
- 解法：每个客户端配一个专属
send chan []byte，所有写请求先入 channel，再由单个writePumpgoroutine 串行消费 - 广播时只往每个 client 的
sendchannel 发消息，不直接调用WriteMessage - channel 缓冲区建议设为 16～32，满时丢弃旧消息（用
select { case c.send ），防内存泄漏
type Client struct {
conn *websocket.Conn
send chan []byte
}
func (c *Client) writePump() {
defer c.conn.Close()
for {
select {
case message, ok := <-c.send:
if !ok {
return
}
if err := c.conn.WriteMessage(websocket.TextMessage, message); err != nil {
return
}
}
}
}
前端用原生 WebSocket 接入时要注意什么
浏览器原生支持足够好，无需额外库，但有三个实际坑点：
- 连接地址必须用
ws://（本地开发）或wss://（线上），不能写成http://—— 否则new WebSocket()直接抛SecurityError -
onmessage收到的是event.data字符串，若后端发的是 JSON，需手动JSON.parse(event.data) - 断开后别傻等重连：加简单重试逻辑，比如
onclose触发后setTimeout(() => ws = new WebSocket(...), 3000)
const ws = new WebSocket("ws://localhost:8080/ws");
ws.onmessage = function(event) {
const data = JSON.parse(event.data); // 后端 send JSON
console.log(data.from + ": " + data.content);
};
ws.onclose = function() {
setTimeout(() => {
ws = new WebSocket("ws://localhost:8080/ws");
}, 3000);
};真正的难点不在连接建立，而在连接生命周期管理：谁负责清理失效连接？广播时某个 client 写失败，是否影响其他 client？超时连接怎么识别？这些细节不显眼，但决定服务能不能跑过一晚上。
