WebSocket连接必须用gorilla/websocket，因标准库不支持帧解析、心跳等核心功能；正确升级需upgrader.Upgrade()，并配置Origin校验、Ping/Pong及Nginx代理头。
WebSocket连接必须用gorilla/websocket，标准库不支持
Go 标准库没有 WebSocket 实现，net/http 只能处理 HTTP 协议升级请求，但不提供 WebSocket 帧解析、心跳、消息读写等能力。强行自己实现协议极易出错，且无法兼容主流客户端（如浏览器 WebSocket API）。实际项目中必须使用成熟第三方库，gorilla/websocket 是事实标准，维护活跃、文档清晰、性能稳定。
安装方式：
go get -u github.com/gorilla/websocket
常见错误现象：
– 用 http.ResponseWriter 直接写入 101 Switching Protocols 后尝试手写帧，结果客户端报 Invalid frame header
– 误以为 http.ServeMux 能自动处理 WebSocket 升级，导致返回 404 或 500
- WebSocket 升级必须由 handler 显式调用
upgrader.Upgrade() - 升级后原
http.ResponseWriter和*http.Request不再可用，后续通信全部走*websocket.Conn - 不要在升级前写任何响应体（包括空格、换行），否则会触发
http: response.WriteHeader on hijacked connection
如何正确升级 HTTP 连接为 WebSocket
关键在于 websocket.Upgrader 的配置和调用时机。它负责校验 Upgrade 请求头、设置响应状态码、完成协议切换，并返回可读写的 *websocket.Conn。
立即学习“go语言免费学习笔记（深入）”；
典型 handler 示例：
var upgrader = websocket.Upgrader{
CheckOrigin: func(r *http.Request) bool {
return true // 生产环境应校验 Origin
},
}
func wsHandler(w http.ResponseWriter, r *http.Request) {
conn, err := upgrader.Upgrade(w, r, nil)
if err != nil {
log.Println("Upgrade error:", err)
return
}
defer conn.Close()
for {
_, msg, err := conn.ReadMessage()
if err != nil {
log.Println("Read error:", err)
break
}
if err := conn.WriteMessage(websocket.TextMessage, msg); err != nil {
log.Println("Write error:", err)
break
}
}
}
-
CheckOrigin默认拒绝所有跨域请求，开发时设为return true，生产务必改为白名单校验 - 升级成功后，
conn会接管底层 TCP 连接，此时不能再调用w.Write()或w.Header().Set() - 读写操作默认阻塞，超时需通过
SetReadDeadline/SetWriteDeadline控制 - 浏览器发起的 WebSocket 请求，
Request.Header.Get("Origin")可用于来源判断
消息读写必须区分文本/二进制类型，且注意缓冲区管理
conn.ReadMessage() 返回的 messageType 是 websocket.TextMessage 或 websocket.BinaryMessage，不能忽略。浏览器发送的字符串消息默认是 Text，ArrayBuffer 则是 Binary；服务端若用 WriteMessage(websocket.TextMessage, []byte{...}) 写二进制数据，客户端 onmessage 会收到乱码或解析失败。
另外，ReadMessage 每次都会分配新切片，大消息频繁调用易引发 GC 压力；WriteMessage 内部会拷贝数据，直接传入长生命周期的字节切片可能造成意外修改。
- 接收时检查
messageType，按需处理：if messageType == websocket.TextMessage { ... } - 发送 JSON 数据优先用
conn.WriteJSON(v interface{})，它自动处理序列化和类型标记 - 对高频小消息，可复用
bufio.Reader+conn.UnderlyingConn()（不推荐，破坏抽象）；更稳妥的是启用conn.SetReadLimit()防止内存耗尽 - 关闭连接前务必调用
conn.Close()，否则连接会卡在 TIME_WAIT，服务端资源泄漏
生产环境必须处理 Ping/Pong 和连接超时
浏览器和多数代理（如 Nginx）会在空闲 60 秒后主动断开 WebSocket 连接。若服务端不主动发 Ping，也不响应客户端 Pong，连接会静默失效，用户无感知。gorilla 默认不自动处理心跳，必须手动注册回调。
正确做法：
upgrader = websocket.Upgrader{ /* ... */ }
upgrader.SetPingHandler(func(appData string) error {
return conn.WriteMessage(websocket.PongMessage, []byte(appData))
})
upgrader.SetPongHandler(func(appData string) error {
conn.SetReadDeadline(time.Now().Add(pongWait))
return nil
})
// 在读消息循环前设置
conn.SetPingInterval(pingPeriod)
conn.SetReadDeadline(time.Now().Add(pongWait))
-
pingPeriod建议设为 25 秒，pongWait设为 30 秒，留出网络抖动余量 -
SetPingInterval启动后台 goroutine 自动发 Ping，无需手动轮询 - 每次收到 Pong 后重置读超时，防止因网络延迟误判连接断开
- Nginx 配置需显式开启 WebSocket 支持：
proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection "upgrade";
连接生命周期管理比看起来复杂得多：从协议升级校验、消息类型匹配、到心跳保活、反向代理适配，每一步漏掉都可能导致线上连接大量异常断开。尤其注意 Upgrader 配置不是一次写完就一劳永逸——Origin 校验、超时设置、错误日志粒度，都得随部署环境动态调整。
