ESP32 WebSocket实操:状态全端秒同步,不用轮询

2026-11-16 13:32:35 54阅读 所属项目:ESP32 开发板

早班刚发过一篇 ESP32 Web Server 实操,浏览器点按钮控制 LED,走的是最经典的 HTTP 路由。那套方案有个先天短板:服务器这边状态一变,已经打开的页面不会知道,得手动刷新才能看到。Random Nerd Tutorials 最近这篇教程给的解法是 WebSocket——连接一直挂着,谁那边变了就全员广播。我把它拆了一遍,顺手把 WebSocket 和 HTTP 轮询的差异讲清楚。对上班族玩家来说,这种不用一直盯着页面的玩法很省心——设备状态变了,页面自己会动。

ESP32 WebSocket服务器控制LED

WebSocket 和 HTTP 轮询差在哪

HTTP 那套的节奏是一问一答:浏览器发请求,ESP32 回一句,连接结束。浏览器想知道最新状态,只能自己再问一次,这就是轮询。轮询频率低,状态更新就慢;频率高,大部分请求又是白跑。多开几个标签页或者多拿几台设备访问时,这个别扭会更明显——你在这台手机上把灯打开,那台电脑上的页面还停在旧状态。

WebSocket 的思路完全不同。握手阶段借一次 HTTP 完成,之后这条 TCP 连接就一直保持着,双向都能随时发消息。用底稿教程的说法,服务器(也就是 ESP32 这块板子)可以在没人请求的情况下主动把消息推给浏览器——GPIO 状态一变,所有在线客户端几乎同时收到通知。而且握手走的就是 HTTP 请求加响应,同一个端口既能接普通 HTTP,也能接 WebSocket,升级完就是全双工。

WebSocket双向通信工作流程图

对应到这个项目,流程是这样的:你在网页上点 Toggle 按钮,浏览器通过 WebSocket 发一条 toggle;ESP32 收到后翻转 LED 状态,然后把新状态广播给所有客户端;每个页面收到消息后自己更新显示。整条链路里没有一次刷新页面。

装库:认准 ESP32Async 维护的两个库

这套代码在 Arduino IDE 里跑,靠 ESPAsyncWebServer 库自带的 WebSocket 插件。底稿指定的是 ESP32Async 这个组织维护的版本,一共装两个:ESPAsyncWebServer,以及它依赖的 AsyncTCP。库管理器在 IDE 左侧边栏的图书馆图标里,搜名字认准作者名再点安装——同名旧版库不少,装错了编译时就会报缺头文件。

硬件上没有任何额外接线,输出用的就是 GPIO 2 的板载 LED。板子选 ESP32 开发板,正常烧录即可,这也是这套例子适合当第一个 WebSocket 练手项目的原因。烧录前记得核对开发板型号和 COM 口,底稿特意提醒过这一步——编译报错八成出在选错板子或者串口驱动没装上。

另外提醒一句,站点会把尖括号写法的头文件吃掉,所以下面代码里的 #include 一律用了引号写法。在 Arduino 里引号和尖括号两种写法对库的搜索路径是等价的,编译结果一样,不影响照抄。

服务端:三段回调把 WebSocket 跑起来

先看头文件和全局定义。ssid、password 换成自家 WiFi 的信息,ledPin 固定 GPIO 2;AsyncWebServer 挂 80 端口,AsyncWebSocket 挂在 /ws 路径上——这个路径待会儿浏览器那头的 gateway 要对上。

// Import required libraries
#include "WiFi.h"
#include "AsyncTCP.h"
#include "ESPAsyncWebServer.h"

// Replace with your network credentials
const char* ssid = "REPLACE_WITH_YOUR_SSID";
const char* password = "REPLACE_WITH_YOUR_PASSWORD";
bool ledState = 0;
const int ledPin = 2;

// Create AsyncWebServer object on port 80
AsyncWebServer server(80);
AsyncWebSocket ws("/ws");

服务端的核心就三个函数。第一个 notifyClients,ws.textAll() 把当前 LED 状态一次性发给所有连着的客户端,广播靠的就是它:

void notifyClients() {
  ws.textAll(String(ledState));
}

第二个 handleWebSocketMessage,是收到客户端消息时的回调。这里有两处值得细看的细节:帧校验和字符串收尾。

void handleWebSocketMessage(void *arg, uint8_t *data, size_t len) {
  AwsFrameInfo *info = (AwsFrameInfo*)arg;
  if (info->final && info->index == 0 && info->len == len && info->opcode == WS_TEXT) {
    data[len] = 0;
    if (strcmp((char*)data, "toggle") == 0) {
      ledState = !ledState;
      notifyClients();
    }
  }
}

if 条件里 info->final、info->index == 0、info->len == len、opcode == WS_TEXT 四个判断连着写,意思是只处理单帧、完整、文本类型的消息。data[len] = 0 这一行是手动补字符串结束符,没有它,strcmp 拿去比较的就是一段没封口的内存,结果不可预期。

第三个 onEvent,是 WebSocket 生命周期事件的总入口。连接建立、断开、收到数据、pong 响应、出错,五类事件都在这里分流,收到数据再转给 handleWebSocketMessage 处理:

void onEvent(AsyncWebSocket *server, AsyncWebSocketClient *client, AwsEventType type,
             void *arg, uint8_t *data, size_t len) {
  switch (type) {
    case WS_EVT_CONNECT:
      Serial.printf("WebSocket client #%u connected from %s\n", client->id(), client->remoteIP().toString().c_str());
      break;
    case WS_EVT_DISCONNECT:
      Serial.printf("WebSocket client #%u disconnected\n", client->id());
      break;
    case WS_EVT_DATA:
      handleWebSocketMessage(arg, data, len);
      break;
    case WS_EVT_PONG:
    case WS_EVT_ERROR:
      break;
  }
}

把回调绑定到 /ws 路径的是 initWebSocket,两行搞定:

void initWebSocket() {
  ws.onEvent(onEvent);
  server.addHandler(&ws);
}

网页本体打包在 index_html 这个 rawliteral 字符串里,底稿把 HTML、CSS、JavaScript 全塞在了一起。页面结构很简单:一张标题卡片,一行 state 状态文字(span 带 id="state",旁边放着 %STATE% 占位符),一个 Toggle 按钮(id="button")。占位符由 processor 在发页面时替换,ledState 为 1 就填 ON,否则填 OFF:

String processor(const String& var){
  Serial.println(var);
  if(var == "STATE"){
    if (ledState){
      return "ON";
    }
    else{
      return "OFF";
    }
  }
  return String();
}

setup 里除了常规的串口初始化、连 WiFi、点灯引脚,关键动作是注册根路径路由并启动服务。server.on 里把 processor 一并传了进去,占位符替换全靠它:

  initWebSocket();

  // Route for root / web page
  server.on("/", HTTP_GET, [](AsyncWebServerRequest *request){
    request->send(200, "text/html", index_html, processor);
  });

  // Start server
  server.begin();

loop 只干两件事:把 ledState 物理写到 LED 上,以及定期清理连接。那句 cleanupClients 后面单独说,它是个隐藏的保命开关:

void loop() {
  ws.cleanupClients();
  digitalWrite(ledPin, ledState);
}

浏览器侧:一小段 JS 维持长连接

客户端逻辑写在页面内嵌的 script 里,代码不长。gateway 用 window.location.hostname 拼出来,浏览器访问的地址本来就是 ESP32 的地址,直接复用就行。onClose 里有个很实用的写法:连接一旦断开,setTimeout 两秒后自动重连,不用人工干预:

  var gateway = `ws://${window.location.hostname}/ws`;
  var websocket;
  window.addEventListener('load', onLoad);
  function initWebSocket() {
    console.log('Trying to open a WebSocket connection...');
    websocket = new WebSocket(gateway);
    websocket.onopen    = onOpen;
    websocket.onclose   = onClose;
    websocket.onmessage = onMessage; // <-- add this line
  }
  function onOpen(event) {
    console.log('Connection opened');
  }
  function onClose(event) {
    console.log('Connection closed');
    setTimeout(initWebSocket, 2000);
  }
  function onMessage(event) {
    var state;
    if (event.data == "1"){
      state = "ON";
    }
    else{
      state = "OFF";
    }
    document.getElementById('state').innerHTML = state;
  }
  function onLoad(event) {
    initWebSocket();
    initButton();
  }
  function initButton() {
    document.getElementById('button').addEventListener('click', toggle);
  }
  function toggle(){
    websocket.send('toggle');
  }

onMessage 处理服务器推来的 1 或 0,转成 ON 或 OFF 写进那个 id 为 state 的元素。点按钮时 toggle() 只做一件事:websocket.send('toggle')。发什么字符串是两端自己约定的,两边对上就行,底稿这里用的是一个单词。

跑起来,以及三个坑

烧录后打开串口监视器,波特率 115200,按一下板子上的 EN/RST 键,ESP32 的 IP 地址会打印出来。浏览器访问这个 IP 就能看到控制页。页面打不开的话,先回串口确认 WiFi 有没有连上——另外一个高频翻车点是路由器的频段,ESP32 只支持 2.4GHz,连 5G 频段的 SSID 是永远等不到 Connecting 成功的:

ESP32 WebSocket网页控制界面

多开几个标签页,或者换台设备访问同一个地址:任何一处点了 Toggle,所有页面的状态会一起变,这就是开头说的全员广播:

多客户端状态同步演示

翻完这篇教程,有三个坑值得提前说。

坑一,访问方式。底稿直接用 IP 地址访问,没有上 mDNS。想在局域网里用 xxx.local 这种好记的域名,得额外加载 ESPmDNS,而且部分手机浏览器对 .local 域名的解析并不可靠。新手建议先用 IP 把流程跑通,域名的事以后再说。

坑二,消息帧。那四个帧校验条件别嫌啰嗦就删掉,它们保证拿到的是一条完整的文本帧;data[len] = 0 也一样,是给 strcmp 用的收尾。以后想传复杂点的数据,比如 JSON,这套单帧判断照样适用,只是解析那边要多做一步。

坑三,多客户端的资源泄漏。loop 里那句 ws.cleanupClients() 不是摆设。库维护者在 GitHub 页面解释过:浏览器有时并不会真正关闭 WebSocket 连接,哪怕 JS 里调了 close(),积累下来会把服务器资源耗尽直接崩掉;在 loop 里定期调 cleanupClients(),超过上限时关掉最老的连接就能兜住。每一圈都调没问题,想省电就控制在一秒一次。

什么时候值得上 WebSocket?底稿这个场景已经给出答案:只要服务器主动通知客户端是刚需——多端同步、状态实时刷新——就该用它。反过来,只是偶尔点一下开关,HTTP 轮询那套简单可靠,没必要上长连接。再往上一层还有 MQTT,适合跨网络、多主题的消息分发,站里今天也发过一篇实操。三套方案不冲突,按场景挑就行。

这套例子的完整工程代码(含网页模板全部内容)在 Random Nerd Tutorials 的 WebSocket 教程页可以直接复制,对照着读会更顺。GPIO 2 换成继电器或者其他输出,就是一个能多端同步的家居控制开关——对上班族玩家来说,周末一个下午足够把它跑通。


作者:工位上的小周
链接:https://www.aiddithome.com/p/5b5622f928e9a.html
本作版权归作者所有,未经允许请勿转载。若存在违规行为,您可以点击 “举报”。


登录 后发表评论
5条评论
拆机党
1楼 · 2026-11-16 13:33:45

这个例子里帧校验那四个条件看着啰嗦,其实是保命的。之前用别的库收 WebSocket 消息,客户端一次发长一点的数据就被拆帧,strcmp 比较老出错,后来才明白要判断 final 和 len 是不是完整单帧。还有 loop 里那个 cleanupClients 确实不能省,测试时开了十几个标签页挂一晚上,第二天串口就刷连接异常,加上这句之后稳多了。新手照抄的时候别嫌这两处麻烦就删掉。

调参到凌晨
2楼 · 2026-11-16 13:33:45

两秒自动重连那个细节很实用,WiFi 抽风的时候页面自己就缓过来了。

周五下班搞一搞
3楼 · 2026-11-16 13:33:45

ESP32 连 5G 频段这个坑我踩过,等半天连不上还以为是板子坏了,其实换个 2.4G 的 SSID 就好。

板砖搬不动
4楼 · 2026-11-16 13:33:45

WebSocket 和 MQTT 的边界讲得挺清楚,局域网玩多端同步确实没必要上 broker,长连接加广播就够了。

默默点赞的路人
5楼 · 2026-11-16 13:33:45

周末正好有块 ESP32 在抽屉吃灰,下午就照这个跑一遍。