根本原因是Iris默认禁用http.Hijacker，而gorilla/websocket升级需接管TCP连接；必须改用app.Run()并传入iris.WithStdLogger等参数，且版本≥v12.2.0。
panic: websocket: response does not implement http.Hijacker
这是 Iris 中 WebSocket 启动失败最典型的错误，根本原因不是代码写错了，而是 HTTP Server 没开劫持能力。Iris 默认禁用 http.Hijacker，而 gorilla/websocket 底层必须接管 TCP 连接才能完成 WebSocket 升级。
实操建议：
- 别用
app.Listen()—— 它不支持 Hijack，必须改用app.Run() - 确保启动参数包含
iris.WithStdLogger和iris.WithoutInterruptHandler（旧版iris.WithoutBodyConsumptionOnUnmarshal无效） - Iris 版本必须 ≥ v12.2.0；低于该版本的
websocket.Config.Endpoint字段已废弃，硬写会静默失效
go get github.com/kataras/iris/v12 报 invalid version 或静默失败
本质是 Go module 解析失败：Iris v12+ 强制要求带 /v12 后缀和语义化版本号，且依赖 GOPROXY 和 GO111MODULE 环境变量稳定生效。
实操建议：
- 先在项目根目录执行
go mod init myapp，确保go.mod第一行是module myapp，不是module .或空 - 安装命令必须带版本，例如：
go get github.com/kataras/iris/v12@v12.2.11；@latest可用于开发，但上线前务必锁死小版本 - Windows 用户请用
set GO111MODULE=on && set GOPROXY=https://mirrors.aliyun.com/goproxy && go get ...，避免环境变量残留导致回退到 GOPATH 模式 - 若仍报
unrecognized import path "golang.org/x/..."，说明代理未覆盖 x repos，可临时补全：go get golang.org/x/net@latest
WebSocket 握手 404 或 OnConnection 不触发
路径不一致是高频原因。Iris 的 websocket.New() 返回的是标准 http.Handler，它不自动注册路由，必须手动挂载，且 Config.Path 和路由路径必须字面量完全相等。
实操建议：
- 不要用
app.Adapt(ws)—— v12+ 已标记为 deprecated，且不生效 - 必须显式绑定：
app.Any("/ws", ws.Handler())（推荐Any，因部分 CDN 会重写 method） -
websocket.Config{Path: "/ws"}和上面的"/ws"必须一模一样，多一个斜杠、大小写差异或前导空格都会导致握手 404 - 检查中间件是否提前终止了请求（如 JWT 验证中间件对
/ws路径做了拦截）
广播消息漏连接或连接卡死
根本问题在于误把连接快照当实时集合用。ws.GetConnectionsByRoom("/room") 返回的是调用瞬间的切片副本，新进连接不会自动加入，遍历时还可能因阻塞操作（如同步 DB 查询）拖垮整个 goroutine。
实操建议：
- 所有耗时操作（DB、HTTP、文件 IO）必须丢进
go func() { ... }()，禁止在OnConnection或OnMessage回调里同步执行 - 广播逻辑应基于房间的实时连接池，而非每次调用
GetConnectionsByRoom；可用ws.Broadcast(...)或自行维护sync.Map记录活跃连接 - 心跳必须由服务端主动发（如
conn.WriteMessage(websocket.PingMessage, nil)），不能只依赖客户端 ping，否则 NAT 超时断连无法感知
