单片机与物联网 / 系统课时
搭建 Web 服务
搭建 Web 服务
ESP32 不只能访问服务器,也可以自己监听 HTTP 请求。本节在设备上启动一个局域网 Web 服务:浏览器访问首页,页面通过控制接口切换 GPIO,并能用 curl 独立验证接口。
学习目标
- 使用
WebServer注册网页路由和控制接口 - 在请求处理函数中读取参数、返回状态码与 JSON
- 从串口、浏览器和命令行三处验证局域网访问是否正常
服务结构
ESP32 连接路由器后获得局域网 IP,并在 80 端口监听请求。浏览器先获取 / 页面;点击按钮后,页面再请求 /api/led,处理函数更新 GPIO 状态并返回 JSON。

WebServer 是 ESP32 Arduino Core 自带的轻量 HTTP 服务类,适合设备配置页、局域网控制和小型调试接口。它不是面向高并发互联网流量设计的通用 Web 服务器。
注册页面和控制接口
下面程序默认使用 GPIO 2 作为输出脚。不同开发板的板载 LED 引脚或有效电平可能不同;若硬件定义不同,请修改 LED_PIN 和 digitalWrite() 的电平逻辑。
#include <WiFi.h>
#include <WebServer.h>
const char* WIFI_SSID = "<SSID>";
const char* WIFI_PASSWORD = "<PASSWORD>";
constexpr int LED_PIN = 2;
WebServer server(80);
bool ledOn = false;
const char INDEX_HTML[] PROGMEM = R"HTML(
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>ESP32 LED 控制</title>
</head>
<body>
<h1>ESP32 LED 控制</h1>
<button onclick="setLed('on')">打开</button>
<button onclick="setLed('off')">关闭</button>
<p id="status">等待操作</p>
<script>
async function setLed(state) {
const response = await fetch('/api/led?state=' + state);
document.getElementById('status').textContent =
await response.text();
}
</script>
</body>
</html>
)HTML";
void handleLed() {
if (!server.hasArg("state")) {
server.send(400, "application/json",
R"({"error":"missing state"})");
return;
}
String state = server.arg("state");
if (state != "on" && state != "off") {
server.send(400, "application/json",
R"({"error":"state must be on or off"})");
return;
}
ledOn = (state == "on");
digitalWrite(LED_PIN, ledOn ? HIGH : LOW);
String body = ledOn ? R"({"led":"on"})"
: R"({"led":"off"})";
server.send(200, "application/json", body);
}
void setup() {
Serial.begin(115200);
pinMode(LED_PIN, OUTPUT);
digitalWrite(LED_PIN, LOW);
WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
unsigned long startedAt = millis();
while (WiFi.status() != WL_CONNECTED &&
millis() - startedAt < 20000) {
delay(500);
Serial.print(".");
}
if (WiFi.status() != WL_CONNECTED) {
Serial.println("\nWi-Fi connect failed");
return;
}
server.on("/", HTTP_GET, []() {
server.send_P(200, "text/html; charset=utf-8", INDEX_HTML);
});
server.on("/api/led", HTTP_GET, handleLed);
server.onNotFound([]() {
server.send(404, "application/json",
R"({"error":"not found"})");
});
server.begin();
Serial.print("\nOpen: http://");
Serial.println(WiFi.localIP());
}
void loop() {
server.handleClient();
}预期输出
Open: http://<IP>上传并复位后,串口中的 <IP> 是路由器分配给 ESP32 的局域网地址。电脑或手机必须能访问同一局域网;在浏览器打开该地址,应看到“ESP32 LED 控制”页面。
验证控制接口
先把 <IP> 替换为串口显示的实际地址,再从同一局域网中的电脑执行:
curl "http://<IP>/api/led?state=on"预期输出
{"led":"on"}此时 GPIO 2 被设置为高电平。若请求改为 state=off,响应会变为 {"led":"off"},GPIO 恢复低电平;若省略 state 或传入其他值,接口会返回 400 和对应错误 JSON。
运行时注意点
server.handleClient() 必须在 loop() 中持续被调用,否则已建立的 Wi-Fi 连接仍在,但 HTTP 请求不会被及时处理。处理函数也应尽量短,不要在里面执行长时间阻塞操作,否则其他页面和接口会一起变慢。
这个示例适合可信局域网内的设备控制。若要跨公网访问,应增加身份认证、HTTPS、访问控制和更严格的输入校验,并优先通过受控网关或消息服务暴露设备能力,而不是直接把 ESP32 的 80 端口映射到互联网。