WebSocket连接失败首要排查DNS解析，如“no such host”错误；连接后断开需处理CloseMessage并启用ping/pong心跳；Upgrader拒绝连接多因Origin或Cookie校验；并发写必须单goroutine串行化，禁用Mutex而用channel。
WebSocket连接失败时 net.Dial 报 dial tcp: lookup example.com: no such host
域名解析失败是建立 WebSocket 连接的第一道关卡，net.Dial（或 websocket.Dial 底层调用）会直接返回该错误，根本不会走到协议升级阶段。
常见于：DNS 配置错误、测试环境 hosts 未配、K8s Service 名称拼错、CI 环境无 DNS 权限。
- 先用
dig example.com或nslookup example.com确认 DNS 可达，别急着改 Go 代码 - Go 中不要硬写域名，用
url.URL解析并检查u.Host是否为空；若从配置读取，加一层net.ParseIP(u.Host)快速判别是 IP 还是域名 - 若必须容忍临时 DNS 不可达，可包装
websocket.DefaultDialer的NetDialContext字段，加带超时和重试的自定义拨号器，但注意：重试逻辑不能放在Dial内部——它只负责单次连接，重连应由上层控制
连接已建立但收发时突然断开，ReadMessage 返回 websocket.CloseMessage 或 io.EOF
这是长连接最典型的“假活”场景：TCP 连接没被操作系统 kill，但对端已静默关闭，或中间 NAT 超时踢出连接。此时 ReadMessage 不报错，而是返回 websocket.CloseMessage 类型帧；再往后调用则大概率触发 io.EOF 或 use of closed network connection。
- 永远在
for循环中调用ReadMessage，并在switch分支里显式处理websocket.CloseMessage：立即调用WriteMessage(websocket.CloseMessage, websocket.FormatCloseMessage(websocket.CloseGoingAway, ""))响应，然后break - 不要依赖
conn.SetReadDeadline单纯防卡死——它只管读操作超时，不感知连接是否真实存活；得配合心跳（ping/pong）：启用conn.SetPingHandler并定期发WriteMessage(websocket.PingMessage, nil) - 注意
net.Conn层的SetKeepAlive对 WebSocket 无效，底层 TCP keepalive 无法穿透 HTTP 升级后的 WebSocket 帧，必须走协议层心跳
websocket.Upgrader 拒绝连接，日志出现 http: named cookie not present 或 origin check failed
服务端拒绝升级请求，多数不是 WebSocket 协议问题，而是 Upgrader 的安全校验拦截了请求。默认配置下，它会检查 Origin 头、Cookie、甚至 TLS 状态。
立即学习“go语言免费学习笔记（深入）”；
- 开发期快速绕过：设置
CheckOrigin: func(r *http.Request) bool { return true }，但上线前必须删掉——这等于开放任意跨域，前端可能被钓鱼页面复用连接 - 生产环境 Origin 校验要严格：提取
r.Header.Get("Origin")，用url.Parse解析后比对 scheme+host，忽略 path 和 query；别用字符串strings.Contains匹配，防伪造 - 如果依赖 Cookie 鉴权（如 session），确保前端请求带
credentials: 'include'，且响应头有Access-Control-Allow-Credentials: true；否则浏览器根本不会发 Cookie，Upgrader查不到就拒掉
并发读写 panic：concurrent write to websocket connection
WebSocket 连接对象不是 goroutine 安全的——WriteMessage、WriteJSON、Close 等写方法不能被多个 goroutine 同时调用，否则直接 panic。
- 最稳做法：每个连接绑定一个专属的写 goroutine，所有写请求通过
chan []byte或chan interface{}投递到该 goroutine，它顺序消费并调用WriteMessage - 别用
sync.Mutex包裹写操作——锁住时间不可控，一旦某个WriteMessage卡住（比如对方网络差），整个连接写就阻塞，其他消息积压 - 读写分离后，
Close也要走写 channel（发一个closeMsg），由写 goroutine 统一执行，避免读 goroutine 收到 EOF 后还试图写
心跳、业务消息、关闭通知，都得走同一条写通道；看似多一层转发，实则避开了最难调试的竞态点——很多人卡在这里两周，最后发现只是忘了加 channel。
