企业官网建设流程全解析

做嵌入式或者物联网相关的开发，只要牵扯到设备端和服务器端实时通信，WebSocket基本是绕不开的一个协议。之前我在一个网关项目里需要把设备状态实时推送到前端页面，最开始用的是HTTP轮询，设备一多、频率一高，服务器压力立刻上来了，后来换成了WebSocket方案，整个链路清爽了很多。当时调研了一圈开源库，最终选了libwebsockets，而这一选就用到了现在。

libwebsockets是一个用C语言实现的WebSocket协议库，官方定位就是轻量级、嵌入式友好，同时也支持完整的服务端和客户端能力。它对资源的占用控制得比较好，在树莓派这类性能不强的板子上也能跑得很稳，而且License是MIT，商用基本没有太多限制。这篇东西不是讲协议原理的，重点放在最实际的三件事上：怎么把源码下载下来、怎么编译出自己想要的库、以及怎么确认编译出来的东西真的能用。文章面向的是那些刚接触这个库的开发者，或者说已经在集成路上被编译问题卡住的人。我会把整个流程拆开来讲，包括我在实际编译中踩过的坑和一些取舍逻辑，尽量让你少走弯路。

1. 为什么选libwebsockets：轻量、干净、工艺成熟

大多数人在选WebSocket库的时候，常常纠结于libwebsockets和websocketpp、uWebSockets这几个热门的库。用下来之后我的体会是，libwebsockets最大的优势在于它的"克制的设计"，它不像websocketpp那样重度依赖Boost，也不像uWebSockets那样为了极致性能引入了比较复杂的异步模型。C语言实现的库在交叉编译、嵌入式部署上天然有优势，不扯什么运行时依赖，编出来是什么就是什么。

1.1 这个库解决了什么问题

WebSocket协议本身并不复杂，但实现起来坑很多。握手阶段的HTTP Upgrade流程、帧的解析与掩码处理、分片消息重组、Ping/Pong心跳机制、关闭握手的时序，这些细节开发者自己撸一遍少说也得一两周，还未必覆盖到所有的边界情况。libwebsockets把这些全部封装好了，你只需要关心业务逻辑：连接建立之后往缓冲区里写数据，或者从回调里读数据。

它的典型使用场景包括：

• 嵌入式设备状态上报：设备通过WebSocket连接服务器，实时上报传感器数据。
• 前端实时看板：后端通过WebSocket向浏览器推送告警、日志、指标。
• 多设备消息转发：在局域网内部署一个轻量WebSocket服务端，供多个客户端订阅消息。
• IoT网关：一边接入传感器协议，一边通过WebSocket把数据上传到云平台。

这个库还自带了一个事件循环机制（event loop），默认基于poll()实现，也可以换epoll，在Linux上性能表现相当不错。编译的时候很多组件都可以裁剪，对应不同的业务需求，这一点后面会详细说。

1.2 和其他方案的一笔对比账

为了说清楚"为什么是它"，我把自己实际用过的几个库放在一起做个对比：

如果你的项目是纯C/C++混编、以后要往ARM板子上移植，libwebsockets几乎是阻力最小的选择。如果你本身就在用Boost且项目全是C++，那websocketpp的无缝集成也有它的道理。组件的选择不分绝对好坏，只有适不适合手头的项目，但从本篇文章的编译环境出发，我默认你已经选定libwebsockets。

1.3 它的源码结构一览

从GitHub把仓库拉下来之后，你会看到几个关键目录（以v4.x版本为例）：

• /lib：核心代码，协议解析、事件循环、TLS封装都在这里。
• /bin：部分工具的入口代码，比如测试服务器。
• /test-apps：官方自带的测试程序源码，编译后会在build目录里生成可执行文件。
• /include：公共头文件，编译安装后拷贝到系统include目录。
• /cmake：CMake模块，处理依赖查找和平台检测。

了解目录结构有助于后面找文件和排查问题，特别是当你想确认某个API的原型时，直接去include/libwebsockets.h里查最快。

2. 编译前的准备：环境检查与依赖梳理

很多人编译开源库翻车，往往不是库本身的问题，而是环境里缺了某个依赖，或者依赖版本不对。所以在下载源码之前，先把环境捋清楚，能省下后面很多麻烦。

2.1 操作系统与编译器要求

官方对平台的适配做得比较好，Linux、macOS、Windows（MSVC/MinGW）都能编。我自己的主力环境是Ubuntu 20.04/22.04，下面的操作都以这个环境为例。如果你用的是CentOS或者树莓派OS，命令上把包管理器换成yum/apt对应的就好。

编译器方面，gcc版本建议4.8以上，因为libwebsockets的CMake构建会用到一些C11特性。用gcc --version确认一下，太老的编译器建议先升级。另外cmake版本不能太老，3.10以上比较稳妥。

2.2 关键依赖的可选与必选

Libwebsockets在编译时有两个方向的依赖：

• TLS库：默认会去查找OpenSSL。如果你的场景是纯内网、没有wss加密，可以不装SSL，编译时用LWS_WITH_SSL=OFF关掉。但我的建议是即使暂时用不上，也把OpenSSL装好，因为一旦后续要上wss，重新编译库的代价要比提前装好大得多。
• libuv：这是一个可选依赖，用LWS_WITH_LIBUV=ON启用。libuv的事件循环在某些高并发场景下有优势，但多数嵌入式场景用不到，可以不开。

Ubuntu下基础依赖安装命令：

sudo apt update sudo apt install -y build-essential cmake git libssl-dev

如果你的系统里没有OpenSSL头文件，CMake配置阶段会直接报错提示找不到openssl，这也是很多新手遇到的第一道坎。装好libssl-dev之后，这个报错通常就消失了。

2.3 源码下载的两种方式与版本选择

下载源码有两种常用方式：

# 方式一：git clone 最新仓库 git clone https://github.com/warmcat/libwebsockets.git # 方式二：下载指定版本的release压缩包 wget https://github.com/warmcat/libwebsockets/archive/refs/tags/v4.3.3.tar.gz tar -xzvf v4.3.3.tar.gz

版本选择上，我个人建议优先选release tag而不是main分支。main分支是开发分支，API可能会变动，今天我基于某个版本写好的代码，过一两个月可能就编译不过了。在GitHub的Tags页面能看到所有正式版本，选最新的稳定版即可。以我写这篇文章的时间点，v4.3.x是一个比较稳的版本。

下载到本地后，解压进入源码目录，接下来就可以开始配置编译参数了。

3. 用cmake-gui配出一份适合自己项目的编译配置

一说到CMake，很多习惯写Makefile的老哥第一反应就是"命令行敲两行就编完，搞什么GUI"。但我为什么推荐先用cmake-gui？是因为libwebsockets的编译开关非常多，命令行一条条写下来不但容易漏，还不直观。图形界面的好处在于能实时看到所有可配置项，随手勾选，反复调整编译参数时效率会高很多。

3.1 配置工具的选择逻辑

直接跑cmake ..其实也能编，但默认配置会把很多用不到的功能也编进去，导致编译时间成倍增加。而且libwebsockets的钩子选项多达几十个，命令行方式稍不留神就会配置出"看似成功实则带病"的构建，比如漏掉某个关键的宏定义。

考虑到第一遍编译多半会遇到各种依赖问题，用cmake-gui能在界面里直接看到红色告警或缺失项，这对新手极其友好。所以我建议：第一次配置用图形界面，跑通之后把最终配置固定下来；后续自动化构建再改回命令行。

安装cmake-gui：

sudo apt install -y cmake-curses-gui

注意这里装的是cmake-curses-gui，提供的工具叫ccmake，是一个终端里运行的交互式配置界面。如果你在桌面环境也可以装cmake-qt-gui，就是带图形界面的cmake-gui。两者功能等价，下面操作以ccmake为例。

3.2 完整的配置流程

在源码根目录下创建并进入build目录，然后启动配置工具：

cd libwebsockets mkdir build cd build ccmake ..

首次打开ccmake会先自动跑一遍CMake配置，然后显示当前所有的编译选项。按下c键重新配置，配置过程中若有红色高亮项，说明该配置有问题或者依赖缺失，需要处理。配置完成后按g键生成Makefile并自动退出。

我习惯调的几个关键开关：

如果你只想快速看到一个能跑的实验环境，最简单的配置方式是：

• LWS_WITH_SSL保持ON（确保环境里装了libssl-dev）
• LWS_WITH_MINIMAL_EXAMPLES保持ON（方便查看官方示例代码）
• LWS_WITHOUT_TESTAPPS设为OFF（这样能编出测试服务器）

这样配置出来的库功能齐全，适合第一次跑通，缺点就是编译时间会长一点。有一说一，我现在已经在用机器的环境比较好，四核八线程开满，默认配置大概一分钟左右能编完。但在树莓派或者老旧的笔记本上，默认配置编译一次可能要七八分钟，这也解释了网上不少人说"libwebsockets编译很慢"的原因，其实就是把用不上的组件全编了一遍。

3.3 理解开关背后的裁剪思路

这里要展开说一下为什么要花这么多精力去理解编译开关。库的裁剪不只是为了编译速度，更重要的是降低运行时的资源占用和攻击面。

嵌入式设备上的Flash和RAM都很有限，如果只用到WebSocket客户端功能，却把服务端、SSE（Server-Sent Events）、HTTP目录服务、cgi等等全部编进去，最终镜像体积会大不少。仔细计算下来，一个去掉所有不需要功能的libwebsockets，静态库体积能比默认配置缩减一半还要多。

所以在配置的时候，不妨先问自己几个问题：

• 我这个设备是做客户端还是服务端？
• 传输层是明文还是要TLS？
• 和业务层之间的连接是只用WebSocket，还要不要HTTP/2等其他协议？
• 底层IO复用用默认poll就够，还是要epoll事件循环？

把这些想清楚再动手配置，编译出来的库会非常贴合你的实际场景，运行稳定性和编译效率都是最优的。这也是一个好的嵌入式工程师和"复制粘贴编译派"的本质区别。

3.4 最小客户端库配置实战

这里我以"在ARM板上做一个纯WebSocket客户端，使用TLS连接云服务器"为假想需求，给出一份精简配置的具体操作。

进入ccmake界面后，做以下修改：

• LWS_WITH_SSL= ON（需要TLS）
• LWS_WITH_MINIMAL_EXAMPLES= OFF
• LWS_WITHOUT_TESTAPPS= ON
• LWS_WITHOUT_TEST_SERVER= ON
• LWS_WITH_LIBUV= OFF
• LWS_WITH_HTTP2= OFF（纯WebSocket用不到HTTP/2）
• LWS_WITH_HTTP_STREAM_COMPRESSION= OFF
• LWS_WITH_FILE_OPS= OFF（如果不需要访问本地文件）

配置完成后按g生成。然后在build目录下执行：

make -j$(nproc)

-j$(nproc)表示使用本机所有CPU核心并行编译，能大幅缩短编译时间。如果你在嵌入式设备的交叉编译环境里，还可以手动指定核心数避免OOM，比如make -j4。

编译完成后，你会在build目录下看到以libwebsockets.so结尾的共享库（或libwebsockets.a静态库），以及一个libwebsockets.h的头文件路径，整个编译阶段就结束了。

4. 从make到make install:产物确认与项目衔接

编译成功只是第一步。你需要的不是build目录里的中间产物，而是能装到系统路径、能被其他工程引用的干净库文件。

4.1 安装命令与路径选择

如果你用的是默认prefix/usr/local，那么只需要：

sudo make install

安装完成后，确认这几个路径下是否出现了相应文件：

• /usr/local/include/libwebsockets.h——头文件，写代码时#include <libwebsockets.h>会用到。
• /usr/local/lib/libwebsockets.so——共享库。
• /usr/local/lib/libwebsockets.a——如果没有关闭静态库生成，还会有这个。

如果你用的是自定义prefix，比如/opt/lws，那么记得把头文件路径和库路径都加到编译环境中。我在项目里常用的做法是：

export LWS_ROOT=/opt/lws export C_INCLUDE_PATH=$LWS_ROOT/include:$C_INCLUDE_PATH export LIBRARY_PATH=$LWS_ROOT/lib:$LIBRARY_PATH export LD_LIBRARY_PATH=$LWS_ROOT/lib:$LD_LIBRARY_PATH

这些环境变量可以写进~/.bashrc，但也建议在项目的CMakeLists.txt里显式指定，因为环境变量跨项目共享，容易污染其他工程的构建。

4.2 验证库文件信息

安装完毕后，不要急着写业务代码，先用几个Linux下的基础命令确认库文件是正常的：

# 查看共享库的链接依赖 ldd /usr/local/lib/libwebsockets.so # 查看导出的符号表，确认核心API在里面 nm -D /usr/local/lib/libwebsockets.so | grep lws_client_connect

如果ldd输出里出现not found，大概率是某个依赖没装或者路径不对，比如libssl.so缺失。遇到这种情况回去检查OpenSSL的安装和编译参数。nm如果能搜到lws_client_connect相关符号，说明客户端API已经正确导出了。

4.3 在自己的CMake工程里链接这个库

在CMakeLists.txt里链接libwebsockets很简单：

cmake_minimum_required(VERSION 3.10) project(MyLwsTest C) set(CMAKE_C_STANDARD 11) find_package(PkgConfig REQUIRED) pkg_check_modules(LIBWEBSOCKETS REQUIRED libwebsockets) include_directories(${LIBWEBSOCKETS_INCLUDE_DIRS}) link_libraries(${LIBWEBSOCKETS_LIBRARIES}) add_executable(my_lws_test main.c)

如果你用的是命令行gcc直接编译，对应的命令是：

gcc -o my_lws_test main.c -lwebsockets -lssl -lcrypto

这里有一个细节：链接顺序很重要。-lwebsockets要放在源文件之后，因为GNU ld是单遍扫描的，被依赖的库要放在依赖者后面。很多人第一次编译自己的工程时遇到的undefined reference问题，往往是库的链接顺序反了。

5. 测试验证：启动官方服务器、手测连接与压测尝试

库编好、装好之后，最需要确认的就是它真的能建立WebSocket连接、收发消息。libwebsockets在源码里自带了几套测试程序，这一步比你自己写一个demo再去调试要方便得多。

5.1 用官方测试服务器做回环验证

如果你在配置时保留了测试服务器的构建（LWS_WITHOUT_TEST_SERVER为OFF），那么在build/bin目录下编译后的可运行文件里，会有一个libwebsockets-test-server（不同版本名字可能略有差异，有的是websockets-test-server）。启动方式：

cd build/bin ./libwebsockets-test-server -p 7681

-p参数指定端口，我这里用的是7681。正常情况下命令行会输出监听日志，大概类似"Listening on port 7681"，说明服务端已经跑起来了。

需要注意一点：如果你编译时开了TLS但没给测试服务器配证书，它启动时可能会因为找不到证书而报错退出。这种情况下有两处理方式：要么把LWS_WITH_SSL关掉重编一个纯明文测试版本；要么在启动参数里指定证书路径。对于最基础的验证，我建议先用纯明文版本跑通，再考虑TLS。

5.2 用浏览器验证整个链路

打开Chrome或者Firefox，在开发者工具的控制台里执行：

var ws = new WebSocket("ws://127.0.0.1:7681", "dumb-increment-protocol"); ws.onopen = function() { console.log("[open] connected"); ws.send("hello libwebsockets"); }; ws.onmessage = function(e) { console.log("[message]", e.data); };

192.168.x.x等局域网地址同理，把127.0.0.1换成服务器IP即可。如果你在控制台看到[open] connected，并且能收到服务端的回包，说明这个库的WebSocket服务端数据处理流程基本没有问题。

5.3 用命令行工具做非浏览器验证

有时候你需要模拟大量连接，或者在一些无浏览器的环境中验证。可以使用websocat这样的命令行WebSocket客户端：

# 安装websocat sudo apt install -y websocat # 连接测试服务器 websocat ws://127.0.0.1:7681

连接成功后可以直接输入文本向服务端发送消息，收到的回包会打印在终端里。有条件的也可以写一段Python脚本用websockets库并发建立几十条连接，观察服务端日志是否稳定。

5.4 客户端模式测试，验证库作为客户端的能力

前面的操作都是从浏览器/命令行作为客户端连到libwebsockets服务端。但实际项目中你可能更常需要把libwebsockets作为嵌入式设备上的客户端去连接外部的WebSocket服务器。

验证客户端模式也很简单：在build/bin目录下，官方也编出了一个测试客户端程序（通常叫libwebsockets-test-client）。先在一个终端启动网络上的任意WebSocket服务端，比如用Python跑一个：

pip install websockets python3 -m websockets ws://127.0.0.1:9002

然后在另一个终端执行：

./libwebsockets-test-client ws://127.0.0.1:9002

观察两边日志，如果服务端收到了来自客户端的连接握手，客户端没有异常退出，说明libwebsockets作为客户端时的连接逻辑也正常。这一步容易被人忽略，但恰恰是嵌入式联网设备里最常用的工作模式。

6. 嵌入式交叉编译：给ARM板定制一个库

前面所有流程都在x86 Linux上操作，对于部署在树莓派、全志、RK等ARM平台上的项目，还需要考虑交叉编译。这部分的思路和原生编译完全一样，只是需要额外提供一个工具链文件，并关掉那些在板子上用不到的组件。

6.1 什么是工具链文件，为什么需要它

交叉编译的意思是在PC上编译生成目标板（比如ARM）上运行的二进制。CMake默认会使用本机的gcc，它编译出来的程序只能在x86上跑。这时就需要通过一个toolchain.cmake文件告诉CMake："编译器换成交叉编译器，目标系统改成ARM"。

一个典型的toolchain文件（以树莓派32位系统为例）：

SET(CMAKE_SYSTEM_NAME Linux) SET(CMAKE_SYSTEM_PROCESSOR arm) SET(CMAKE_C_COMPILER arm-linux-gnueabihf-gcc) SET(CMAKE_CXX_COMPILER arm-linux-gnueabihf-g++) SET(CMAKE_FIND_ROOT_PATH /usr/arm-linux-gnueabihf) SET(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) SET(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) SET(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

我这里用的是Ubuntu自带的arm-linux-gnueabihf交叉编译工具链，如果没有先安装：

sudo apt install -y gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf

如果你用的是aarch64（64位ARM），则把工具链前缀改成aarch64-linux-gnu-。

6.2 交叉编译的配置命令

在源码根目录下重新建一个build-arm目录，避免和原来x86的build目录混淆：

cd libwebsockets mkdir build-arm cd build-arm cmake .. -DCMAKE_TOOLCHAIN_FILE=../toolchain.cmake \ -DLWS_WITH_SSL=OFF \ -DLWS_WITH_MINIMAL_EXAMPLES=OFF \ -DLWS_WITHOUT_TESTAPPS=ON \ -DCMAKE_BUILD_TYPE=Release

然后编译：

make -j4

注意这里不要使用-j$(nproc)，因为交叉编译时单机核心太多会导致内存被瞬间打满，除非你确定内存足够。

6.3 交叉编译时的常见坑

交叉编译的坑主要来自依赖库。如果目标板上需要TLS，你在PC上装的OpenSSL是x86版本，不能直接链接到ARM程序里。要么关掉SSL，要么从源码交叉编译一份ARM版的OpenSSL。

我在最初尝试时，就是在这里差点放弃。一开始想着"反正编译的是Linux库，应该会自动适配吧"，结果连接时一堆undefined reference to SSL_CTX_new，这才反应过来OpenSSL也需要为ARM平台单独编译。所以嵌入式场景有个原则：用不到的能关就关，能省掉一个依赖就省掉一个依赖。这也是为什么我在工具链文件示例里默认关闭SSL。

6.4 验证交叉编译产物

交叉编译完成后，通过file命令检查产物架构：

file lib/libwebsockets.so

如果输出中含有ARM字样的架构信息，说明交叉编译成功；如果显示x86-64，说明编译器还是本机的，回到toolchain文件检查路径和名字是否写对。

把这个libwebsockets.so和头文件拷贝到目标板，再在板子上用ldconfig刷新动态库缓存，就可以正常连接使用。在板子上做基础连通性测试时，可以直接用板子上的curl或者其他工具做一次握手包的探测：

echo -e "GET / HTTP/1.1\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==\r\nSec-WebSocket-Version: 13\r\nHost: example.com\r\n\r\n" | nc 目标服务器IP 端口

如果服务器返回101状态码，说明网络链路和协议栈是通的，问题基本锁定在应用层代码上。

7. 我在编译测试中踩过的坑，以及对应的排查思路

这一部分我非常想写，因为翻看网上帖子，很多人编译失败后习惯性地把错误信息直接丢进搜索引擎，找到什么答案就贴什么，回头问题并没有真正解决。我在这里把几个高频的、有共性的问题整理出来，顺手说说我的定位方法。

7.1 报错找不到ssl/openssl头文件

这个报错基本上集中在CMake配置阶段，错误信息里往往会出现Could NOT find OpenSSL。原因很简单：OpenSSL的开发头文件没有安装。我多次强调装libssl-dev就是为了这个。如果确实装了还找不到，确认一下安装路径是否在CMake的搜索范围内。Ubuntu下默认路径是/usr/include/openssl，如果没问题再查一下环境变量OPENSSL_ROOT_DIR有没有被错误地设置。

排查这类问题，不要急着在CMakeLists里写死路径，先手动找一下openssl/ssl.h在哪个目录，再决定是装包还是加路径，效率高得多。

7.2 编译很慢：多半是编了太多用不上的组件

"libwebsockets编译很慢"是热搜里经常出现的关键词，我也深有体会。有一次我在一台老笔记本上默认配置编译，去泡了杯咖啡回来还没编完。后来我发现问题不在于编译器，而在于默认配置把minimal examples、test server、test apps、各种插件全都编译了一遍。

解决方案就是前文讲过的裁剪逻辑。如果是做开发调试，可以用make -j4并在配置阶段把LWS_WITH_MINIMAL_EXAMPLES关闭，只保留自己需要的部分。裁剪之后，编译时间能从十几分钟降级到一两分钟，体感差别非常显著。

7.3 链接的时候出现undefined reference

这个报错一般不是libwebsockets本身的问题，而是调用方工程的问题。最常见的原因有三个：

• 链接库顺序不对：-lwebsockets必须放在源文件或者依赖它的库之后。
• 少了TLS依赖：libwebsockets如果编译时开了SSL，链接时就要跟着加-lssl -lcrypto。
• 头文件和库版本不匹配：比如头文件是新的，库文件是旧的，API对不上。

解决方法是编译时加上-v参数，看编译器实际执行的链接命令，把所有-l参数顺序捋一遍，基本能定位。

7.4 编译出来体积偏大：静态库和动态库取舍

有些场景下你希望把libwebsockets静态编进应用里，这样运行时不需要额外动态库。在CMake配置里，可以设置LWS_WITH_STATIC=ON，或者同时生成两种库。不过静态链接有个注意点：如果libwebsockets内部依赖了OpenSSL，静态链接时通常需要添加-ldl -lpthread，否则会出现符号找不到的错误。

体积方面，如果做极致裁剪，可以尝试开启LWS_WITH_MINIMAL_EXAMPLES=OFF加上-Os优化选项，最终静态库体积能小到几百KB级别，对于Flash紧张的板子来说相当友好。

7.5 测试连接失败，但服务端看起来启动正常

如果是服务端模式，启动日志正常但客户端连不上，优先检查端口占用和防火墙。用ss -lntp查看端口有没有被监听，用curl -v做一次HTTP探测看握手阶段是否响应。如果是客户端模式，优先检查服务端地址、端口和协议名是否匹配，比如测试服务器要求子协议为dumb-increment-protocol，客户端没指定这个子协议时会被直接拒绝。

这一类问题的排查思路是：从链路最底层往上逐步排除。先确认TCP能通，再确认HTTP 101返回，再去看WebSocket协议层，最后才是业务逻辑。

我在实际项目里摸索出的心得其实就一句话：把一个库用好，不在于把文档从头翻到尾，而在于把它在你的具体工程里跑出符合预期的行为。libwebsockets的代码质量和文档在开源项目里都算上乘，编译安装这块熟悉以后，后面写业务代码会顺畅许多。如果将来你有时间，建议把minimal-examples目录下的官方示例逐个跑一遍，那些示例覆盖了从客户端、服务端、异步收发到原始HTTP处理的全部常见玩法，每跑通一个你就对这个库的理解深一层。这套编译测试流程，现在花半个下午走一遍，以后能给整个项目省下好几个下午。