用libwebsockets搭建轻量WebSocket服务端最实际，它封装了accept、HTTP升级、帧编解码、ping/pong及连接管理，开发者只需在C风格回调中写业务逻辑；避免裸写TCP+协议解析或误用Boost.Beast导致的内存泄漏、丢帧与卡死问题。
用 libwebsockets 搭建轻量 WebSocket 服务端最实际
直接上手写裸 TCP + HTTP 升级 + 帧解析，99% 的项目不值得。C++ 生态里，libwebsockets 是目前最稳定、零依赖、纯 C 实现（但 C++ 项目调用毫无压力）的方案。它把 accept、HTTP Upgrade 处理、帧解包/封包、ping/pong、连接生命周期全包了，你只管在回调里写业务逻辑。
常见错误是试图用 Boost.Beast 从头实现——它确实功能强，但需要手动管理连接状态、超时、缓冲区、TLS 握手时机，一不留神就内存泄漏或丢帧；而 libwebsockets 的事件驱动模型天然防这类问题。
- 编译时加
-DLWS_WITH_HTTP2=OFF -DLWS_WITH_SSL=OFF可去掉 OpenSSL 依赖（纯 ws 场景） - 所有回调函数必须是 C 风格函数指针，C++ 类成员函数需用
static包装或传void*用户数据 - 每个连接的私有数据（如用户 ID、会话状态）通过
lws_set_wsi_user存，用lws_get_wsi_user取，别存在局部变量里
libwebsockets 回调里怎么发消息不崩
不能直接在 CALLBACK_WS_SERVER_MSG 或 CALLBACK_HTTP 里调用 lws_write ——此时可能不在服务线程上下文，或缓冲区未就绪，大概率返回 -1 并触发断连。正确做法是标记“待发送”，由 CALLBACK_SERVER_WRITEABLE 统一处理。
典型场景：收到 JSON 指令后要广播给其他客户端。这时得先解析、存到连接私有结构体里，再调用 lws_callback_on_writable 触发可写事件。
立即学习“C++免费学习笔记（深入）”；
-
lws_write返回值必须检查：等于请求长度才成功；小于则说明缓冲区满，需等下次WRITABLE；负数表示错误（如连接已断） - 发二进制帧用
LWS_WRITE_BINARY，文本用LWS_WRITE_TEXT，混用会导致客户端解析失败 - 不要在回调里做耗时操作（如查数据库），应投递到工作线程，再用
lws_cancel_service唤醒主线程写回
为什么 Boost.Beast 的 websocket::stream 容易卡死
根本原因是它的异步模型要求严格遵循“发起 async_op → 在 handler 里再发下一个 async_op”链式调用。一旦漏掉一次 async_read 或 async_write，连接就静默挂起——没有超时、没有报错，只是不再收发。
典型坑：async_write 的 handler 里没立刻调用 async_read，或者用了 boost::asio::post 把读操作延后，导致底层 socket 接收缓冲区填满后对端被阻塞。
- 务必用
stream.binary(true)显式设二进制模式，否则某些客户端（如浏览器 JSWebSocket）发二进制会失败 -
stream.set_option(websocket::stream_base::timeout::suggested(manual))必须设，否则空闲连接永不关闭 - 用
strand包裹所有 stream 操作，否则多线程调用read/write会引发未定义行为
调试连接建立失败，先看 Upgrade 头和状态码
浏览器控制台报 WebSocket connection to 'ws://...' failed，90% 不是代码问题，而是 HTTP Upgrade 流程卡在第一步。用 curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Key: xxx" http://localhost:8080 手动模拟，观察响应头。
关键检查点：
- 响应必须含
HTTP/1.1 101 Switching Protocols，不是 200 或 400 - 必须有
Upgrade: websocket和Connection: Upgrade -
Sec-WebSocket-Accept值是否为base64(sha1(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"))，少一个字符都不行 - 若用反向代理（Nginx），确认已配
proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade等三行
帧级问题（比如 ping 超时断连）往往藏在日志级别不够深的地方——libwebsockets 编译时加 -DCMAKE_BUILD_TYPE=Debug，运行时设 LWS_LOG_LEVEL=7 才能看到握手细节；Boost.Beast 则需启用 BOOST_ASIO_ENABLE_HANDLER_TRACKING。
