Gin原生不支持WebSocket，因其仅为HTTP路由框架，不处理Upgrade握手与101响应；必须用gorilla/websocket.Upgrader手动升级，并在升级后立即脱离gin.Context，禁用所有c.*方法，否则会触发hijacked connection错误或连接秒断。
为什么 Gin 原生不支持 WebSocket？
Gin 是一个 HTTP 路由框架，它本身不处理 WebSocket 协议升级（即 Upgrade 请求头和 101 Switching Protocols 响应），所有 WebSocket 逻辑必须手动接管。你不能直接在 GET 路由里调用 c.WebSocket()——Gin 根本没有这个方法。
真正能用的方案是：用标准库 net/http 的 Upgrader 处理握手，再把连接交给 Gin 的路由上下文做初始鉴权或参数提取，之后脱离 Gin 管理。
- 常见错误现象：
http: response.WriteHeader on hijacked connection或连接立即关闭 - 根本原因：在已
Hijack()的连接上继续调用c.JSON()、c.String()等 Gin 响应方法 - 正确做法：一旦完成升级，就不要再碰
*gin.Context，改用原始net.Conn或封装后的*websocket.Conn
如何安全地把 WebSocket 升级接入 Gin 路由？
关键是在 Gin handler 内部用 websocket.Upgrader 升级，但必须绕过 Gin 的响应生命周期。最稳妥的方式是：先用 Gin 解析 URL 参数、校验 token、记录日志，再调用 upgrader.Upgrade() 并立即 return。
var upgrader = websocket.Upgrader{
CheckOrigin: func(r *http.Request) bool {
return true // 生产需严格校验 Origin
},
}
<p>func chatHandler(c *gin.Context) {
conn, err := upgrader.Upgrade(c.Writer, c.Request, nil)
if err != nil {
return // 不要 c.AbortWithError()，那会写响应头
}
defer conn.Close()</p><pre class="brush:php;toolbar:false;">// 此处开始纯 WebSocket 逻辑，与 Gin 无关
handleConnection(conn)}
立即学习“go语言免费学习笔记（深入）”；
- 必须传
c.Writer和c.Request，不能传c.Writer.ResponseWriter()（类型不匹配） -
CheckOrigin默认拒绝非同源请求，开发时可临时放行，但上线前务必改为白名单校验 - 升级后禁止再调用任何
c.*()方法，包括c.Next()、c.Set()
群发消息时如何避免并发 panic 和连接泄漏？
WebSocket 连接是长连接，每个 *websocket.Conn 都需要独立 goroutine 读/写。群发本质是遍历所有活跃连接并 WriteMessage()，但若某连接已断开或写阻塞，直接调用会 panic 或卡死整个广播循环。
必须用带超时和 recover 的写法，并维护连接池（如 map[string]*websocket.Conn + sync.RWMutex）：
var (
clients = make(map[string]*websocket.Conn)
mu sync.RWMutex
)
<p>func broadcast(msg []byte) {
mu.RLock()
defer mu.RUnlock()
for _, conn := range clients {
// 设置写超时，防止一个卡住拖垮全部
conn.SetWriteDeadline(time.Now().Add(5 * time.Second))
if err := conn.WriteMessage(websocket.TextMessage, msg); err != nil {
log.Printf("write error: %v", err)
// 这里应触发清理逻辑，比如标记待删除
}
}
}- 读消息必须单独起 goroutine，且要监听
conn.ReadMessage()返回的io.EOF或websocket.CloseMessage来主动 close - 不要在广播循环里
delete(clients, key)，否则可能引发 concurrent map iteration panic；应先收集待删 key，再另起锁写操作 - 客户端断连时，
ReadMessage()会返回错误，这是唯一可靠判断连接死亡的时机
为什么不能直接用 gin-contrib/websocket？
gin-contrib/websocket 是社区封装，它内部仍基于 websocket.Upgrader，但隐藏了底层细节，导致两个硬伤：
- 无法自定义
CheckOrigin以外的升级逻辑（如携带 JWT 解析用户 ID） - 广播时缺乏对单个连接异常的隔离能力，一次
WriteMessage()失败可能中断整个 for 循环 - 它的
c.WebSocket()实际是语法糖，底层仍是 Hijack + Upgrade，没解决 Gin 上下文残留问题
真实项目中，多几行手动升级代码换来的是可控性——比如你在升级前可以查数据库验证用户权限，或从 c.Param("room") 提取房间号，这些都比依赖黑盒封装更稳。
群发逻辑越简单，越容易出错；真正的难点从来不是“怎么发”，而是“发失败了怎么办”和“谁该收到”。连接管理永远比协议本身更消耗心力。
