最近在调试 ESP32-C3 的小项目，遇到一个挺有意思的需求：设备在完成 WiFi 配网后，需要自动跳转到配置成功的页面；如果用户直接访问根路径，也要自动引导到状态页。说白了就是“ESP32-C3 实现网页跳转”——用乐鑫这颗 RISC-V 内核的芯片起一个轻量 Web Server，通过 HTTP 状态码和 Location 头，让浏览器乖乖听话跳到指定页面。
这功能听起来简单，但实际落地有不少坑：直接 sendHeader 不生效、302 和 301 的区别怎么选、配网时跳转会不会卡死……这篇文章就把我从零到一的实现过程、踩过的坑和最终能直接抄作业的代码全部分享出来。适合正在用 ESP32-C3 做物联网设备、想做配网交互或者需要内嵌 Web 管理页面的朋友参考。
1. 整体设计与实现思路
1.1 这个“跳转”到底在解决什么问题
先别急着敲代码，想想我们为什么需要网页跳转。ESP32-C3 这类芯片跑 Web Server 的场景，最常见的就是设备配网和管理页面。用户手机连上设备的热点，打开浏览器输入 192.168.4.1，看到的应该是“配置 WiFi”的引导页，而不是一堆 JSON 数据或者 404。当你提交完 WiFi 账号密码，设备开始连接路由器，这时候需要把用户引导到“连接中，请稍候”的页面，连上了再跳转到“成功”页面。
如果没有 HTTP 级别的跳转，你只能用前端 JS 定时刷新或者 setTimeout 模拟，但那个体验真的很差——页面刷新有闪烁、定时器被手机浏览器省电策略干掉、用户手动刷新又不知道跳到哪里。HTTP 重定向则是浏览器原生支持的机制，您告诉浏览器“你去另一个地址”，浏览器自己就会发起新的请求，干净利落，不会出现莫名其妙的白屏。
从实现角度讲，ESP32-C3 上的网页跳转本质就是在 HTTP 响应里加两样东西：一个 3xx 状态码，一个 Location 响应头。回来后我会详细拆这两样是怎么协作的。
1.2 方案选型：为什么用 Arduino 框架
ESP32-C3 官方支持的开发框架有 ESP-IDF 和 Arduino。这个项目我选 Arduino 框架，原因很实在：WebServer 库封装得足够友好，几行代码就能起服务，写重定向逻辑时心智负担小。ESP-IDF 的 httpd 组件功能更底层、性能上限更高，但对于“设备内嵌网页 + 跳转”这种轻量业务，用 Arduino 完全够用，而且排查问题更容易——串口打印函数随手就能加。
我用的是 ESP32-C3 SuperMini 开发板，板载 4MB Flash，引出引脚很全。开发环境是 Arduino IDE 2.x + 乐鑫官方 ESP32 板卡包（版本 2.0.14）。板卡包安装很简单，在“开发板管理器”里搜 esp32，选乐鑫官方源安装即可。注意版本不要太老，老版本 WebServer 库在重定向这块偶尔有异常。
2. 核心原理拆解：HTTP 重定向到底是怎么工作的
2.1 状态码的选择：301 还是 302
这是新手最容易忽略的细节。HTTP 协议里，跟跳转相关的状态码主要有 301 Moved Permanently 和 302 Found（也叫 302 Moved Temporarily）。这俩的区别字面上看是“永久”和“临时”，实际影响是浏览器缓存行为：
- 301：浏览器会记住这次跳转，下次直接访问旧地址时，不再请求服务器，直接跳到新地址。适合域名迁移、页面永久改版这种场景。
- 302：浏览器只跳这一次，下次还来问服务器。适合配网流程这种临时状态。
ESP32-C3 配网跳转，百分之百用 302。如果你误用了 301，用户第一次配 A 路由器的密码，成功后跳到了成功页；下次换到 B 路由器，浏览器可能缓存了之前的跳转，导致访问 192.168.4.1 直接蹦到旧成功页，但这时候设备其实还没配网，翻车翻得很隐蔽。
从我实测来看，WebServer 库里用 sendHeader 方法设置 Location 后，再调用 send(302) 就能正确实现。不过有个细节必须注意：location 地址如果不是以 http:// 开头，部分浏览器会理解成相对路径，导致跳转地址错误。所以我后面代码里都拼接完整的 URL。
2.2 Location 响应头就是跳转的“门牌号”
Location 头的作用是告诉浏览器“你要找的资源在另一个地址”。它的值可以是一个绝对 URL（比如 http://192.168.4.1/success）也可以是一个相对路径（比如 /success）。出于稳妥考虑，我在实现里用的是绝对 URL——因为设备在做热点时，用户访问的可能是 192.168.4.1 或者 192.168.4.1/ 两种形式，如果 Location 写死相对路径，某些终端下会拼接出错误的地址。
这里要特别提醒一个细节：ESP32-C3 的 WebServer 库在sendHeader之后，如果你紧接着调用send(200)这种函数，Location是不会生效的。原因是底层代码会根据状态码决定是否把响应头写出去，200 状态码下浏览器不会执行跳转逻辑。必须用 3xx 状态码。
2.3 ESP32-C3 上实现跳转的最小代码骨架
说了这么多理论，先看一个能直接跑的最小示例。这个代码实现了三件事：根路径 302 跳转到 /home，/home 返回一个简单 HTML 页面，以及把不存在的路径统一重定向到 404 页面。
#include <WiFi.h> #include <WebServer.h> WebServer server(80); void handleRoot() { // 关键：先设置 Location，再发送 302 server.sendHeader("Location", "http://" + WiFi.softAPIP().toString() + "/home"); server.send(302, "text/plain", ""); } void handleHome() { String html = "<html><body><h1>ESP32-C3 Home</h1></body></html>"; server.send(200, "text/html", html); } void handleNotFound() { server.sendHeader("Location", "http://" + WiFi.softAPIP().toString() + "/home"); server.send(302, "text/plain", ""); } void setup() { Serial.begin(115200); WiFi.mode(WIFI_AP); WiFi.softAP("ESP32-C3-Demo"); server.on("/", handleRoot); server.on("/home", handleHome); server.onNotFound(handleNotFound); server.begin(); } void loop() { server.handleClient(); }这段代码麻雀虽小但五脏俱全。注意server.onNotFound是注册 404 处理函数，我这里为了让演示效果更明显，直接把它也做成了跳转。实际项目中你可能希望 404 返回一个提示页面而不是跳走，看自己的产品逻辑。编译下载后，手机连上 ESP32-C3 的热点，浏览器访问 http://192.168.4.1，你会看到地址栏自动变成了 http://192.168.4.1/home。
3. 实操过程：从零搭建一个完整的配置跳转系统
3.1 硬件准备和开发环境配置
硬件方面很简单，一张 ESP32-C3 开发板、一根 Micro USB 数据线就够了。我手头这块 SuperMini 板子的 CH340 串口芯片驱动在 Windows 和 macOS 下都能自动识别，没有折腾驱动。如果你的板子是其他品牌，先确认串口芯片是 CP2102 还是 CH340，对应装上驱动。
软件环境建议用 Arduino IDE 2.x，安装好后在“文件 -> 首选项 -> 附加开发板管理器网址”里加上乐鑫的 JSON：
https://espressif.github.io/arduino-esp32/package_esp32_index.json然后在“开发板管理器”搜索 esp32，安装最新版本。装好后在“工具 -> 开发板”里选择 “ESP32C3 Dev Module”。这里有个坑：如果你的板子没有板载 USB 转串口芯片，需要选择 “ESP32C3 Dev Module (USB CDC)” 选项，否则上传的时候会卡在 Connecting。
选择开发板后，把 Flash Mode 设置为 QIO，Flash Size 保持 4MB，上传速度选 115200 比较稳。其他参数保持默认即可。设置完毕后，把上一节的最小代码烧进去，打开串口监视器，波特率 115200，你就能看到 softAP 创建成功的日志。
3.2 业务场景复现：配网过程中的多步跳转
光有最小骨架还不够，实际产品里跳转往往是一连串流程。我这里复刻一个典型的“智能插座配网”场景，状态机如下：
- 设备上电，进入 AP 模式，SSID 为 ESP32C3_Config
- 用户连上热点，访问 192.168.4.1，根路径返回配网表单页 /config
- 用户在表单里输入 WiFi 名称和密码，提交到 /save
- /save 处理函数收到参数后，先保存到 NVS，然后返回 302 跳转到 /connecting
- 设备尝试连接路由器，如果成功，/connecting 页面里通过 JS 定时请求 /check 接口；如果失败，跳转到 /fail 页面
- /check 接口返回连接状态，一旦检测到 STA 模式已经获得 IP，就通过重定向让浏览器跳到 /success
下面给出核心的几个 handler。首先是配网页面，这里用 URL 编码的方式把当前扫描到的 WiFi 列表嵌入 HTML，让用户在下拉框里选择。为了减少代码量，我省略了 WiFi 扫描的细节，只保留表单部分。
void handleConfig() { String html = "<!DOCTYPE html><html><head><meta charset='utf-8'>"; html += "<meta name='viewport' content='width=device-width,initial-scale=1'>"; html += "<title>WiFi配置</title></head><body>"; html += "<h2>请选择你的WiFi</h2>"; html += "<form method='POST' action='/save'>"; html += "<input type='text' name='ssid' placeholder='WiFi名称'>"; html += "<input type='password' name='password' placeholder='WiFi密码'>"; html += "<button type='submit'>连接</button>"; html += "</form></body></html>"; server.send(200, "text/html", html); }提交之后，save 处理函数是跳转的关键：
void handleSave() { String ssid = server.arg("ssid"); String password = server.arg("password"); // 保存参数 preferences.begin("wifi", false); preferences.putString("ssid", ssid); preferences.putString("pass", password); preferences.end(); // 先保存，再跳转。跳到连接中的等待页 String redirectUrl = "http://" + WiFi.softAPIP().toString() + "/connecting"; server.sendHeader("Location", redirectUrl); server.send(302, "text/plain", ""); // 在后台开启 WiFi 连接 connectTaskRunning = true; xTaskCreate(connectTask, "connectTask", 4096, NULL, 1, NULL); }注意一个先后问题：我特意把sendHeader和send放在开启连接任务之前。这是因为如果先开连接任务，WiFi 状态一变，softAP 的 IP 可能变化（在某些配置下），你用于拼接 Location 的 IP 就会不对。先应答浏览器，再做耗时操作，是最稳的顺序。
连接中的等待页，我用了一个 5 秒后自动刷新一次的方式：
void handleConnecting() { String html = "<html><head><meta charset='utf-8'>"; html += "<meta http-equiv='refresh' content='3'>"; // 3秒自动刷新一次 html += "</head><body><h2 style='text-align:center'>正在连接中...</h2></body></html>"; server.send(200, "text/html", html); }这个页面每 3 秒刷新一次，每次刷新都会重新请求 /connecting，而 /connecting 的处理函数会检测 STA 是不是已经连上：
void handleConnecting() { // 如果已经联网成功，立即 302 跳转到 success if (WiFi.status() == WL_CONNECTED) { String redirectUrl = "http://" + WiFi.softAPIP().toString() + "/success"; server.sendHeader("Location", redirectUrl); server.send(302, "text/plain", ""); return; } // 否则返回等待页面 String html = "<html><head><meta charset='utf-8'>"; html += "<meta http-equiv='refresh' content='3'>"; html += "</head><body><h2 style='text-align:center'>正在连接中...</h2></body></html>"; server.send(200, "text/html", html); }这种做法是“轮询式重定向”，比让 JS 主动去请求接口更简单。坏处是 3 秒内用户会看到页面闪烁，好处是代码量极小、对浏览器兼容性最好。如果你希望过渡得更顺滑，可以把 3 秒改成 1 秒，或者做一个带进度条的前端页面，然后通过 JS 每 500 毫秒请求一次 /check，成功后用window.location.href跳转。
不过这里我要泼一盆冷水：不会真的想靠 ESP32-C3 的 WebServer 扛大量并发请求。它同时能处理的连接数非常有限，5 秒的刷新间隔已经够用了，频繁请求会拖慢整个系统响应。
3.3 参数计算与页面拼接的细节
网页跳转看似只是发个头的事，但页面内容拼接、编码处理这些细节才是真正决定体验的部分。
在 handleConfig 里，我用了server.arg("ssid")直接取 POST 表单里的字段。这背后是 WebServer 库帮你做了解析，但如果你的前端用application/json提交，那就拿不到参数了。我习惯统一用 URL encoded 表单。
WiFi 名称里可能包含中文或特殊字符，表单提交时会做 URL 编码。WebServer 库的arg()方法返回的是解码后的值，所以存到 NVS 里的已经是真正的字符串。但你需要注意长度问题，NVS 单键长度有限制，SSID 最长 32 字节、密码最长 64 字节，存入前做个长度校验是必要的。
再就是软 AP 的 IP 地址拼接。我用了WiFi.softAPIP().toString()，这个函数在 Arduino 的 IPAddress 类里可以直接返回字符串。如果你把这一行写成String redirectUrl = "http://192.168.4.1/success"，当软 AP 网段变化时就会翻车。所以在任何需要拼 IP 的场景，都不要写死地址。
3.4 完整可复制的代码整合
把上面的片段整合一下，我自己实际跑通的完整代码如下。这个版本支持连接超时跳转失败页，也做了连接成功后停止 AP 模式的操作（这是配网常见收尾动作，防止别人继续蹭热点配置）。
#include <WiFi.h> #include <WebServer.h> #include <Preferences.h> WebServer server(80); Preferences preferences; String targetSSID = ""; String targetPass = ""; unsigned long connectStart = 0; bool connecting = false; void handleRoot() { server.sendHeader("Location", "http://" + WiFi.softAPIP().toString() + "/config"); server.send(302, "text/plain", ""); } void handleConfig() { String html = "<!DOCTYPE html><html><head><meta charset='utf-8'>"; html += "<meta name='viewport' content='width=device-width,initial-scale=1'>"; html += "<title>设备配网</title></head><body>"; html += "<h2>WiFi配置</h2>"; html += "<form method='POST' action='/save'>"; html += "<label>WiFi名称</label><br>"; html += "<input type='text' name='ssid' value='" + targetSSID + "'><br>"; html += "<label>WiFi密码</label><br>"; html += "<input type='password' name='password'><br><br>"; html += "<button type='submit'>开始连接</button>"; html += "</form></body></html>"; server.send(200, "text/html", html); } void handleSave() { targetSSID = server.arg("ssid"); targetPass = server.arg("password"); if (targetSSID.length() == 0) { server.sendHeader("Location", "http://" + WiFi.softAPIP().toString() + "/config"); server.send(302, "text/plain", ""); return; } preferences.begin("wifi", false); preferences.putString("ssid", targetSSID); preferences.putString("pass", targetPass); preferences.end(); server.sendHeader("Location", "http://" + WiFi.softAPIP().toString() + "/connecting"); server.send(302, "text/plain", ""); WiFi.mode(WIFI_AP_STA); WiFi.begin(targetSSID.c_str(), targetPass.c_str()); connectStart = millis(); connecting = true; } void handleConnecting() { if (!connecting) { server.sendHeader("Location", "http://" + WiFi.softAPIP().toString() + "/config"); server.send(302, "text/plain", ""); return; } if (WiFi.status() == WL_CONNECTED) { server.sendHeader("Location", "http://" + WiFi.softAPIP().toString() + "/success"); server.send(302, "text/plain", ""); return; } if (millis() - connectStart > 15000) { connecting = false; server.sendHeader("Location", "http://" + WiFi.softAPIP().toString() + "/fail"); server.send(302, "text/plain", ""); return; } String html = "<html><head><meta charset='utf-8'>"; html += "<meta http-equiv='refresh' content='2'>"; html += "<style>body{font-family:sans-serif;display:flex;height:100vh;justify-content:center;align-items:center;}</style>"; html += "</head><body><h2>正在连接，请稍候...</h2></body></html>"; server.send(200, "text/html", html); } void handleSuccess() { String html = "<html><head><meta charset='utf-8'>"; html += "<meta name='viewport' content='width=device-width,initial-scale=1'>"; html += "</head><body style='font-family:sans-serif;text-align:center;padding-top:60px'>"; html += "<h2 style='color:green'>配置成功</h2>"; html += "<p>设备已连接网络</p>"; html += "<p><small>IP: " + WiFi.localIP().toString() + "</small></p>"; html += "</body></html>"; server.send(200, "text/html", html); // 成功后可以关闭 AP，避免他人继续访问 delay(3000); WiFi.softAPdisconnect(true); WiFi.mode(WIFI_STA); } void handleFail() { String html = "<html><head><meta charset='utf-8'>"; html += "<meta name='viewport' content='width=device-width,initial-scale=1'>"; html += "</head><body style='font-family:sans-serif;text-align:center;padding-top:60px'>"; html += "<h2 style='color:red'>连接失败</h2>"; html += "<p>请检查 WiFi 密码或信号</p>"; html += "<p><a href='/config' style='color:#fff;background:#007bff;padding:10px 20px;border-radius:6px;text-decoration:none'>重新配置</a></p>"; html += "</body></html>"; server.send(200, "text/html", html); } void setup() { Serial.begin(115200); WiFi.mode(WIFI_AP); WiFi.softAP("ESP32C3_Config"); server.on("/", handleRoot); server.on("/config", handleConfig); server.on("/save", handleSave); server.on("/connecting", handleConnecting); server.on("/success", handleSuccess); server.on("/fail", handleFail); server.onNotFound(handleRoot); server.begin(); Serial.println("HTTP server started, IP: " + WiFi.softAPIP().toString()); } void loop() { server.handleClient(); }这个代码我在 ESP32-C3 SuperMini 上测过，配合手机热点实测整个配网流程大概 5 秒内完成。编译固件时记得开-O2优化等级，代码体积能小一点，页面响应也会更快。
4. 常见问题与排查技巧实录
4.1 跳转不生效：页面直接显示了空内容
这个问题我在第一次写跳转时踩过：server.sendHeader("Location", "...")写了，server.send(302, "text/plain", "");也写了，但浏览器不跳转，只看到一个空白页面。
排查后发现是调用顺序的问题。WebServer 库内部维护一个响应头列表，sendHeader只是把内容加到列表里，直到send时才真正拼到 HTTP 响应里。如果你在send之后再调用sendHeader，不会报错，但头根本发不出去。正确顺序一定是sendHeader在前，send在后。
另外，send的第二个参数 Content-Type 建议写"text/plain"或者"text/html"。虽然send(302, "", "")也能编译，但有些浏览器对缺失 Content-Type 的响应解析会有兼容问题，安分一点写上没坏处。
4.2 跳转后打不开目标页面
如果 302 跳转本身没问题，但目标页面一打开就 Connection Reset 或者长时间转圈，多半是/success或者/connecting的 handler 没有正确注册。
这种问题最有效的排查手段就是接串口监视器，看 ESP32-C3 的日志输出。WebServer 库在收到请求时如果没有打我自带的日志，你可以自己在每个 handler 第一行加Serial.println("handleConfig called");这种方式定位到具体是哪一个请求没被处理。
还有个小概率原因：softAP 的 IP 变了。如果你在配网过程中切了 WiFi 模式（比如从 AP 切到 AP_STA），某些 SDK 版本下软 AP 的 IP 可能会重置。稳妥做法是在给 Location 拼 IP 时用WiFi.softAPIP()动态获取，而不是常量字符串。
4.3 302 之后表单数据丢失
这个场景很经典：用户在 /save 页面提交数据，你重定向到 /connecting，接着 /connecting 页面刷新时你又想读取之前的表单数据，发现server.arg("ssid")是空的。
原因很直接，302 重定向后浏览器发起的是一个全新的 GET 请求，不会带之前 POST 的表单数据。你想要在跳转后保留数据，需要把数据放在 URL query 里拼接过去，例如：
String redirectUrl = "http://" + WiFi.softAPIP().toString() + "/connecting?ssid=" + targetSSID; server.sendHeader("Location", redirectUrl); server.send(302, "text/plain", "");然后在 /connecting 里通过server.arg("ssid")读回来。不过要注意：SSID 里可能含有特殊字符，拼接 URL 前需要先 URL 编码。Arduino 没有内置的 easy 编码函数，自己写一个字符替换也足够用了。更优雅的办法是用 NVS 保存参数，页面重新读取 NVS。
我最后采用的就是 NVS 方案，因为配网流程中数据从 /save 到 /connecting 再到 /success，传递链路太长，用全局变量和 NVS 混合最可靠。
4.4 手机浏览器不刷新缓存导致旧页面
开发调试时改了代码，重新烧录后手机打开 192.168.4.1，看到的却还是旧页面。这是因为浏览器缓存了配网表单或者跳转记录。
浏览器开发者工具的“禁用缓存”只在电脑上有效，手机上没法一直开着。我的土办法是：给静态页面 URL 加一个版本参数，比如/config?v=20231201，这样 URL 变化了，浏览器就会认为这是一个新资源，强制重新请求。这个方法也可以用在你修改 HTML 后需要用户手动刷新的场景。
4.5 常见问题速查表
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| 跳转后空白页 | sendHeader 在 send 之后调用 | 调换顺序，sendHeader 必须在 send 前 |
| 能跳转但目标页打不开 | 路由未注册 | server.on 注册目标路径，串口加日志验证 |
| Location 地址多了端口号 | softAP IP 拼接错误 | 使用 WiFi.softAPIP().toString() 动态获取 |
| 连接失败不跳转 fail | millis() 溢出或超时逻辑被阻塞 | 超时判断放 loop 里，避免 delay 阻塞 |
| 中文 SSID 乱码 | HTML 没加 charset=utf-8 | head 里加<meta charset='utf-8'> |
| 上传失败卡在 Connecting | USB CDC 设置不对 | 选择带 USB CDC 的开发板类型 |
4.6 几个保持稳定的习惯
用 ESP32-C3 做 Web Server，稳定性是绕不开的话题。分享几个我实测下来有用的习惯：
第一，不要在请求处理函数里做耗时操作。server.send之后如果处理函数还在跑，底层的 TCP 连接还挂着，用户的浏览器可能已经收到了响应但连接没有正确关闭，下次请求就会变慢。遇到需要等待的操作，要么异步任务处理，要么把长耗时操作放在loop()里用状态机推进。
第二，合理使用WiFi.softAPdisconnect(true)。配网成功后关闭 AP 是常规操作，但这个调用我已经在 delay(3000) 之后执行了，因为如果立即断开，浏览器的 /success 页面还没加载完，HTTP 连接就被掐断，用户体验很差。
第三，代码里尽量避免String的堆碎片问题。ESP32-C3 内存 400KB 左右，比 ESP8266 宽裕多了，但 Arduino 的 String 拼接会产生碎片。如果页面内容特别长，建议用snprintf写进char数组，再用server.send发送。我上面为了可读性用了 String，实际项目里可以按需优化。
5. 进阶玩法：把“跳转”玩出花
5.1 用跳转实现简易强制门户
强制门户（Captive Portal）是很多商用 Wi-Fi 的做法：用户连上热点后，手机自动弹出浏览器并打开认证页面。ESP32-C3 没法完全模拟系统级的强制门户，但可以做一个简化版：通过 DNS 劫持把任意域名请求都解析到设备自己的 IP，然后再通过 HTTP 跳转把所有流量引导到配置页。
这个玩法需要开启 DNS Server，监听 53 端口，把查询结果都返回 192.168.4.1。随后用户访问任何网站，浏览器发送的请求到了 ESP32-C3 的 80 端口，你的 WebServer 的onNotFound就会触发，在这里做个跳转到 /config 的操作，用户体验上就和强制门户几乎一样了。代码上就是在 setUp 里加一个 DNSServer 对象：
#include <DNSServer.h> DNSServer dnsServer; const byte DNS_PORT = 53; // 在 setup 里： dnsServer.start(DNS_PORT, "*", WiFi.softAPIP()); // 在 loop 里： dnsServer.processNextRequest();配合onNotFound里的重定向，用户连上热点打开任意网址都会被拉到配网页。这也是我目前在做的一个小产品的核心交互逻辑。
5.2 根据设备类型自适应跳转页面
手机和电脑的屏幕尺寸不同，直接返回同一个 HTML 在手机上体验尚可，但电脑上就明显偏窄。一个取巧的方法：根据 User-Agent 判断设备类型，然后 302 到不同的页面路由。
void handleRoot() { String ua = server.header("User-Agent"); if (ua.indexOf("Mobile") != -1) { server.sendHeader("Location", "http://" + WiFi.softAPIP().toString() + "/mobile"); } else { server.sendHeader("Location", "http://" + WiFi.softAPIP().toString() + "/desktop"); } server.send(302, "text/plain", ""); }两个页面地址不同，返回的 HTML 各自适配屏幕宽度。这么做比返回一个响应式页面要多维护两套模板，但胜在页面加载更快，且在处理老旧浏览器时不依赖 CSS 兼容性。如果你对前后端分离有洁癖，也可以在/desktop里返回一段会检测屏幕宽度的 JS，再决定是否二次跳转，不过这就绕弯路了——既然 ESP32-C3 的性能有限，尽量把重定向逻辑放在服务端，让浏览器少干活。
5.3 二维码引导用户访问
给设备起一个热点名，把配网页地址生成一个二维码印在产品标签上。用户扫描二维码直接打开配置页面，省去手动输入 192.168.4.1 的步骤。由于二维码只能包含静态字符串，所以地址写死为 http://192.168.4.1 是没问题的。再配合强制门户，用户扫码后即使热点没弹出浏览器，通过 Portal 也能自动跳转。
我用的是qrcode库，在后台生成二维码 SVG，然后嵌到一个 /qr 页面里。访问 http://192.168.4.1/qr 可以看到二维码图片，方便自己测试时快速用手机扫描。这个页面本身也可以通过根路径 302 引导过去。
写在最后
从最小示例到完整配网流程，再到强制门户和自适应跳转，ESP32-C3 上的网页跳转其实就干一件事：告诉浏览器“资源挪地方了”。但真正落地时，状态码选择、头字段顺序、URL 拼接、缓存策略这些细节，每一个都能让你的功能从“能跑”变成“好用”。
我个人在实际项目里最深的体会是：跳转方案不要等到最后才加，而要在设计路由表的时候就规划好。先把页面路径定清楚——根路径走哪、配网流程走哪、失败页走哪——再写 handler 就顺理成章。另外，每次烧录完先在电脑浏览器上验一遍 302 行为，再拿手机测，能省掉一大半浏览器兼容性的排查时间。
最后再分享一个调试小技巧：在串口监视器里把 WebServer 库的日志级别调到最大，它会打印每个请求的方法、路径、状态码，配合跳转逻辑排查非常直观。希望这篇文章能帮你少走几个弯路，如果你的设备跳转场景跟我不太一样，也欢迎在评论区聊聊你怎么设计的。
