QTcpServer与C#客户端WebSocket无法正常建立连接问题排查

核心问题 #

要在本地localhost环境实现基于WebSocket协议的QTcpServer与C#客户端连接，但出现以下异常：

• QTcpServer能和telnet正常交互（连接确认+双向传数据），但和C#客户端、Chrome WebSocket测试插件等标准WebSocket客户端无法建立有效连接
• C#客户端对接C#服务端或第三方WebSocket服务端完全正常，排除客户端本身的WebSocket实现问题

抓包（WireShark）发现的关键差异 #

• 和telnet连接：走标准HTTP握手流程，后续数据交互正常
• 和标准WebSocket客户端连接：
  • 客户端发握手请求 → 服务端响应后，客户端重复发送握手请求
  • 客户端状态卡在Connecting，服务端却认为连接已建立，双方无法传数据

排查重点（按优先级排序） #

1. QTcpServer的WebSocket握手逻辑错误 #

WebSocket握手不是普通HTTP连接，必须严格遵循协议规范，这是最可能的问题：

• Sec-WebSocket-Accept计算错误：
  客户端发的Sec-WebSocket-Key必须拼接固定字符串258EAFA5-E914-47DA-95CA-C5AB0DC85B11，做SHA-1哈希后Base64编码，返回给客户端。如果计算错了，客户端会判定握手失败，重发请求。
• 响应头不完整/格式错误：
  必须返回101 Switching Protocols状态码，同时包含Upgrade: websocket和Connection: Upgrade头，缺一不可。少了任何一个，客户端都不会切换到WebSocket模式。
• 响应未正确结束：
  HTTP响应头必须以\r\n\r\n结尾（空行），如果服务端没发送这个分隔符，客户端会认为响应还没完成，一直等待，最后超时重发请求。

2. QTcpServer的响应发送方式问题 #

• 检查是否分段发送了握手响应，导致客户端无法识别完整的握手包
• 确认是否在发送响应后，没有切换到WebSocket帧格式处理，还是按普通文本接收/发送数据

3. 协议版本或扩展字段不兼容 #

• 检查服务端是否支持客户端发送的Sec-WebSocket-Version（主流是13），版本不匹配会直接导致握手失败
• 如果客户端发送了Sec-WebSocket-Extensions字段，服务端要么协商支持，要么明确忽略，不能返回不兼容的扩展配置

快速验证方法 #

• 用wscat命令行工具连接QTcpServer，它会输出详细的握手错误信息，比如Error: Invalid WebSocket frame: invalid status code
• 把QTcpServer的握手响应和C#服务端的响应做对比，逐字段检查差异
• 在QTcpServer里加日志，打印收到的所有请求头和发送的响应内容，直接定位不匹配的地方

内容的提问来源于stack exchange，提问作者anjelomerte