qt c++实现websocket客户端需正确初始化qwebsocket、绑定信号（推荐qt::queuedconnection）、显式链接websockets模块（qt+=websockets），并确保url协议与服务端模式匹配（ws://对应nonsecuremode，wss://对应securemode），否则运行时崩溃或静默失败。
Qt C++ 实现 WebSocket 客户端，只要正确初始化 QWebSocket、处理好连接生命周期和信号绑定，就能稳定跨平台收发消息；不依赖第三方库，但必须链接 websockets 模块，否则编译通过、运行时崩溃。
确保 QT += websockets 已写入 .pro 文件
这是最容易被跳过的一步 —— Qt Creator 有时会自动补全 core 和 widgets，但不会加 websockets。没这行，QWebSocket 类型能识别（头文件可包含），但链接阶段找不到符号，运行时报 QMetaObject::connectSlotsByName: No matching signal for on_webSocket_connected() 或直接段错误。
-
QT += core widgets network websockets必须显式写出，不能只靠“自动检测” - VS + Qt 插件环境下，还需在项目属性 → Qt Project Settings → Qt Modules 中勾选
WebSockets - Qt 6.6+ 中模块名仍是
websockets（不是websocket或qt6_websockets）
连接 URL 格式与协议兼容性必须匹配
客户端连不上，80% 是 URL 写错。Qt 的 QWebSocket 对 ws:// 和 wss:// 处理逻辑不同，且不自动降级。
- 服务端用
QWebSocketServer启动在非加密模式（QWebSocketServer::NonSecureMode），客户端必须用ws://127.0.0.1:8080，写成wss://会静默失败，errorString()返回空 - 若服务端启用了 TLS（
QWebSocketServer::SecureMode），客户端需调用ignoreSslErrors()（仅调试用）或配置QSslConfiguration，否则连接卡在Connecting状态 - URL 中不能带路径参数如
ws://localhost:8080/chat—— Qt 默认不校验 path，但某些 Nginx 反代或自定义路由服务会拒绝，建议先用根路径测试
消息接收必须用 queued connection 绑定信号
QWebSocket::textMessageReceived 信号默认是 auto connection，在多线程环境（比如你在 worker thread 创建 QWebSocket）下，若直接用 connect(ws, &QWebSocket::textMessageReceived, this, &MyClass::onMessage)，槽函数可能在错误线程执行，导致 UI 更新崩溃或消息丢失。
- 显式指定
Qt::QueuedConnection：connect(ws, &QWebSocket::textMessageReceived, this, &MyClass::onMessage, Qt::QueuedConnection) - 确保接收槽函数
onMessage是public slots:声明，且参数为const QString & - 如果需要在子线程中解析 JSON 或做耗时处理，不要在
onMessage里直接阻塞，应 emit 自定义信号转发到工作线程
sendTextMessage() 失败时别只看返回值
QWebSocket::sendTextMessage(const QString &) 返回 qint64，表面看是字节数，但实际它只表示“是否已进入发送队列”，不保证送达。真正失败往往发生在底层 socket 关闭后还调用它 —— 此时返回 -1，但更关键的是后续会触发 errorOccurred 信号。
- 务必 connect
&QWebSocket::errorOccurred，并在槽中检查ws->errorString() - 常见错误码：
QAbstractSocket::RemoteHostClosedError（对方断开）、QAbstractSocket::NetworkError（网络中断）、QWebSocketProtocol::CloseCodeAbnormalDisconnection（协议层异常） - 发送前用
ws->state() == QAbstractSocket::ConnectedState判断，但注意：该状态可能滞后于真实网络状态，建议配合心跳帧（ping/pong）保活
跨平台真正难的不是代码写法，而是 Windows 上防火墙静默拦截、macOS 的 ATS 限制、Linux 下 SELinux 策略 —— 这些不会报 Qt 错误，只会让 connected() 信号根本不触发。上线前务必在目标系统上用 telnet host port 或 curl -i http://host:port 先验证基础连通性。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
