Qt的QWebSocket和QWebSocketServer支持跨平台运行（Windows/macOS/Linux），但实际通信成败取决于网络可达性、协议一致性及连接生命周期管理，常见问题包括构建配置遗漏websockets模块、端口冲突、URL协议不匹配、SSL模式混用、防火墙拦截及多线程访问未加锁等。
Qt 的 QWebSocket 和 QWebSocketServer 能直接跑在 Windows/macOS/Linux 上，只要 Qt 版本 ≥ 5.3，编译时链接了 websockets 模块，跨平台通信本身没有障碍——真正卡住人的，是网络可达性、协议一致性、以及连接生命周期管理。
pro 或 CMake 配置漏掉 websockets 模块，程序根本连不上
这是最常发生的“连不上”原因：代码写得再对，构建系统没把 WebSocket 库链接进去，运行时 QWebSocket 会静默失败，QWebSocketServer::listen() 返回 false，但很多人没检查错误字符串。
-
QT += core gui websockets（qmake 项目，必须加在 .pro 文件里，不能只写core gui） - CMake 项目要写两行：
find_package(Qt6 REQUIRED COMPONENTS WebSockets)+target_link_libraries(your_target PRIVATE Qt6::WebSockets) - Qt 5.9 及更早版本存在握手兼容性问题，实测
QWebSocketServer::NonSecureMode在 Qt 5.9 上可能和 Chrome 90+ 握手失败，建议升到 Qt 5.12 或更高
服务端 listen() 失败却没报错，其实是端口被占或权限不足
server->listen(QHostAddress::Any, 8080) 返回 false 时，别急着改代码，先看 server->errorString()。常见真实原因是：
WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。
- 端口已被其他进程占用（比如另一个 Qt 实例、Node.js 服务、甚至 Docker 容器）
- Linux/macOS 下尝试绑定 1024 以下端口（如 80），但没用 root 权限启动
- Windows 防火墙或杀软拦截了监听行为（尤其在公司内网环境）
-
QHostAddress::Any在某些虚拟机/容器网络中不可靠，可临时换成具体 IP 如QHostAddress("127.0.0.1")排查
客户端 connectToUrl() 后无响应，大概率是 URL 格式或跨域问题
Qt 客户端用 m_websocket.open(QUrl("ws://127.0.0.1:8080")) 连接时，如果服务端跑在本地但客户端 UI 是从 IDE 启动的，需确认：
- URL 协议必须匹配服务端模式：
ws://对应QWebSocketServer::NonSecureMode，wss://必须配SecureMode+ SSL 证书，混用必失败 - 地址不能写
localhost—— 某些 Qt 版本 DNS 解析有 bug，统一用127.0.0.1 - 若服务端绑的是
QHostAddress::Any，但客户端运行在另一台机器（比如手机连开发机），要确保开发机防火墙放行对应端口，且服务端没绑定成127.0.0.1 - Qt 客户端不处理 HTTP 跨域（CORS），那是浏览器的事；但如果你用 Qt 做服务端、网页做客户端，浏览器会校验服务端响应头里的
Access-Control-Allow-Origin，Qt 默认不加，得手动 setHeader
消息收发正常但断开后 crash，多半是 client 对象被重复 delete 或跨线程访问
典型场景：客户端断开触发 disconnected() 信号，槽函数里调用 client->deleteLater()，但同时又在别的地方（比如定时器、广播逻辑）遍历 m_clients 列表并调用了 client->sendTextMessage()。
- 务必在
disconnected槽里先m_clients.removeAll(client)，再client->deleteLater() - 所有对
m_clients的读写操作，如果涉及多线程（比如用QTimer定时广播），必须加锁或改用信号槽跨线程传递数据 - 不要在
textMessageReceived槽里直接处理耗时逻辑（如解析 JSON + 写文件），容易阻塞事件循环，导致后续 ping/pong 超时断连
跨平台能通只是起点，真正的坑藏在连接存活、异常恢复、以及多客户端状态同步的细节里。尤其是嵌入式或工业场景，设备频繁上下线时，nextPendingConnection() 返回空指针、peerAddress() 在断连后仍可读但内容已失效，这些边界情况比协议本身更需要小心验证。
