ESP32 Captive Portal 自动弹出原理

1. 功能概述

手机连接 ESP32 的 SoftAP 后，Android 或 iOS 会自动弹出配网页面。

这个页面并不是 ESP32 主动命令手机打开的，而是手机操作系统检测到当前 Wi-Fi 存在 Captive Portal 后，主动打开系统配网窗口。

当前实现结合了以下三种机制：

DHCP Option 114 声明配网页面地址。
DNS 劫持将所有域名解析到 ESP32。
HTTP Server 将未知路径重定向到配网页面。

2. 手机连接 Wi-Fi 后的行为

手机连接 Wi-Fi 后，通过 DHCP 获取以下网络参数：

IP 地址
子网掩码
默认网关
DNS Server
Captive Portal 地址

ESP32 SoftAP 通常分配：

手机地址：192.168.4.2
网关地址：192.168.4.1
DNS 地址：192.168.4.1

ESP32 还通过 DHCP Option 114 告诉手机：

Captive Portal URL = http://192.168.4.1/

支持 DHCP Option 114 的操作系统可以直接知道配网页面的地址。

3. 操作系统联网检测

手机连接 Wi-Fi 后，会主动访问操作系统预设的 HTTP 地址，判断当前网络是否能够访问互联网。

常见检测地址如下：

Android:
http://connectivitycheck.gstatic.com/generate_204

iOS:
http://captive.apple.com/hotspot-detect.html

Windows:
http://www.msftconnecttest.com/connecttest.txt

操作系统期望收到特定响应：

系统	预期响应
Android	HTTP 204 No Content
iOS	包含固定 `Success` 内容的页面
Windows	固定的文本内容

如果收到预期响应，系统认为网络可以正常访问互联网。

如果收到重定向、配网页面或其他内容，系统会认为当前网络需要进行网页登录认证。

4. DNS 劫持

ESP32 在 UDP 53 端口运行 DNS Server。

DNS Server 会将客户端发来的所有 IPv4 A 记录查询都解析为 SoftAP 地址：

任意域名 -> 192.168.4.1

例如手机查询：

connectivitycheck.gstatic.com

ESP32 返回：

connectivitycheck.gstatic.com -> 192.168.4.1

因此手机原本发往互联网的联网检测请求，最终会发送到 ESP32 的 HTTP Server。

5. HTTP 重定向

手机可能访问以下路径：

/generate_204
/hotspot-detect.html
/connecttest.txt

ESP32 当前只提供根路径：

当 HTTP Server 收到未注册的路径时，返回：

HTTP/1.1 303 See Other
Location: /

手机随后访问：

http://192.168.4.1/

ESP32 返回完整的配网页面。

6. 完整流程

手机连接 ESP32 SoftAP
        |
        v
通过 DHCP 获取 IP、网关和 DNS
        |
        v
DHCP Option 114 声明配网页面地址
        |
        v
手机发起系统联网检测
        |
        v
查询 connectivitycheck.gstatic.com 等域名
        |
        v
ESP32 DNS 返回 192.168.4.1
        |
        v
联网检测请求到达 ESP32 HTTP Server
        |
        v
未知路径返回 HTTP 303
        |
        v
重定向到根路径 /
        |
        v
ESP32 返回配网页面
        |
        v
系统判断当前 Wi-Fi 存在 Captive Portal
        |
        v
Android/iOS 自动弹出系统配网窗口

7. 各模块职责

DHCP Server

负责向客户端分配网络参数，并通过 Option 114 声明配网页面：

http://192.168.4.1/

Captive DNS Server

监听 UDP 53 端口，将所有 A 记录查询解析为：

192.168.4.1

HTTP Server

负责：

返回配网页面。
处理手机的联网检测请求。
将未知路径重定向到 /。

Android/iOS

负责：

主动检测网络连通性。
判断是否存在 Captive Portal。
打开系统配网窗口。
配网完成后重新检查互联网连接。

8. 为什么使用 HTTP 而不是 HTTPS

Captive Portal 主要依赖 HTTP 联网检测。

如果手机访问：

https://example.com

浏览器要求服务器提供与 example.com 匹配的 TLS 证书。

ESP32 无法提供任意网站的合法证书，因此 HTTPS 请求会产生证书错误，不能透明重定向到配网页面。

因此可以认为：

普通 HTTP 请求可以被引导到配网页面。
HTTPS 请求不能可靠劫持和重定向。

9. 配网页面不一定始终自动弹出

是否自动弹出最终由手机操作系统决定，以下情况可能影响弹窗：

手机启用了 Private DNS、DoH 或 DoT。
手机缓存了之前的 DNS 结果。
手机自动切换到蜂窝网络。
操作系统厂商修改了联网检测机制。
手机已经记住了该 Wi-Fi 的检测结果。
浏览器访问的是 HTTPS 或启用了 HSTS 的网站。

即使系统没有自动弹窗，用户仍然可以手动访问：

http://192.168.4.1/

进入配网页面。

10. 当前实现总结

当前 ESP32 Captive Portal 使用：

SoftAP
+ DHCP Option 114
+ 通配 DNS 解析
+ HTTP 303 重定向
+ HTML 配网页面

其本质是：

ESP32 将手机的联网检测请求引导到本地 HTTP Server，操作系统发现响应不符合互联网连通性检测要求，因此判定该 Wi-Fi 需要认证，并自动打开配网页面。

[esp32] Captive Portal