4. SoftAP配网实战

SoftAP（Soft Access Point）配网是 ESP32 最经典、最可靠的本地配网方式之一。它的核心思路是：设备在未联网时主动变成一个 Wi-Fi 热点，手机连接该热点后，通过浏览器访问设备内置的 Web 页面，把目标路由器的 SSID 和密码提交给 ESP32，设备再以 STA 模式连接目标路由器，最后把结果反馈给手机。整个过程不依赖任何外部服务器，适合首次上电、无屏设备、售后现场等场景。

一、核心原理：AP 与 STA 的共存与切换

ESP32 的 Wi-Fi 模块支持 AP、STA 以及 AP+STA 共存三种模式。SoftAP 配网通常采用“先 AP，后 STA”的策略：设备启动后进入 AP 模式，广播一个固定 SSID（如 ESP32_Config），手机连接后获得由 ESP32 分配的 IP（默认网关通常是 192.168.4.1）。此时手机与 ESP32 处于同一局域网，浏览器访问 http://192.168.4.1 即可打开配网页面。

当用户提交 SSID 和密码后，ESP32 调用 WiFi.begin(ssid, password) 尝试连接目标路由器。若连接成功，设备获得路由器分配的 IP，并可通过 mDNS 或固定 IP 被访问；若失败，则回到 AP 模式等待重新提交。这里的关键是：AP 与 STA 不能同时使用同一信道冲突，实际开发中常采用“提交后关闭 AP、切换 STA”或“AP+STA 共存但以 STA 为主”两种方案。

二、AP 模式配置：从热点到可访问服务

AP 模式配置的核心是设置热点参数并启动服务。典型代码如下：

#include <WiFi.h>
#include <WebServer.h>

const char* AP_SSID = "ESP32_Config";
const char* AP_PASS = "12345678";   // 至少 8 位
WebServer server(80);

void setup() {
  Serial.begin(115200);
  WiFi.mode(WIFI_AP);
  WiFi.softAP(AP_SSID, AP_PASS);
  Serial.print("AP IP: ");
  Serial.println(WiFi.softAPIP());   // 192.168.4.1

  server.on("/", handleRoot);
  server.on("/submit", HTTP_POST, handleSubmit);
  server.begin();
}

void loop() {
  server.handleClient();
}

这里有几个容易忽略的细节：第一，WiFi.softAP() 的密码长度必须为 8~63 位，否则热点启动失败；第二，AP 的 IP 默认是 192.168.4.1，但可以通过 WiFi.softAPConfig() 自定义；第三，若设备同时需要 STA 连接，建议使用 WIFI_AP_STA 模式，避免切换时服务中断。

三、Web 服务器搭建：表单与路由设计

Web 服务器负责向手机返回配网页面，并接收表单提交。页面通常包含 SSID 输入框、密码输入框和提交按钮。为了提升体验，可以扫描周围 Wi-Fi 并以下拉列表展示：

String page = "<form action='/submit' method='POST'>"
  "SSID: <input name='ssid'><br>"
  "PASS: <input name='pass' type='password'><br>"
  "<input type='submit' value='连接'></form>";

void handleRoot() {
  server.send(200, "text/html", page);
}

void handleSubmit() {
  String ssid = server.arg("ssid");
  String pass = server.arg("pass");
  // 保存到 NVS，并尝试连接
  WiFi.begin(ssid.c_str(), pass.c_str());
  server.send(200, "text/html", "正在连接，请稍候...");
}

路由设计上，建议至少提供 /（配网页）、/submit（提交处理）、/status（查询连接状态）三个端点。若使用 ESPAsyncWebServer，还能支持 WebSocket 实时推送状态，避免手机反复刷新。

四、手机连接与参数提交：真实场景与常见问题

手机连接 ESP32_Config 后，部分系统会提示“无互联网连接”，这是正常现象，因为该热点没有外网出口。用户需要手动选择“保持连接”。随后在浏览器输入 192.168.4.1，若无法打开，常见原因包括：手机自动切换回移动数据、浏览器使用了 HTTPS 强制跳转、或 ESP32 的 Web 服务未启动。

五、配网结果反馈：让用户知道成功还是失败

提交后，ESP32 需要把连接结果反馈给手机。最简单的方式是在 /submit 返回一个“正在连接”页面，然后通过 /status 轮询或 WebSocket 推送最终结果。反馈内容应包含：目标 SSID、连接状态（成功/失败）、获取到的 IP、失败原因（密码错误、超时、未找到 AP）。

六、误区与复盘

• 误区一：AP 密码留空。部分手机无法连接开放热点，建议至少设置 8 位密码。
• 误区二：提交后立即关闭 AP。若 STA 连接失败，手机将无法收到反馈，也无法重新配网。建议先反馈结果，再决定是否关闭 AP。
• 误区三：不保存凭据。配网成功后应将 SSID 和密码写入 NVS，下次上电直接尝试 STA 连接，失败后再启动 AP。
• 误区四：忽略 DNS 劫持。部分手机访问 192.168.4.1 不便，可启动 DNSServer 把所有域名解析到 AP IP，实现“连上即弹窗”。

整体来看，SoftAP 配网的稳定性取决于三个关键点：AP 热点参数正确、Web 服务路由完整、状态反馈及时。把这三点做好，手机端体验会非常顺畅，也为后续远程诊断和 OTA 升级打下基础。