C++后端实时推送实战：Boost.Beast WebSocket从原理到Demo

简介：面向 C++ 开发者的 WebSocket 可直接编译 Demo，集成 websocketpp、Boost 与 jsoncpp 三套库，解决 C++ 端 WebSocket 客户端/服务器快速上手与环境搭建难题。项目以 CMake 组织构建，涵盖握手、收发数据、JSON 序列化等典型流程，适合正在学习网络编程或准备在项目中引入实时通信的开发者参考。

压缩包共 14553 个文件，约 154.62MB，其中绝大多数为 hpp、ipp、h 头文件，属于 Boost 与 websocketpp 的完整依赖源码；另含少量 cpp、sample 等示例文件。包内依赖齐备，按说明执行 CMake/make 即可完成编译，免去手动配置第三方库的麻烦。已有 1077 人学习/浏览。

通过该 Demo 可快速理解 WebSocket 事件处理、Boost 多线程/网络 I/O 的配合方式，以及 jsoncpp 在消息编解码中的实际用法；代码结构清晰，可直接作为二次开发起点，也可用于本地调试与协议验证。

1. C++ 后端要实时推数据给网页：一份可直接编译的 Boost.Beast WebSocket Demo

做 C++ 服务端的人迟早会遇到一个尴尬需求：程序算好的行情、日志、任务状态，要实时推到网页上看。早几年我只能轮询，三五秒刷一次，数据量一大带宽先扛不住；自己拿裸 socket 手写 WebSocket 更是大坑，光是握手和帧解析就能耗掉一周。Boost.Beast 把 WebSocket 协议栈封装好了，这份 Demo 把服务端、客户端、CMake 工程一次配齐，能编译 Boost 就能直接跑。它做的事情很朴素：服务端监听 8088，接受连接并回显消息；客户端发五条消息、打印回显；CMake 一键编译。新手可以用它迈过「第一个能跑的 WebSocket 工程」这道坎，熟手能拿它当模板，加心跳、业务协议、二进制帧和鉴权逻辑。

2. WebSocket 协议与 Boost.Beast 选型：握手阶段、帧格式与头文件即库的收益

2.1 建立连接的两个阶段：HTTP Upgrade 握手与数据帧传输

WebSocket 不是凭空躺在 TCP 上的协议，它借用了 HTTP 的握手流程。客户端先发一个普通 HTTP GET 请求，带上三个关键头：Upgrade: websocket、Connection: Upgrade、Sec-WebSocket-Key。服务端校验通过后返回 101 Switching Protocols，并把基于 Sec-WebSocket-Key 计算出的 Sec-WebSocket-Accept 写进响应头，这一步完成，连接才从 HTTP 正式切换到 WebSocket 模式。一个典型的握手请求长这样：

GET / HTTP/1.1 Host: 127.0.0.1:8088 Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==

注意 Host 的端口必须对得上服务端监听的端口，路径 / 要和客户端 handshake(host, "/") 里的第二个参数一致。改了端口忘改客户端、或者路径对不上，服务端会直接拒绝握手，浏览器里表现为连接失败。这个设计带来的直接好处是：80、8080、443 这些 HTTP 端口可以直接复用，不用额外开防火墙，能过 HTTP 的链路 WebSocket 基本都能过。遇到连接问题，先用命令行工具直接发一个带 Upgrade 头的 GET，看响应是不是 101，能快速把问题定位在握手阶段还是后面的数据传输阶段，少走不少弯路。

握手完成后，传输单位变成帧（frame）。一帧里最关键的字段如下：

MASK 这条是协议硬性约束：客户端发给服务端的帧必须带掩码，服务端发给客户端的帧禁止掩码。自己写解析器漏掉掩码逻辑，浏览器会直接报错断开。Beast 把这些细节全部封装了，Demo 里读写就是 read(buffer) 和 write(buffer.data()) 两行，但理解帧结构对排查「消息发出去了对方没收到」很关键。早期我调试时把抓包工具拉出来，对照帧字段逐条看才定位到掩码问题，算是把一个黑匣子硬生生拆开了一次。断开连接时，主动关闭的一方要发一个 opcode=8 的关闭帧并带上关闭码（1000 是正常关闭、1001 是离开、1002 是协议错误），对方回一个关闭帧，TCP 连接才彻底释放。Demo 客户端循环结束后调用 ws.close(websocket::close_code::normal)，发的就是关闭码 1000；如果直接把 socket 析构不发关闭帧，服务端 read 会抛websocket::error::closed异常，代码里单独捕获它而不是当错误处理，就是这层考虑。

Demo 默认走文本帧，服务端回显时有一行 ws.text(ws.got_text())，作用是把回显帧类型对齐到收到消息的类型，避免服务端发文本、客户端按二进制解析导致打印乱码。后面要传文件、图片，把类型切成 2（二进制）走同一套读写接口即可，Beast 对两种帧的 API 完全一致，改动量很小。

2.2 选 Beast 而不选其他库：头文件即库、Asio 复用、同步异步双写法

选择 Boost.Beast 而不是其他 WebSocket 库，我主要看四点。第一，头文件即库。Beast 是 header-only 组件，编译产物不引入额外动态库，部署时只要头文件目录和 Boost 的 system 库在位，不会出现「运行时报缺 .so」这类玄学问题。第二，构建在 Boost.Asio 之上。对已经在用 Asio 的项目，引入成本几乎为零，io_context、tcp::acceptor、tcp::socket 直接复用，Beast 只是把 WebSocket 协议逻辑挂在 socket 上，是叠加不是替换。第三，同步异步两套 API 并存，这是它最实用的地方。Demo 用同步写法，accept 阻塞、read 阻塞，逻辑直白，适合先跑通链路；生产要高并发时换成 async_accept、async_read、async_write 的回调链，协议库不用换，只是在回调嵌套上多花心思。第四，wss 预留。websocket::stream 的模板参数可以换成 ssl::stream tcp::socket ，配上 SSL 上下文就能跑加密 WebSocket。Demo 没开加密，但 CMakeLists 里已把 OpenSSL 依赖配好，接 HTTPS 页面时不用重构工程。

同步和异步的取舍，展开说两句。同步 API 的好处是代码线性读完，会话逻辑里不穿插回调，调试时打断点非常直观；坏处是一个线程只能挂一个连接，Demo 里每来一个连接开一个 std::thread，对演示足够，真上了生产，几千连接就吃不住线程开销了。异步 API 把读写都变成回调，配合 io_context 的线程池能扛住高并发，但代码结构变成嵌套回调，心智负担明显上升。我的建议是先用同步把协议跑通，再逐步迁移到异步，不要在项目第一天就追求完美架构。

选型还要注意版本边界：Beast 自 Boost 1.66 起才作为正式组件发布，更早的 Boost 没有完整的 boost/beast/websocket 头文件，这是编译阶段最容易翻车的地方。建议在代码里加一道版本闸门：

#include <boost/version.hpp> #if BOOST_VERSION < 106600 #error "需要 Boost 1.66 及以上版本才能编译本 Demo" #endif

Demo 按 C++17 标准编写，编译前确认两件事：Boost 版本不小于 1.66，编译器支持 C++17。Windows 上 MSVC 2017 以后没问题，Linux 上 gcc 7 以上即可。捋清楚协议和库的边界，接下来拆 Demo 源码就有坐标系了：服务端负责握手和回显，客户端负责连接和收发，两边都是围绕几个关键调用展开。

3. 拆服务端与客户端源码：accept、握手到回显，两条核心链路逐行过

3.1 服务端：监听、accept 循环与回显会话

先看服务端主函数，它做的事情分三步：创建 io_context、创建 acceptor 绑定地址端口、进入 accept 死循环。每 accept 到一个新连接，就开一个线程跑 do_session。这里故意用了单 io_context 加每连接一线程的模式，是因为同步 API 天然适合这个结构，代码好读，跑起来也没问题，就是别拿它直接扛高并发。

// server_ws.cpp —— WebSocket 回显服务端 #include <boost/beast/core.hpp> #include <boost/beast/websocket.hpp> #include <boost/asio/ip/tcp.hpp> #include <iostream> #include <thread> namespace beast = boost::beast; namespace websocket = beast::websocket; namespace asio = boost::asio; using tcp = asio::ip::tcp; // 每个连接独立一个线程，会话结束后线程自动退出 void do_session(tcp::socket socket) { try { websocket::stream<tcp::socket> ws{std::move(socket)}; // 自定义握手响应头里的 Server 字段，纯标识用途 ws.set_option(websocket::stream_base::decorator( [](websocket::response_type& res) { res.set(beast::http::field::server, "cpp-websocket-demo"); })); // 执行握手，完成 HTTP Upgrade ws.accept(); for (;;) { beast::flat_buffer buffer; ws.read(buffer); // 阻塞等待一帧消息 std::cout << "收到: " << beast::make_printable(buffer.data()) << std::endl; // 对齐帧类型：收文本发文本，收二进制发二进制 ws.text(ws.got_text()); ws.write(buffer.data()); // 原样回显 } } catch (beast::system_error const& se) { // 客户端正常关闭会走到这里，不作为错误处理 if (se.code() != websocket::error::closed) std::cerr << "会话异常: " << se.code().message() << std::endl; } catch (std::exception const& e) { std::cerr << "会话异常: " << e.what() << std::endl; } } int main() { auto const address = asio::ip::make_address("0.0.0.0"); auto const port = static_cast<unsigned short>(8088); asio::io_context ioc{1}; tcp::acceptor acceptor{ioc, {address, port}}; std::cout << "服务端已启动: ws://0.0.0.0:" << port << std::endl; for (;;) { tcp::socket socket{ioc}; acceptor.accept(socket); // 阻塞等待新连接 std::thread(std::bind(&do_session, std::move(socket))).detach(); } return 0; }

几个关键参数说明：

• make_address("0.0.0.0") 监听所有网卡，改成 "127.0.0.1" 就只允许本机连接。局域网联调时用 0.0.0.0，但要注意防火墙放行 8088。
• websocket::stream tcp::socket 的模板参数决定底层传输，换成 ssl::stream tcp::socket 即升级为 wss。
• beast::flat_buffer 是 Beast 自带的动态缓冲区，read 之后 buffer.data() 指向收到的完整 payload。
• ws.text(ws.got_text()) 调整帧类型，got_text() 返回最近一帧是不是文本帧。
• 捕获websocket::error::closed单独放过，是因为客户端主动 close 后 read 会抛这个异常，它不是程序错误。

整个会话逻辑只有三步：accept 握手、循环 read/write、异常兜底。Demo 里没有做断开后的显式清理，因为线程结束时 socket、buffer 全部自动析构，这正是 C++ RAII 省心的地方。

3.2 客户端：解析地址、TCP 连接、握手、收发五步走

客户端比服务端多了两步：地址解析和显式握手。整体链路是 resolve -> connect -> 包装 WebSocket 流 -> handshake -> 循环收发。

// client_ws.cpp —— WebSocket 客户端，连上后发 5 条消息 #include <boost/beast/core.hpp> #include <boost/beast/websocket.hpp> #include <boost/asio/connect.hpp> #include <boost/asio/ip/tcp.hpp> #include <iostream> namespace beast = boost::beast; namespace websocket = beast::websocket; namespace asio = boost::asio; using tcp = asio::ip::tcp; int main() { auto const host = "127.0.0.1"; auto const port = "8088"; asio::io_context ioc; // 1. 解析域名或地址，得到端点列表 tcp::resolver resolver{ioc}; auto results = resolver.resolve(host, port); // 2. 建立 TCP 连接 beast::tcp_stream stream{ioc}; stream.connect(results); // 3. 将 TCP 流包装成 WebSocket 流 websocket::stream<beast::tcp_stream> ws{std::move(stream)}; // 4. 设置 User-Agent 后执行握手 ws.set_option(websocket::stream_base::decorator( [](websocket::request_type& req) { req.set(beast::http::field::user_agent, "cpp-websocket-demo-client"); })); ws.handshake(host, "/"); // 第二个参数是请求路径 // 5. 循环发送 5 条消息并打印服务端回显 for (int i = 0; i < 5; ++i) { std::string msg = "消息 #" + std::to_string(i + 1); ws.write(asio::buffer(msg)); std::cout << "已发送: " << msg << std::endl; beast::flat_buffer buffer; ws.read(buffer); std::cout << "回显: " << beast::make_printable(buffer.data()) << std::endl; } // 6. 发送关闭帧（关闭码 1000），优雅断开 ws.close(websocket::close_code::normal); return 0; }

参数说明和几个容易踩的点：

• host 和 port 都是字符串。port 写成 "8088" 而不是 8088，因为 resolver 接受服务名或端口字符串，直接传数字反而编译不过。
• stream.connect(results) 内部会逐个尝试端点，全部失败才抛异常；Demo 不做重试，是因为只演示链路，生产环境这里要套重试和超时。
• websocket::stream beast::tcp_stream 的模板参数和服务端不同：客户端底层是 beast::tcp_stream，封装了解析和连接逻辑，比直接裸用 tcp::socket 方便。
• handshake(host, "/") 的第二个参数必须和服务端 accept 的路由匹配；Demo 不校验路径，但保持一致的 "/" 是好习惯。

收发循环里有一个细节需要注意：每次 write 之后必须紧跟一次 read，否则服务端回显会堆积在缓冲区里，第二次循环 write 不会阻塞，read 拿到的可能是上一条回显，造成消息错位。如果业务是「发消息不等待回显」的推送模式，就要把读写拆到两个线程或者改异步，这是从这份 Demo 往前走的第一步。

提示：同一台机器上跑服务端和客户端，先起服务端再起客户端，顺序反了客户端会直接抛 connect 失败。

4. 编译与避坑：CMake 依赖配置、boost 版本边界和五个运行时翻车记录

4.1 CMake 工程组织：system、Threads、OpenSSL 三个依赖一次配齐

Demo 自带的 CMakeLists 是这样的：

cmake_minimum_required(VERSION 3.10) project(cpp_websocket_demo) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) find_package(Boost REQUIRED COMPONENTS system) find_package(Threads REQUIRED) find_package(OpenSSL REQUIRED) add_executable(ws_server server_ws.cpp) target_link_libraries(ws_server PRIVATE Boost::system Threads::Threads OpenSSL::SSL OpenSSL::Crypto) add_executable(ws_client client_ws.cpp) target_link_libraries(ws_client PRIVATE Boost::system Threads::Threads OpenSSL::SSL OpenSSL::Crypto)

三个依赖各管一件事。Boost::system 链接 boost_system 库，Beast 的错误类型依赖它——Beast 本体是 header-only，但系统错误码相关的符号需要这个库；Threads 是跨平台线程库，服务端的 std::thread 需要它；OpenSSL 是为 wss 预留，当前 Demo 没有调用 SSL 接口，但链接上不会有害，反而省得后面升级时再改 CMake。编译命令就是标准流程：

mkdir build && cd build cmake .. make -j4 ./ws_server & ./ws_client

如果 cmake 找不到 Boost，先确认 BOOST_ROOT 环境变量是否指向目标 Boost 安装目录；Windows 下还要检查 CMake 配置的编译器架构（x64/x86）和 Boost 预编译库架构是否一致，这个不一致会让 find_package 拿到一堆「找不到匹配版本」的报错，看着像路径问题，其实是架构问题。

注意：给 CMakeLists 做任何改动之前先备份一份，版本切换翻车时后悔药得提前备好。

4.2 五个高频踩坑记录

编译能过只是第一关，运行时的问题才考验功底。下面这些坑是我在不同机器上反复遇到过的，按现象、原因、解决的顺序写，方便直接对照排查。

坑一：beast 头文件直接找不到。 现象：编译报 fatal error: boost/beast/websocket.hpp: No such file or directory。 原因：Boost 版本低于 1.66，或者 include 路径没指到 Boost 根目录。 解决：先在代码里加第 2 章提到的 BOOST_VERSION 版本闸门，确认版本；路径问题检查 BOOST_ROOT 和 CMAKE_INCLUDE_PATH 两个变量，Linux 上还可以用dpkg -l | grep libboost看系统包版本。

坑二：CMake 的 find_package(Boost) 找到错误版本。 现象：机器上装了系统自带的旧 Boost 和本地编译的新 Boost，cmake 默认选中旧版，编译到一半报不支持的特性。 原因：find_package 的搜索顺序里系统路径排在前面，本地路径被忽略。 解决：cmake 配置时显式指定-DBOOST_ROOT=/path/to/new-boost，必要时加-DBoost_NO_SYSTEM_PATHS=ON只搜指定路径。这个参数在 CI 环境里尤其有用，否则同一份代码在不同机器上编译结果不一致。

坑三：链接阶段报 undefined reference，集中在 boost::system。 现象：编译全部通过，链接时报几十个undefined reference to boost::system::...。 原因：Beast 虽然是 header-only，但错误分类相关的符号在 libboost_system 里，没链接这个库。 解决：find_package(Boost REQUIRED COMPONENTS system) 并把 Boost::system 加进 target_link_libraries。如果项目要求零动态依赖，可以在包含 beast 头文件之前定义BOOST_ERROR_CODE_HEADER_ONLY启用 header-only 错误码，省掉这个库，但建议保持默认，少折腾。

坑四：运行中客户端秒断，报 10053 或 10054 连接被重置。 现象：服务端确实起来了，客户端偶尔收到回显，偶尔一握手就断，服务端打印 connection reset。 原因：最常见是两个：一是服务端会话对象在 accept 之后被意外提前析构，TCP 连接被强制关闭；二是异步改造时前一个 write 还没写完就调 close，发送缓冲被清空，对端直接收到 RST。 解决：同步版 Demo 里 read 返回之后再 close 是安全的；改成异步后，close 前必须确认所有 pending 写操作完成，加一个发送队列计数。排查时先看服务端有没有打印异常，再抓包看 RST 出现在哪个阶段，能区分是析构问题还是写后关闭问题。

坑五：中文消息打印出来是乱码。 现象：客户端发「中文测试」，服务端打印成乱码，或者回显到浏览器变乱码。 原因：源文件编码不是 UTF-8，字符串字面量在运行时是 GBK 字节序列，而 WebSocket 文本帧按 UTF-8 语义传输，两侧编码不一致。 解决：源文件统一存成 UTF-8，MSVC 加 /utf-8 编译选项，gcc 加 -finput-charset=UTF-8 -fexec-charset=UTF-8；不要在代码里手写转码，数据链路统一 UTF-8 是 WebSocket 应用的默认约定。这个坑在 Windows 上最隐蔽，因为 MSVC 默认按本地代码页读源文件，换了机器就翻车。

5. 进阶验证：加心跳、上 JSON、用浏览器实测一轮

5.1 心跳与断线感知

Demo 的收发循环是阻塞的，客户端不开消息服务端永远不知道它活着。生产环境要加心跳，标准做法是 WebSocket 自带的 ping/pong 帧：一端周期性发 ping，另一端自动回 pong，不需要业务层参与。以服务端为例，用 Asio 的 steady_timer 每 30 秒发一次 ping 帧，连续几次收不到 pong 就判定断线并关闭连接：

// 用 shared_ptr 持有定时器，回调里重新安排下一次 ping，形成周期心跳 auto timer = std::make_shared<asio::steady_timer>(ws.get_executor()); std::function<void()> ping_loop; ping_loop = [&ws, timer, &ping_loop]() { timer->expires_after(std::chrono::seconds(30)); timer->async_wait([&ws, timer, &ping_loop](boost::system::error_code ec) { if (ec) return; // 会话结束，取消定时器 ws.ping(asio::buffer("hb")); // 发 ping 帧，pong 由 Beast 自动回 ping_loop(); // 安排下一次心跳 }); }; ping_loop();

关键点在于 timer 用 shared_ptr 持有，回调里也捕获一份，否则定时器在回调触发前被析构，async_wait 会立刻返回一个 operation_aborted 错误，心跳直接停摆。ws 的生命周期必须覆盖整个心跳循环，这也是异步代码最常见的对象生命周期问题。

5.2 浏览器实测与 JSON 协议设计

验证 Demo 是否真的可用，浏览器是最快的手段。开一个空页面，按 F12 进控制台，直接执行：

const ws = new WebSocket("ws://127.0.0.1:8088"); ws.onopen = () => ws.send("来自浏览器"); ws.onmessage = (e) => console.log("服务端回显:", e.data);

能看到回显，说明握手、收发、帧类型全部正常，这份 Demo 才算真正落地。我每次改完服务端都习惯性先跑一遍浏览器实测，再跑客户端程序，因为浏览器对协议错误最敏感，有一点不合规立刻断开。

把 Demo 推向生产，消息体建议统一成 JSON 字符串：{"type":"ping"}、{"type":"data","payload":{...}}，客户端先解析 type 字段再分发给对应的业务处理函数。Demo 是回显逻辑，改成业务只需把 do_session 的 for 循环里的 write 换成对业务处理函数的调用即可。从那以后，我每次拿到网络相关的 Demo，都会强制走一遍三件事：确认 Boost 版本、跑一遍 CMake、用浏览器实测一轮。这三步能拦住八成的编译问题和协议细节问题，希望帮到你。

本文还有配套的精品资源，点击获取