1. 项目缘起：当“三行代码”遇到ESP8266
如果你玩过Arduino，或者对物联网有点兴趣，大概率听说过ESP8266这颗神奇的WiFi芯片。它便宜、小巧，却内置了完整的TCP/IP协议栈，让单片机轻松连上网络。很多人的第一个物联网项目，可能就是用它点个灯，或者读取个温湿度数据上报到云端。但不知道你有没有想过，能不能让这个小小的芯片，直接变成一个能通过浏览器访问的Web服务器？
这个想法听起来有点“超纲”。传统的Web服务器，像Apache、Nginx，那都是运行在性能强大的电脑或服务器上的庞然大物。而ESP8266，内存以KB计，主频也就几十到一百多兆赫兹，让它来承载复杂的网页逻辑，似乎有点天方夜谭。但恰恰是这种“以小博大”的挑战，催生了许多极简的解决方案。今天要聊的，就是其中一种号称“三行代码”就能搞定的玩法。当然，这里的“三行”更多是一种营销话术，它背后隐藏的是一个精心封装的库——InqPortal。这个库的目标，就是让为ESP8266（以及后来的ESP32）创建一个功能丰富的Web服务器，变得像调用几个简单函数一样容易。
我第一次接触这个想法，是在一个开源硬件社区。当时我需要为一个传感器数据采集板做一个简单的配置界面，不想折腾复杂的手机App，也不想依赖额外的中控电脑。最理想的方式，就是设备自己开一个WiFi热点，我用手机连上去，打开浏览器就能设置参数、查看实时数据。这本质上就是一个Web服务器。如果从头实现，我需要处理TCP连接、解析HTTP协议、管理多客户端、渲染HTML页面……光是想想就头大。而InqPortal这类库，把这些脏活累活都打包好了，暴露给开发者的，就是一个极其简洁的API。这不仅仅是省了几行代码，更是把开发心智从底层协议细节中解放出来，让你能专注于业务逻辑本身。
所以，这篇文章我们就来深挖一下，用ESP8266和Arduino环境，如何真正快速地搭建一个实用的Web服务器。我们会从最基础的“三行代码”Demo开始，拆解其背后的原理，然后一步步把它扩展成一个能处理表单、显示动态数据、甚至提供文件下载的实用工具。过程中，我会分享我实际调试时遇到的坑，比如内存不足导致的重启、长连接下的稳定性问题，以及如何优化页面响应速度。无论你是想快速做个设备调试界面，还是为你的智能家居项目添加一个本地控制面板，相信这些经验都能帮到你。
2. 环境搭建与InqPortal库初探
在开始写那“三行代码”之前，我们得先把舞台搭好。整个项目的核心是Arduino IDE和ESP8266开发板。如果你还没接触过，别担心，这个过程现在非常友好。
2.1 硬件与软件准备
首先，你需要一块ESP8266开发板。市面上最常见的是NodeMCU和Wemos D1 mini，它们都集成了USB转串口芯片，用一根Micro-USB线就能连接电脑，非常方便。我手头用的是一块NodeMCU，它的引脚丰富，兼容Arduino Uno的 shield，可玩性很高。
软件方面，首要任务是安装Arduino IDE。建议直接从官网下载最新版本。安装好后，默认是不支持ESP8266的，我们需要添加开发板支持。打开Arduino IDE，进入“文件”->“首选项”，在“附加开发板管理器网址”里填入以下地址：http://arduino.esp8266.com/stable/package_esp8266com_index.json然后点击“确定”。接着，打开“工具”->“开发板”->“开发板管理器”，搜索“esp8266”，找到由“ESP8266 Community”提供的包，点击安装。这个过程可能会有点慢，取决于你的网络环境。
安装完成后，在“工具”->“开发板”下拉菜单里，就能看到一大堆ESP8266的板子了。根据你手头的硬件选择，比如我用的NodeMCU 1.0，就选择“NodeMCU 1.0 (ESP-12E Module)”。同时，记得在“工具”菜单里把上传速度（Upload Speed）设置为“115200”，端口（Port）选择你电脑识别到的那个COM口（Windows）或/dev/ttyUSB*（Linux/Mac）。
接下来是主角——InqPortal库。打开“工具”->“管理库…”，在库管理器中搜索“InqPortal”。你应该能找到它，直接点击安装即可。这个库的作者做了很好的封装，我们后面会看到，它甚至内置了一个轻量级的文件系统（SPIFFS）支持，用于存放网页文件。
2.2 理解InqPortal的“三行代码”本质
现在，让我们来看看传说中的“三行代码”到底长什么样。新建一个Arduino项目，输入以下代码：
#include <InqPortal.h> InqPortal svr; void setup() { svr.begin(); } void loop() { svr.process(); }对，就这些。编译并上传到你的ESP8266。上传成功后，打开串口监视器（波特率设为115200），你会看到类似这样的输出：
InqPortal Started... AP IP address: 192.168.4.1这说明你的ESP8266已经启动了一个WiFi接入点（Access Point），其IP地址是192.168.4.1。现在，用你的手机或电脑，搜索WiFi网络，你会找到一个名字类似“InqPortal-XXXXXX”的热点，连接它（通常没有密码）。然后，打开浏览器，输入http://192.168.4.1，砰！一个Web管理页面应该就出现了。
这看起来非常神奇，但我们必须拆开这个“黑箱”看看。这三行代码的每一行，背后都对应着大量的工作：
#include <InqPortal.h>：这引入了整个InqPortal框架。这个头文件背后，包含了WiFi管理、HTTP服务器、WebSocket支持、文件系统接口等一系列模块。InqPortal svr;：实例化一个InqPortal服务器对象。在构造函数里，库已经完成了默认参数的设置，比如AP的SSID命名规则、Web服务器的端口号（默认为80）等。svr.begin();：在setup()函数中调用这个方法，是启动的关键。它依次执行了：初始化SPIFFS文件系统（如果可用）、启动WiFi AP模式、启动DNS服务器（用于捕获所有域名请求，实现“门户”效果）、启动HTTP和WebSocket服务器。svr.process();：在loop()函数中不断调用。这是库的事件循环核心。它负责检查是否有新的网络连接、处理已接收到的HTTP请求、维护WebSocket连接、执行后台任务等。如果没有这个持续的过程，服务器就无法响应客户端请求。
所以，“三行代码”是一个高度抽象的结果。它用合理的默认配置，掩盖了所有繁琐的初始化步骤，让你瞬间获得一个可用的Web服务器。这对于快速原型验证、概念演示来说，威力巨大。但当我们想做一个更定制化的项目时，就必须深入了解这些默认配置，并学会如何去覆盖它们。
3. 从Demo到实用：配置与定制化开发
默认的AP模式虽然方便，但很多时候我们希望设备能连接到家里现有的WiFi网络（Station模式），这样手机和ESP8266都在同一个局域网内，访问更稳定，也不影响手机上网。同时，那个自动生成的SSID名字，我们也希望能改成自己项目相关的。
3.1 配置WiFi模式与凭据
InqPortal提供了非常灵活的方式来配置这些参数。我们可以修改代码，在svr.begin()之前进行配置：
#include <InqPortal.h> InqPortal svr; void setup() { // 设置工作在Station模式，并指定要连接的WiFi名称和密码 svr.setWiFiMode(INQ_STATION); // 设置为STA模式 svr.setWiFiCredentials("Your_WiFi_SSID", "Your_WiFi_Password"); // 如果你想同时开启AP模式作为备用（比如配网失败时），可以使用AP_STA模式 // svr.setWiFiMode(INQ_AP_STA); // svr.setAPCredentials("MyDeviceAP", NULL); // AP名为MyDeviceAP，无密码 svr.begin(); } void loop() { svr.process(); }上传这段代码后，ESP8266会尝试连接你指定的WiFi。串口输出会显示连接过程，成功后会打印出它从路由器获取到的IP地址，比如192.168.1.105。此时，你用同一局域网内的设备访问这个IP地址，就能打开Web界面。
这里有个非常重要的实践细节：硬编码WiFi密码在代码里是不安全也不灵活的。对于需要分发给别人的产品，你不能要求每个用户都去改代码、重新编译。因此，InqPortal（以及很多其他物联网框架）都实现了“智能配网”功能。通常的做法是：设备第一次启动时，如果找不到已知的WiFi，会进入AP模式，提供一个配置页面，让用户用手机连接设备热点，在页面上选择家庭WiFi并输入密码。设备保存这些凭证后，下次启动就会自动连接。InqPortal库也内置了类似的机制，通过svr.enableWiFiManager()之类的函数可以启用，但这通常需要更多的代码和页面配合，超出了“三行”的范畴，却是产品化必不可少的一步。
3.2 添加自定义的Web API端点
默认的Web页面是库自带的，显示一些系统信息。但我们肯定需要添加自己的页面和功能。InqPortal允许你非常方便地添加“API端点”（Endpoint）。你可以把它理解为一个URL路径，当浏览器访问这个路径时，由你指定的一段代码来响应。
假设我们想添加一个简单的LED控制功能。ESP8266开发板上通常有一个板载LED，连接到GPIO2（NodeMCU上对应D4引脚）。我们创建一个控制它的API：
#include <InqPortal.h> InqPortal svr; // 声明一个处理函数，用于响应 /api/led 的请求 void handleLED(InqPortalRequest &req) { // req是一个请求对象，包含了客户端传来的信息 String state = req.getArg("state"); // 获取URL查询参数，例如 ?state=on if (state == "on") { digitalWrite(2, LOW); // NodeMCU板载LED是低电平点亮 req.send(200, "text/plain", "LED is ON"); } else if (state == "off") { digitalWrite(2, HIGH); req.send(200, "text/plain", "LED is OFF"); } else { req.send(400, "text/plain", "Bad Request: use state=on or state=off"); } } void setup() { pinMode(2, OUTPUT); digitalWrite(2, HIGH); // 初始状态熄灭 svr.begin(); // 将处理函数绑定到特定的URL路径上 svr.on("/api/led", HTTP_GET, handleLED); } void loop() { svr.process(); }在这段代码里，我们做了几件事：
- 定义了
handleLED函数，它接收一个InqPortalRequest对象。从这个对象里，我们可以解析客户端通过URL传递的参数（req.getArg）。 - 根据参数值控制GPIO2的电平，并通过
req.send方法向客户端返回一个简单的文本响应。200是HTTP状态码（成功），400表示客户端请求有误。 - 在
setup()中，通过svr.on方法，将这个处理函数注册到路径/api/led上，并且指定只响应HTTP GET请求。
现在，编译上传代码。设备启动后，你可以在浏览器地址栏输入：http://[设备IP]/api/led?state=on页面会显示“LED is ON”，同时板子上的LED应该被点亮。访问state=off则会熄灭它。这就实现了一个最基本的远程控制API。
3.3 提供完整的HTML页面
返回纯文本的API对于机器交互很方便，但对于人机界面就不够友好了。我们更希望有一个漂亮的网页按钮来控制LED。这就需要服务器能够返回HTML页面。InqPortal支持从SPIFFS文件系统中读取文件并发送给客户端。
首先，我们需要将网页文件上传到ESP8266的SPIFFS中。Arduino IDE安装ESP8266开发板支持后，通常会附带一个“ESP8266 Sketch Data Upload”工具。你需要先安装这个工具：在Arduino IDE中，点击“工具”->“ESP8266 Sketch Data Upload”->“安装”。安装完成后，在存放你当前.ino项目的目录下，新建一个名为data的文件夹。在这个data文件夹里，我们创建一个简单的HTML文件，比如叫index.html：
<!DOCTYPE html> <html> <head> <title>ESP8266 LED Control</title> <meta name="viewport" content="width=device-width, initial-scale=1"> <style> body { font-family: Arial; text-align: center; margin-top: 50px; } button { padding: 15px 30px; font-size: 18px; margin: 10px; } .on { background-color: green; color: white; } .off { background-color: red; color: white; } </style> </head> <body> <h1>Control the LED</h1> <button id="btnOn" class="on" onclick="controlLED('on')">Turn ON</button> <button id="btnOff" class="off" onclick="controlLED('off')">Turn OFF</button> <p id="status">Status: Ready</p> <script> function controlLED(state) { document.getElementById('status').innerText = 'Status: Sending command...'; fetch('/api/led?state=' + state) .then(response => response.text()) .then(data => { document.getElementById('status').innerText = 'Status: ' + data; }) .catch(error => { document.getElementById('status').innerText = 'Status: Error!'; console.error('Error:', error); }); } </script> </body> </html>这个页面有两个按钮，点击时会调用JavaScript的fetch函数，向我们的/api/ledAPI发送请求，并更新状态文字。
然后，回到Arduino IDE，确保当前项目窗口是激活的，点击“工具”->“ESP8266 Sketch Data Upload”->“上传”。这会将data文件夹下的所有文件写入ESP8266的SPIFFS文件系统。
接下来，我们需要修改Arduino代码，让服务器能够响应对根路径/的请求，并返回这个index.html文件，同时保留我们的/api/led接口：
#include <InqPortal.h> #include <FS.h> // 需要包含FS库来操作文件系统 InqPortal svr; void handleLED(InqPortalRequest &req) { String state = req.getArg("state"); if (state == "on") { digitalWrite(2, LOW); req.send(200, "text/plain", "LED turned ON"); } else if (state == "off") { digitalWrite(2, HIGH); req.send(200, "text/plain", "LED turned OFF"); } else { req.send(400, "text/plain", "Bad Request"); } } // 处理根路径请求，发送index.html void handleRoot(InqPortalRequest &req) { File file = SPIFFS.open("/index.html", "r"); if (!file) { req.send(500, "text/plain", "Failed to open file"); return; } // 流式传输文件内容，节省内存 req.streamFile(file, "text/html"); file.close(); } void setup() { Serial.begin(115200); pinMode(2, OUTPUT); digitalWrite(2, HIGH); // 初始化SPIFFS文件系统 if (!SPIFFS.begin()) { Serial.println("SPIFFS Mount Failed"); return; } svr.begin(); // 注册路由 svr.on("/", HTTP_GET, handleRoot); // 根路径返回网页 svr.on("/api/led", HTTP_GET, handleLED); // API路径 } void loop() { svr.process(); }重新上传代码。现在，当你访问设备的IP地址时，会看到一个带有按钮的控制页面，点击按钮可以控制LED，并且页面会动态更新状态。这就构成了一个完整的、前后端分离的微型Web应用。前端是静态HTML/CSS/JavaScript，后端是运行在ESP8266上的InqPortal服务器，通过简单的API进行通信。
4. 深入核心：InqPortal如何处理并发与内存
玩到这里，你可能已经觉得这很简单。但当我们试图增加功能，比如同时读取多个传感器数据并在网页上实时显示时，挑战就来了。ESP8266的资源极其有限，典型的只有80KB的RAM可供用户程序使用。一个HTTP请求的头部、一个HTML页面、几个变量，很容易就把内存消耗殆尽，导致设备重启（看门狗复位）。
4.1 理解服务器的单线程事件循环
InqPortal和大多数Arduino上的网络库一样，采用单线程事件驱动模型。这意味着svr.process()这个函数必须在loop()中尽可能频繁地被调用。它内部会检查网络套接字的状态，如果有数据到达，就读取、解析，然后调用你注册的处理函数（如handleLED或handleRoot）。你的处理函数必须尽快执行完毕并返回，否则就会阻塞整个事件循环，导致服务器无法响应其他客户端的请求，甚至网络连接超时。
注意：绝对不要在
handleRoot或handleLED这类请求处理函数中进行长时间的delay()操作，或者执行非常耗时的计算（比如复杂的数学运算、长时间的传感器读取）。如果需要做耗时操作，应该将其分解成非阻塞的、状态机驱动的代码片段，在loop()中分步执行。
4.2 内存优化实战技巧
内存是ESP8266上最宝贵的资源。以下是我在实际项目中总结的几个关键优化点：
1. 使用PROGMEM存储常量字符串：HTML、CSS、JavaScript代码作为字符串常量，默认是存放在RAM中的。对于大一点的页面，这会是巨大的开销。Arduino环境提供了PROGMEM关键字，可以将常量数据存放在Flash中，仅在需要时读取到RAM。
// 不推荐：大字符串直接放在RAM const char indexHtml[] = "<!DOCTYPE html><html>...很长很长的HTML..."; // 推荐：使用PROGMEM存放在Flash const char indexHtml[] PROGMEM = R"rawliteral( <!DOCTYPE html> <html> ...很长很长的HTML... </html> )rawliteral"; void handleRoot(InqPortalRequest &req) { // 发送时需要使用特殊函数从Flash读取 req.send_P(200, "text/html", indexHtml); }InqPortal的req.send_P方法就是用来发送存放在PROGMEM中的内容的。对于复杂的页面，这能节省出数十KB的RAM。
2. 流式传输大文件：前面的例子中，我们使用req.streamFile来发送文件。这是最佳实践，因为它不会一次性将整个文件读入内存，而是分块读取、分块发送。对于存储在SPIFFS中的文件，务必使用这种方法。
3. 谨慎使用String类：Arduino的String类虽然方便，但动态内存分配容易产生碎片，在长期运行后可能导致内存不足。在性能关键或内存紧张的区域，可以考虑使用C风格的字符数组（char[]）和标准库函数。在请求处理函数中，解析参数、拼接响应时尤其要注意。
4. 监控内存使用：在开发过程中，定期打印剩余内存有助于发现内存泄漏。
void loop() { svr.process(); static unsigned long lastPrint = 0; if (millis() - lastPrint > 5000) { // 每5秒打印一次 Serial.printf("Free Heap: %d bytes\n", ESP.getFreeHeap()); lastPrint = millis(); } }如果发现Free Heap持续下降且不回升，很可能存在内存泄漏。
4.3 处理多个并发请求与连接管理
ESP8266的硬件网络栈可以维护多个并发的TCP连接（通常5个左右）。InqPortal会管理这些连接。但是，你的处理函数是顺序执行的。如果handleRoot函数因为读取大文件而稍微慢了一点，那么后续的/api/led请求就必须等待。因此，保持处理函数轻快至关重要。
对于需要实时更新数据的场景（比如网页上显示传感器实时曲线），频繁地轮询API（每隔一秒发一个GET请求）并不是高效的做法。这会占用连接资源，增加服务器负担。更好的方式是使用WebSocket。WebSocket在客户端和服务器之间建立一个全双工的持久连接，数据可以随时从任一端推送，避免了HTTP轮询的开销和延迟。InqPortal库也内置了WebSocket支持，允许你建立实时数据通道。当传感器有新数据时，服务器可以主动推送给所有已连接的网页客户端，实现真正的实时更新。这部分代码相对复杂一些，需要处理连接建立、消息收发等事件，但对于数据仪表盘类的应用，性能提升是质的飞跃。
5. 项目进阶：构建一个传感器数据监控面板
现在，让我们把前面学到的所有东西组合起来，构建一个更实用的项目：一个通过网页实时显示温湿度传感器数据的监控面板。我们将使用常见的DHT11传感器，并通过WebSocket将数据推送到网页前端。
5.1 硬件连接与传感器库
首先，将DHT11传感器连接到ESP8266。DHT11有三个引脚（有些是四个，但其中一个是空脚）：
- VCC 接 3.3V
- GND 接 GND
- DATA 接 GPIO5 (NodeMCU的D1引脚)
我们需要安装DHT sensor library。在Arduino库管理中搜索“DHT sensor library by Adafruit”并安装。
5.2 后端代码：集成传感器与WebSocket
Arduino代码如下。这段代码比之前复杂，因为它融合了WiFi连接、HTTP服务器、WebSocket服务器、文件服务和传感器读取。
#include <InqPortal.h> #include <FS.h> #include <WebSocketsServer.h> // InqPortal内部可能封装了，这里显式引入 #include <DHT.h> #define DHTPIN 5 // GPIO5 #define DHTTYPE DHT11 DHT dht(DHTPIN, DHTTYPE); InqPortal svr; WebSocketsServer webSocket = WebSocketsServer(81); // WebSocket运行在81端口 float temperature = 0.0; float humidity = 0.0; unsigned long lastSensorRead = 0; const long sensorInterval = 2000; // 每2秒读取一次传感器 // 处理根路径，返回网页 void handleRoot(InqPortalRequest &req) { File file = SPIFFS.open("/sensor_panel.html", "r"); if (file) { req.streamFile(file, "text/html"); file.close(); } else { req.send(500, "text/plain", "Failed to load page"); } } // WebSocket事件处理函数 void webSocketEvent(uint8_t num, WStype_t type, uint8_t * payload, size_t length) { switch(type) { case WStype_DISCONNECTED: Serial.printf("[%u] Disconnected!\n", num); break; case WStype_CONNECTED: { // 当新客户端连接时，立即发送一次当前数据 IPAddress ip = webSocket.remoteIP(num); Serial.printf("[%u] Connected from %d.%d.%d.%d\n", num, ip[0], ip[1], ip[2], ip[3]); String jsonData = "{\"temp\":" + String(temperature) + ",\"humi\":" + String(humidity) + "}"; webSocket.sendTXT(num, jsonData); } break; case WStype_TEXT: // 可以处理从前端发来的消息，这里我们不需要 break; } } void setup() { Serial.begin(115200); dht.begin(); // 初始化文件系统 if (!SPIFFS.begin()) { Serial.println("SPIFFS Mount Failed"); return; } // 配置WiFi（Station模式） svr.setWiFiMode(INQ_STATION); svr.setWiFiCredentials("Your_WiFi_SSID", "Your_WiFi_Password"); svr.begin(); // 启动WebSocket服务器 webSocket.begin(); webSocket.onEvent(webSocketEvent); // 注册HTTP路由 svr.on("/", HTTP_GET, handleRoot); // 可以添加一个简单的JSON API供备用 svr.on("/api/data", HTTP_GET, [](InqPortalRequest &req) { String json = "{\"temperature\":" + String(temperature) + ",\"humidity\":" + String(humidity) + "}"; req.send(200, "application/json", json); }); Serial.println("Server started"); } void loop() { svr.process(); // 处理HTTP请求 webSocket.loop(); // 处理WebSocket事件 // 定时读取传感器数据 unsigned long now = millis(); if (now - lastSensorRead > sensorInterval) { lastSensorRead = now; float h = dht.readHumidity(); float t = dht.readTemperature(); // 检查读数是否有效 if (isnan(h) || isnan(t)) { Serial.println("Failed to read from DHT sensor!"); return; } temperature = t; humidity = h; Serial.printf("Temperature: %.2f °C, Humidity: %.2f %%\n", temperature, humidity); // 广播新数据给所有WebSocket客户端 String jsonData = "{\"temp\":" + String(temperature) + ",\"humi\":" + String(humidity) + "}"; webSocket.broadcastTXT(jsonData); } }5.3 前端页面：使用Chart.js绘制实时图表
我们需要创建一个更复杂的前端页面sensor_panel.html，放入data文件夹。这个页面将使用Chart.js库来绘制实时曲线图。
<!DOCTYPE html> <html> <head> <title>ESP8266 Sensor Monitor</title> <meta name="viewport" content="width=device-width, initial-scale=1"> <script src="https://cdn.jsdelivr.net/npm/chart.js"></script> <style> body { font-family: sans-serif; margin: 20px; } .container { display: flex; flex-wrap: wrap; gap: 20px; } .card { background: #f5f5f5; padding: 20px; border-radius: 10px; flex-grow: 1; min-width: 300px; } .value { font-size: 2.5em; font-weight: bold; text-align: center; margin: 10px 0; } .temp { color: #e74c3c; } .humi { color: #3498db; } canvas { max-width: 100%; } </style> </head> <body> <h1>🌡️ Real-Time Sensor Dashboard</h1> <div class="container"> <div class="card"> <h2>Temperature</h2> <div id="tempValue" class="value temp">--.- °C</div> </div> <div class="card"> <h2>Humidity</h2> <div id="humiValue" class="value humi">--.- %</div> </div> </div> <div class="card"> <h2>Trend Chart (Last 2 Minutes)</h2> <canvas id="sensorChart"></canvas> </div> <script> // 初始化WebSocket连接 const ws = new WebSocket('ws://' + window.location.hostname + ':81/'); const tempCtx = document.getElementById('tempValue'); const humiCtx = document.getElementById('humiValue'); const chartCtx = document.getElementById('sensorChart').getContext('2d'); // 配置Chart.js const chart = new Chart(chartCtx, { type: 'line', data: { labels: [], // 时间标签 datasets: [ { label: 'Temperature (°C)', borderColor: '#e74c3c', backgroundColor: 'rgba(231, 76, 60, 0.1)', data: [], yAxisID: 'y', }, { label: 'Humidity (%)', borderColor: '#3498db', backgroundColor: 'rgba(52, 152, 219, 0.1)', data: [], yAxisID: 'y1', } ] }, options: { responsive: true, interaction: { mode: 'index', intersect: false }, scales: { x: { title: { display: true, text: 'Time' } }, y: { type: 'linear', display: true, position: 'left', title: { display: true, text: 'Temperature (°C)' }, min: 10, max: 40 }, y1: { type: 'linear', display: true, position: 'right', title: { display: true, text: 'Humidity (%)' }, min: 20, max: 80, grid: { drawOnChartArea: false } } } } }); // 保留最近120个数据点（2分钟，每秒一个点） const maxDataPoints = 120; let timeCounter = 0; ws.onmessage = function(event) { const data = JSON.parse(event.data); const temp = data.temp.toFixed(1); const humi = data.humi.toFixed(1); // 更新数值显示 tempCtx.textContent = temp + ' °C'; humiCtx.textContent = humi + ' %'; // 更新图表 const now = new Date().toLocaleTimeString(); chart.data.labels.push(now); chart.data.datasets[0].data.push(data.temp); chart.data.datasets[1].data.push(data.humi); // 保持数据量不超过最大值 if (chart.data.labels.length > maxDataPoints) { chart.data.labels.shift(); chart.data.datasets[0].data.shift(); chart.data.datasets[1].data.shift(); } chart.update(); }; ws.onerror = function(error) { console.error('WebSocket Error:', error); tempCtx.textContent = 'Connection Error'; humiCtx.textContent = 'Connection Error'; }; // 备用方案：如果WebSocket失败，尝试使用HTTP轮询（每5秒） function fallbackPolling() { fetch('/api/data') .then(response => response.json()) .then(data => { tempCtx.textContent = data.temperature.toFixed(1) + ' °C'; humiCtx.textContent = data.humidity.toFixed(1) + ' %'; }) .catch(err => console.error('Polling failed:', err)); } // 初始连接失败后启动轮询 ws.onclose = function() { console.log('WebSocket closed, starting fallback polling.'); setInterval(fallbackPolling, 5000); fallbackPolling(); }; </script> </body> </html>5.4 部署与实测要点
将sensor_panel.html放入data文件夹，使用“ESP8266 Sketch Data Upload”工具上传。然后上传Arduino代码到设备。
设备启动连接WiFi后，记下串口打印的IP地址。在浏览器中访问该地址，你将看到一个包含实时数值和趋势图表的仪表盘。温度数据会每2秒通过WebSocket自动推送到网页，图表会动态更新。
在这个项目中，我们遇到了几个关键设计点：
- 双协议支持：我们同时提供了WebSocket（主）和HTTP API（备）两种数据获取方式。前端优先使用WebSocket实现低延迟推送，并在连接失败时自动降级为HTTP轮询。这提升了用户体验的鲁棒性。
- 前端资源外链：我们使用了CDN上的Chart.js，而不是将其打包进SPIFFS。这大大节省了ESP8266上宝贵的Flash空间，让它可以存储更重要的网页文件或程序代码。对于需要离线工作的场景，才需要考虑将库文件本地化。
- 资源管理：图表只保留最近2分钟的数据（120个点），防止前端内存无限增长。这是一个在资源受限的嵌入式设备和浏览器端都需要考虑的问题。
通过这个完整的项目，你已经超越了简单的“三行代码”Demo，构建了一个具有实用价值、考虑资源限制和用户体验的物联网Web服务器应用。它展示了如何将有限的硬件资源，通过合理的软件架构和库的支持，转化为一个功能相对丰富的网络服务节点。
