1. 从改个密码要重刷固件说起ESP32 NVS 的痛点到底在哪搞过 ESP32 量产或者小批量部署的朋友大概率都遇到过这个场景设备已经装到现场了客户突然说 WiFi 换了密码也变了你怎么办最原始的做法是改代码里的宏定义重新编译然后抱着笔记本和 USB 线跑到现场拆壳、接线、烧录。一套流程下来半小时没了如果设备装在吊顶里或者户外防水盒里那酸爽程度直接翻倍。这个问题的本质其实不是 WiFi 本身的问题而是配置数据的存储方式决定的。ESP32 的 WiFi 账号密码绝大多数项目里都是存在 NVSNon-Volatile Storage里的。NVS 是 ESP-IDF 提供的一套轻量级键值存储系统跑在 SPI Flash 的一个独立分区上掉电不丢。Arduino 环境下用Preferences库底层也是 NVS。问题在于NVS 的数据虽然可以运行时读写但没有一个现成的、面向普通用户的修改入口——你总不能要求现场施工的大哥去连串口敲命令吧。所以真正要解决的不是怎么改 NVS而是怎么给 NVS 开一个不依赖串口、不依赖重刷固件、普通人用浏览器就能操作的修改通道。这个通道要满足几个硬条件第一设备本身得能起一个 HTTP 服务第二这个服务要能读写 NVS 的指定键第三操作界面要足够傻瓜最好手机浏览器打开就能改第四改完要能立即生效不用重启或者重启后自动连上新 WiFi。我前后在几个项目里折腾过这套东西从最早的串口命令行到后来的蓝牙配网再到现在的浏览器直接改 NVS踩过的坑不算少。下面就把这套方案的完整思路、代码实现、以及那些文档里不会写的细节一次性讲清楚。适合正在做 ESP32 联网产品、需要现场改配置的开发者也适合想搞明白 NVS 到底怎么玩的朋友。2. 为什么是浏览器改 NVS而不是蓝牙配网或串口命令2.1 三种现场改配置方案的横向对比在决定用浏览器方案之前我把常见的几种现场配置方式都试了一遍这里直接给结论对比省得你再走一遍弯路。方案实现难度现场操作门槛是否需要额外 App跨平台性适用场景串口命令行低高需电脑串口工具否差开发调试蓝牙配网中高中需手机 App 或特定小程序是一般消费级产品浏览器改 NVS中低手机浏览器即可否极好工业/商用现场按键LED 配网中中操作序列复杂否好无屏设备串口方案的问题很明显现场不可能随时有电脑和 USB 转串口模块而且很多设备装好后根本够不着串口。蓝牙配网看起来优雅但你要么自己写一个 App要么依赖某个平台的配网协议跨平台和长期维护都是负担尤其是安卓和 iOS 的蓝牙权限策略越来越严配网失败率居高不下。浏览器方案的核心优势在于零客户端依赖。ESP32 自己起一个 HTTP 服务器手机连上设备的热点或者设备连上局域网后浏览器访问设备 IP直接就是一个网页表单填完提交NVS 写入WiFi 重连。整个过程不需要装任何东西安卓、iOS、Windows、Mac 通吃。2.2 浏览器方案的两个前提条件这个方案能跑起来依赖两个前提必须提前想清楚。第一个前提是设备得先能被访问到。如果设备还没连上任何 WiFi那它只能开热点AP 模式手机连它的热点访问192.168.4.1这类默认网关地址。如果设备已经连上了某个 WiFi那手机和它要在同一个局域网里通过设备 IP 访问。这两种模式在实际项目里往往要同时支持——首次配置走 AP 模式后续改密码走 STA 模式。第二个前提是HTTP 服务不能阻塞主循环。ESP32 的 WiFi 重连、NVS 写入这些操作如果放在 HTTP 回调里同步执行很容易触发看门狗复位。我的做法是 HTTP 回调只负责解析参数和写 NVS然后设置一个标志位主循环检测到标志位后再执行 WiFi 重连。这样职责分离稳定性高很多。注意AP 模式和 STA 模式同时开启APSTA虽然方便但会显著增加功耗和内存占用。如果设备是电池供电建议首次配置用 AP 模式配置完成后关闭 AP只保留 STA。3. NVS 键值读写的底层逻辑与代码骨架3.1 NVS 到底存了什么命名空间怎么规划NVS 不是一块裸 Flash它有一套自己的分区结构和索引机制。每个键值对归属于一个命名空间namespace命名空间下面才是具体的键key。键名最长 15 个字符值可以是整数、字符串、二进制块等类型。ESP32 默认的 NVS 分区通常是nvs分区大小在分区表里定义常见的是 0x500020KB或者 0x900036KB。我的命名空间规划习惯是这样的WiFi 相关的配置放wifi_cfg业务参数放app_cfg设备身份信息放dev_info。这样做的原因是将来如果要擦除某一类配置可以按命名空间整体擦除不会误伤其他数据。比如恢复出厂设置时只擦wifi_cfg和app_cfg保留dev_info里的设备序列号。// Arduino 环境下用 Preferences 库操作 NVS #include Preferences.h Preferences prefs; // 写入 WiFi 配置 prefs.begin(wifi_cfg, false); // false 表示读写模式 prefs.putString(ssid, MyWiFi); prefs.putString(pass, 12345678); prefs.end(); // 读取 prefs.begin(wifi_cfg, true); // true 表示只读模式 String ssid prefs.getString(ssid, ); String pass prefs.getString(pass, ); prefs.end();这里有个细节很多人不注意begin()的第二个参数是只读标志。如果你只是读取一定要传true这样 NVS 不会以写模式打开减少 Flash 磨损也避免多任务下的锁竞争。我见过有人在循环里反复begin(false)读数据结果 Flash 寿命和性能都受影响。3.2 HTTP 服务的最小实现与路由设计浏览器方案的核心是一个轻量 HTTP 服务器。Arduino 环境下用WebServer库就够了ESP-IDF 环境下用esp_http_server。路由设计我一般分三个GET /返回配置页面 HTML包含 SSID、密码的输入框和提交按钮POST /save接收表单数据写入 NVS返回成功提示GET /status返回当前连接状态方便页面轮询#include WebServer.h WebServer server(80); void handleRoot() { String html htmlbody; html h2WiFi Config/h2; html form action/save methodPOST; html SSID: input namessidbr; html PASS: input namepass typepasswordbr; html input typesubmit valueSave; html /form/body/html; server.send(200, text/html, html); } void handleSave() { String ssid server.arg(ssid); String pass server.arg(pass); prefs.begin(wifi_cfg, false); prefs.putString(ssid, ssid); prefs.putString(pass, pass); prefs.end(); server.send(200, text/plain, Saved, reconnecting...); needReconnect true; // 标志位主循环处理 } void setup() { // ... WiFi 初始化 ... server.on(/, handleRoot); server.on(/save, HTTP_POST, handleSave); server.begin(); } void loop() { server.handleClient(); if (needReconnect) { needReconnect false; WiFi.disconnect(); WiFi.begin(newSSID.c_str(), newPass.c_str()); } }这段代码看起来简单但有几个坑必须提前说。第一server.arg()拿到的字符串如果包含特殊字符比如密码里有或表单编码会出问题建议前端用encodeURIComponent处理后端做 URL 解码。第二handleSave里不要直接调WiFi.begin()原因前面说了会阻塞。第三HTML 页面里的中文如果直接写要确保响应头带charsetutf-8否则手机浏览器可能乱码。3.3 写入 NVS 后如何让新配置立即生效写完 NVS 只是第一步让新配置真正生效才是关键。WiFi 重连的逻辑我一般这样写先WiFi.disconnect(true)彻底断开并清除旧状态然后WiFi.begin(ssid, pass)接着给一个超时等待比如 15 秒。如果 15 秒内没连上就回退到 AP 模式让用户重新配置。bool connectWiFi(String ssid, String pass, uint32_t timeout_ms) { WiFi.disconnect(true); delay(100); WiFi.begin(ssid.c_str(), pass.c_str()); uint32_t start millis(); while (WiFi.status() ! WL_CONNECTED) { if (millis() - start timeout_ms) { return false; } delay(200); } return true; }这里有个经验值WiFi.disconnect(true)里的true参数会同时关闭 WiFi 射频再重新打开比单纯disconnect()更彻底能避免一些连上了但拿不到 IP的玄学问题。另外超时时间不要设太短有些路由器 DHCP 分配慢10 秒以内都可能不够15 到 20 秒比较稳妥。4. 现场实操中那些文档不会告诉你的坑4.1 AP 模式下手机浏览器打不开页面的排查链路这个坑我踩过不止一次。设备开了 AP 热点手机也连上了但浏览器访问192.168.4.1就是转圈。排查下来通常是这几个原因第一个原因是手机自动切换到了移动数据。很多安卓手机在 WiFi 没有外网时会自动用蜂窝数据导致请求根本没走 WiFi。解决办法是在代码里给 AP 配置一个假的 DNS或者提示用户手动关闭移动数据。iOS 相对好一点但也会弹无互联网连接的提示用户点了保持连接才行。第二个原因是AP 的 IP 段和手机其他网络冲突。默认192.168.4.1一般没事但如果用户手机之前连过同样网段的网络路由表可能混乱。我一般把 AP 的 IP 改成不常见的段比如192.168.77.1减少冲突概率。第三个原因是HTTP 服务没起来。这个最隐蔽因为 WiFi 连上了不代表服务器在跑。我的做法是在setup()里server.begin()之后串口打印一行 HTTP server started现场调试时一眼就能看出来。4.2 密码里的特殊字符导致表单提交失败用户设的 WiFi 密码什么字符都可能有、、、#、空格这些在 URL 编码里都有特殊含义。如果前端表单直接application/x-www-form-urlencoded提交后端server.arg()解析时可能截断或者错位。我的处理方式是前端用 JavaScript 做一次encodeURIComponent后端拿到后再解码。或者更省事把表单的enctype设成text/plain然后手动解析 body。但最稳的还是标准 URL 编码配合后端解码。// 前端提交前编码 function submitForm() { var ssid encodeURIComponent(document.getElementById(ssid).value); var pass encodeURIComponent(document.getElementById(pass).value); fetch(/save, { method: POST, headers: {Content-Type: application/x-www-form-urlencoded}, body: ssid ssid pass pass }); }后端server.arg()在 Arduino WebServer 库里其实已经做了 URL 解码所以前端编码后传过去后端拿到的是解码后的原文这个配合是没问题的。但如果你用的是 ESP-IDF 的httpd_req_get_url_query_str那就要自己解码别搞混了。4.3 NVS 写入失败与分区空间不足NVS 写入失败最常见的原因是分区满了。NVS 虽然会做垃圾回收但如果频繁写入大量数据或者键值对数量超过分区容量putString会返回 0写入字节数为 0表示失败。很多人不检查返回值以为写进去了结果重启后读出来还是旧值。我的习惯是每次putString后检查返回值如果为 0就打印错误并尝试prefs.clear()清空当前命名空间后重写。当然clear()要慎用会清掉该命名空间下所有键。size_t written prefs.putString(ssid, ssid); if (written 0) { Serial.println(NVS write failed, namespace may be full); // 可选清理后重试 }另一个隐蔽的坑是NVS 分区大小在分区表里定义。如果你用的是自定义分区表nvs分区给得太小比如 0x1000存几个字符串就满了。建议至少给 0x5000也就是 20KB够存几百个键值对。4.4 改完密码后设备连不上如何优雅回退这是现场最尴尬的情况用户改了个密码结果密码打错了设备连不上新 WiFi又因为已经不在 AP 模式用户也访问不到设备了直接失联。这个问题的解法是双保险。第一层保险是连接超时回退。前面connectWiFi返回 false 时不要傻等直接重新开启 AP 模式让用户可以再次访问配置页面。第二层保险是保留上一次成功的配置。在写入新配置之前先把旧配置备份到另一个命名空间比如wifi_bak。如果新配置连接失败自动回滚到旧配置重连。这样即使密码打错设备也能回到之前能用的状态。// 备份旧配置 prefs.begin(wifi_bak, false); prefs.putString(ssid, oldSSID); prefs.putString(pass, oldPass); prefs.end(); // 新配置失败后回滚 if (!connectWiFi(newSSID, newPass, 15000)) { prefs.begin(wifi_bak, true); String bakSSID prefs.getString(ssid, ); String bakPass prefs.getString(pass, ); prefs.end(); connectWiFi(bakSSID, bakPass, 15000); }这个回滚机制在实际项目里救过我好几次尤其是给非技术用户用的设备他们改密码时手滑打错一个字符的概率相当高。5. 从能用到好用配置页面的交互优化与安全考量5.1 页面自动填充当前 SSID 和信号强度一个合格的配置页面不应该让用户从零开始输入。设备当前连的什么 WiFi、信号多强这些信息应该直接显示在页面上。SSID 可以从 NVS 读信号强度用WiFi.RSSI()拿。String currentSSID prefs.getString(ssid, ); int rssi WiFi.RSSI(); String html pCurrent: currentSSID ( String(rssi) dBm)/p;RSSI 的参考值-50 dBm 以内是极好-60 到 -70 是良好-80 以下就偏弱了。页面上可以顺便给个提示信号弱的时候建议换个位置或者换个 AP。另外扫描周边 WiFi 列表也是个加分项。WiFi.scanNetworks()能扫出一圈 SSID做成下拉框让用户选比手打强得多。但扫描比较耗时一般 2 到 4 秒建议做成按钮触发不要每次加载页面都扫。5.2 给配置接口加一层简单的访问保护浏览器改 NVS 虽然方便但也意味着同一个局域网里任何人都能改你的设备配置。如果是商用场景这个风险不能忽视。最简单的保护是加一个配置密码页面提交时要求输入后端校验通过才写入。if (server.arg(token) ! your_secret_token) { server.send(403, text/plain, Forbidden); return; }这个 token 可以存在 NVS 里首次烧录时写入后续可以改。更严格的做法是限制访问来源 IP或者只在 AP 模式下开放配置接口STA 模式下关闭。具体用哪种看你的安全等级要求。注意不要在页面上明文显示 token也不要用太简单的固定值。我见过有人直接用 123456 当配置密码等于没设。5.3 配置生效后的状态反馈与页面跳转用户点了保存之后最怕的是页面卡住不知道成没成。我的做法是保存接口立即返回一个正在重连的页面然后页面用 JavaScript 轮询/status接口拿到连接成功后再跳转到成功提示。void handleStatus() { if (WiFi.status() WL_CONNECTED) { server.send(200, text/plain, connected: WiFi.localIP().toString()); } else { server.send(200, text/plain, connecting); } }前端拿到connected后显示设备的局域网 IP方便用户后续访问。这个体验细节看起来小但现场用起来差别很大——用户知道设备连上了、IP 是多少心里就有底。6. 几个容易被忽略的工程细节6.1 看门狗与长耗时操作的相处之道ESP32 默认开启了任务看门狗TWDT如果某个任务长时间不让出 CPU就会触发复位。WiFi 重连、NVS 大批量写入这些操作都可能超时。除了前面说的用标志位把重连放到主循环还要注意在等待循环里加delay()或者vTaskDelay()让看门狗有机会喂狗。while (WiFi.status() ! WL_CONNECTED) { if (millis() - start timeout_ms) break; delay(100); // 关键让出 CPU }这个delay(100)不是可有可无的去掉它看门狗大概率会咬你。我早期就因为这个设备一改密码就重启查了半天才发现是看门狗。6.2 固件升级后 NVS 数据的兼容性NVS 的数据是独立于固件的刷固件不会清 NVS除非你手动擦除。这本来是好事但如果你在新固件里改了键名或者命名空间旧数据就读不出来了。我的做法是在 NVS 里存一个cfg_ver版本号固件启动时检查版本不匹配就执行迁移或者重置。prefs.begin(app_cfg, false); int ver prefs.getInt(cfg_ver, 0); if (ver CURRENT_CFG_VER) { // 执行迁移逻辑 prefs.putInt(cfg_ver, CURRENT_CFG_VER); } prefs.end();这个习惯在长期维护的项目里特别重要能避免很多升级后配置丢失的投诉。6.3 多设备批量配置时的效率问题如果你一次要给几十台设备配网一台台连热点、开浏览器、输密码效率太低。这时候可以做一个批量配置的变体设备上电后如果检测到某个按键被按住就进入 AP 模式并广播一个固定的 SSID 前缀比如CFG_ESP32_xxxx。配置人员用手机连上后页面里可以一次性填写多台设备的配置或者用脚本通过 HTTP 接口批量提交。更进一步如果设备已经在一个局域网里可以做一个 UDP 广播发现机制配置工具广播一个发现包所有设备回应自己的 IP然后工具批量调用每台设备的/save接口。这套东西做一次后面批量部署能省大量时间。7. 我在实际项目里踩过的两个真实教训第一个教训是关于AP 模式下的 DNS。早期版本我只起了 HTTP 服务没配 DNS结果手机连上 AP 后浏览器地址栏输入任何域名都打不开用户必须手动输 IP。后来我在 AP 配置里加了一个 DNS 服务器把所有域名都解析到 AP 的 IP这样用户输config.local或者随便什么域名都能跳到配置页。这个细节对非技术用户特别友好。// 简易 DNS所有查询都返回 AP IP DNSServer dnsServer; dnsServer.start(53, *, WiFi.softAPIP());第二个教训是关于NVS 的写入寿命。Flash 有擦写次数限制虽然 NVS 做了磨损均衡但如果你在循环里高频写 NVS比如每秒写一次传感器数据Flash 很快就会坏。我的做法是传感器数据攒够一定量或者定时比如 5 分钟才写一次 NVS中间数据放 RAM。配置类数据本来就是低频写入倒不用担心但业务数据一定要控制写入频率。这两个教训都是实际跑出来的文档里不会写但现场遇到就是大麻烦。浏览器改 NVS 这套方案本身不复杂难的是把那些边界情况都考虑到让它在各种手机、各种网络环境下都能稳定工作。我现在的做法是每做一个新项目都把这套配置页面做成一个可复用的组件改改命名空间和键名就能用省得每次重写。
1. 从改个密码要重刷固件说起ESP32 NVS 的痛点到底在哪搞过 ESP32 量产或者小批量部署的朋友大概率都遇到过这个场景设备已经装到现场了客户突然说 WiFi 换了密码也变了你怎么办最原始的做法是改代码里的宏定义重新编译然后抱着笔记本和 USB 线跑到现场拆壳、接线、烧录。一套流程下来半小时没了如果设备装在吊顶里或者户外防水盒里那酸爽程度直接翻倍。这个问题的本质其实不是 WiFi 本身的问题而是配置数据的存储方式决定的。ESP32 的 WiFi 账号密码绝大多数项目里都是存在 NVSNon-Volatile Storage里的。NVS 是 ESP-IDF 提供的一套轻量级键值存储系统跑在 SPI Flash 的一个独立分区上掉电不丢。Arduino 环境下用Preferences库底层也是 NVS。问题在于NVS 的数据虽然可以运行时读写但没有一个现成的、面向普通用户的修改入口——你总不能要求现场施工的大哥去连串口敲命令吧。所以真正要解决的不是怎么改 NVS而是怎么给 NVS 开一个不依赖串口、不依赖重刷固件、普通人用浏览器就能操作的修改通道。这个通道要满足几个硬条件第一设备本身得能起一个 HTTP 服务第二这个服务要能读写 NVS 的指定键第三操作界面要足够傻瓜最好手机浏览器打开就能改第四改完要能立即生效不用重启或者重启后自动连上新 WiFi。我前后在几个项目里折腾过这套东西从最早的串口命令行到后来的蓝牙配网再到现在的浏览器直接改 NVS踩过的坑不算少。下面就把这套方案的完整思路、代码实现、以及那些文档里不会写的细节一次性讲清楚。适合正在做 ESP32 联网产品、需要现场改配置的开发者也适合想搞明白 NVS 到底怎么玩的朋友。2. 为什么是浏览器改 NVS而不是蓝牙配网或串口命令2.1 三种现场改配置方案的横向对比在决定用浏览器方案之前我把常见的几种现场配置方式都试了一遍这里直接给结论对比省得你再走一遍弯路。方案实现难度现场操作门槛是否需要额外 App跨平台性适用场景串口命令行低高需电脑串口工具否差开发调试蓝牙配网中高中需手机 App 或特定小程序是一般消费级产品浏览器改 NVS中低手机浏览器即可否极好工业/商用现场按键LED 配网中中操作序列复杂否好无屏设备串口方案的问题很明显现场不可能随时有电脑和 USB 转串口模块而且很多设备装好后根本够不着串口。蓝牙配网看起来优雅但你要么自己写一个 App要么依赖某个平台的配网协议跨平台和长期维护都是负担尤其是安卓和 iOS 的蓝牙权限策略越来越严配网失败率居高不下。浏览器方案的核心优势在于零客户端依赖。ESP32 自己起一个 HTTP 服务器手机连上设备的热点或者设备连上局域网后浏览器访问设备 IP直接就是一个网页表单填完提交NVS 写入WiFi 重连。整个过程不需要装任何东西安卓、iOS、Windows、Mac 通吃。2.2 浏览器方案的两个前提条件这个方案能跑起来依赖两个前提必须提前想清楚。第一个前提是设备得先能被访问到。如果设备还没连上任何 WiFi那它只能开热点AP 模式手机连它的热点访问192.168.4.1这类默认网关地址。如果设备已经连上了某个 WiFi那手机和它要在同一个局域网里通过设备 IP 访问。这两种模式在实际项目里往往要同时支持——首次配置走 AP 模式后续改密码走 STA 模式。第二个前提是HTTP 服务不能阻塞主循环。ESP32 的 WiFi 重连、NVS 写入这些操作如果放在 HTTP 回调里同步执行很容易触发看门狗复位。我的做法是 HTTP 回调只负责解析参数和写 NVS然后设置一个标志位主循环检测到标志位后再执行 WiFi 重连。这样职责分离稳定性高很多。注意AP 模式和 STA 模式同时开启APSTA虽然方便但会显著增加功耗和内存占用。如果设备是电池供电建议首次配置用 AP 模式配置完成后关闭 AP只保留 STA。3. NVS 键值读写的底层逻辑与代码骨架3.1 NVS 到底存了什么命名空间怎么规划NVS 不是一块裸 Flash它有一套自己的分区结构和索引机制。每个键值对归属于一个命名空间namespace命名空间下面才是具体的键key。键名最长 15 个字符值可以是整数、字符串、二进制块等类型。ESP32 默认的 NVS 分区通常是nvs分区大小在分区表里定义常见的是 0x500020KB或者 0x900036KB。我的命名空间规划习惯是这样的WiFi 相关的配置放wifi_cfg业务参数放app_cfg设备身份信息放dev_info。这样做的原因是将来如果要擦除某一类配置可以按命名空间整体擦除不会误伤其他数据。比如恢复出厂设置时只擦wifi_cfg和app_cfg保留dev_info里的设备序列号。// Arduino 环境下用 Preferences 库操作 NVS #include Preferences.h Preferences prefs; // 写入 WiFi 配置 prefs.begin(wifi_cfg, false); // false 表示读写模式 prefs.putString(ssid, MyWiFi); prefs.putString(pass, 12345678); prefs.end(); // 读取 prefs.begin(wifi_cfg, true); // true 表示只读模式 String ssid prefs.getString(ssid, ); String pass prefs.getString(pass, ); prefs.end();这里有个细节很多人不注意begin()的第二个参数是只读标志。如果你只是读取一定要传true这样 NVS 不会以写模式打开减少 Flash 磨损也避免多任务下的锁竞争。我见过有人在循环里反复begin(false)读数据结果 Flash 寿命和性能都受影响。3.2 HTTP 服务的最小实现与路由设计浏览器方案的核心是一个轻量 HTTP 服务器。Arduino 环境下用WebServer库就够了ESP-IDF 环境下用esp_http_server。路由设计我一般分三个GET /返回配置页面 HTML包含 SSID、密码的输入框和提交按钮POST /save接收表单数据写入 NVS返回成功提示GET /status返回当前连接状态方便页面轮询#include WebServer.h WebServer server(80); void handleRoot() { String html htmlbody; html h2WiFi Config/h2; html form action/save methodPOST; html SSID: input namessidbr; html PASS: input namepass typepasswordbr; html input typesubmit valueSave; html /form/body/html; server.send(200, text/html, html); } void handleSave() { String ssid server.arg(ssid); String pass server.arg(pass); prefs.begin(wifi_cfg, false); prefs.putString(ssid, ssid); prefs.putString(pass, pass); prefs.end(); server.send(200, text/plain, Saved, reconnecting...); needReconnect true; // 标志位主循环处理 } void setup() { // ... WiFi 初始化 ... server.on(/, handleRoot); server.on(/save, HTTP_POST, handleSave); server.begin(); } void loop() { server.handleClient(); if (needReconnect) { needReconnect false; WiFi.disconnect(); WiFi.begin(newSSID.c_str(), newPass.c_str()); } }这段代码看起来简单但有几个坑必须提前说。第一server.arg()拿到的字符串如果包含特殊字符比如密码里有或表单编码会出问题建议前端用encodeURIComponent处理后端做 URL 解码。第二handleSave里不要直接调WiFi.begin()原因前面说了会阻塞。第三HTML 页面里的中文如果直接写要确保响应头带charsetutf-8否则手机浏览器可能乱码。3.3 写入 NVS 后如何让新配置立即生效写完 NVS 只是第一步让新配置真正生效才是关键。WiFi 重连的逻辑我一般这样写先WiFi.disconnect(true)彻底断开并清除旧状态然后WiFi.begin(ssid, pass)接着给一个超时等待比如 15 秒。如果 15 秒内没连上就回退到 AP 模式让用户重新配置。bool connectWiFi(String ssid, String pass, uint32_t timeout_ms) { WiFi.disconnect(true); delay(100); WiFi.begin(ssid.c_str(), pass.c_str()); uint32_t start millis(); while (WiFi.status() ! WL_CONNECTED) { if (millis() - start timeout_ms) { return false; } delay(200); } return true; }这里有个经验值WiFi.disconnect(true)里的true参数会同时关闭 WiFi 射频再重新打开比单纯disconnect()更彻底能避免一些连上了但拿不到 IP的玄学问题。另外超时时间不要设太短有些路由器 DHCP 分配慢10 秒以内都可能不够15 到 20 秒比较稳妥。4. 现场实操中那些文档不会告诉你的坑4.1 AP 模式下手机浏览器打不开页面的排查链路这个坑我踩过不止一次。设备开了 AP 热点手机也连上了但浏览器访问192.168.4.1就是转圈。排查下来通常是这几个原因第一个原因是手机自动切换到了移动数据。很多安卓手机在 WiFi 没有外网时会自动用蜂窝数据导致请求根本没走 WiFi。解决办法是在代码里给 AP 配置一个假的 DNS或者提示用户手动关闭移动数据。iOS 相对好一点但也会弹无互联网连接的提示用户点了保持连接才行。第二个原因是AP 的 IP 段和手机其他网络冲突。默认192.168.4.1一般没事但如果用户手机之前连过同样网段的网络路由表可能混乱。我一般把 AP 的 IP 改成不常见的段比如192.168.77.1减少冲突概率。第三个原因是HTTP 服务没起来。这个最隐蔽因为 WiFi 连上了不代表服务器在跑。我的做法是在setup()里server.begin()之后串口打印一行 HTTP server started现场调试时一眼就能看出来。4.2 密码里的特殊字符导致表单提交失败用户设的 WiFi 密码什么字符都可能有、、、#、空格这些在 URL 编码里都有特殊含义。如果前端表单直接application/x-www-form-urlencoded提交后端server.arg()解析时可能截断或者错位。我的处理方式是前端用 JavaScript 做一次encodeURIComponent后端拿到后再解码。或者更省事把表单的enctype设成text/plain然后手动解析 body。但最稳的还是标准 URL 编码配合后端解码。// 前端提交前编码 function submitForm() { var ssid encodeURIComponent(document.getElementById(ssid).value); var pass encodeURIComponent(document.getElementById(pass).value); fetch(/save, { method: POST, headers: {Content-Type: application/x-www-form-urlencoded}, body: ssid ssid pass pass }); }后端server.arg()在 Arduino WebServer 库里其实已经做了 URL 解码所以前端编码后传过去后端拿到的是解码后的原文这个配合是没问题的。但如果你用的是 ESP-IDF 的httpd_req_get_url_query_str那就要自己解码别搞混了。4.3 NVS 写入失败与分区空间不足NVS 写入失败最常见的原因是分区满了。NVS 虽然会做垃圾回收但如果频繁写入大量数据或者键值对数量超过分区容量putString会返回 0写入字节数为 0表示失败。很多人不检查返回值以为写进去了结果重启后读出来还是旧值。我的习惯是每次putString后检查返回值如果为 0就打印错误并尝试prefs.clear()清空当前命名空间后重写。当然clear()要慎用会清掉该命名空间下所有键。size_t written prefs.putString(ssid, ssid); if (written 0) { Serial.println(NVS write failed, namespace may be full); // 可选清理后重试 }另一个隐蔽的坑是NVS 分区大小在分区表里定义。如果你用的是自定义分区表nvs分区给得太小比如 0x1000存几个字符串就满了。建议至少给 0x5000也就是 20KB够存几百个键值对。4.4 改完密码后设备连不上如何优雅回退这是现场最尴尬的情况用户改了个密码结果密码打错了设备连不上新 WiFi又因为已经不在 AP 模式用户也访问不到设备了直接失联。这个问题的解法是双保险。第一层保险是连接超时回退。前面connectWiFi返回 false 时不要傻等直接重新开启 AP 模式让用户可以再次访问配置页面。第二层保险是保留上一次成功的配置。在写入新配置之前先把旧配置备份到另一个命名空间比如wifi_bak。如果新配置连接失败自动回滚到旧配置重连。这样即使密码打错设备也能回到之前能用的状态。// 备份旧配置 prefs.begin(wifi_bak, false); prefs.putString(ssid, oldSSID); prefs.putString(pass, oldPass); prefs.end(); // 新配置失败后回滚 if (!connectWiFi(newSSID, newPass, 15000)) { prefs.begin(wifi_bak, true); String bakSSID prefs.getString(ssid, ); String bakPass prefs.getString(pass, ); prefs.end(); connectWiFi(bakSSID, bakPass, 15000); }这个回滚机制在实际项目里救过我好几次尤其是给非技术用户用的设备他们改密码时手滑打错一个字符的概率相当高。5. 从能用到好用配置页面的交互优化与安全考量5.1 页面自动填充当前 SSID 和信号强度一个合格的配置页面不应该让用户从零开始输入。设备当前连的什么 WiFi、信号多强这些信息应该直接显示在页面上。SSID 可以从 NVS 读信号强度用WiFi.RSSI()拿。String currentSSID prefs.getString(ssid, ); int rssi WiFi.RSSI(); String html pCurrent: currentSSID ( String(rssi) dBm)/p;RSSI 的参考值-50 dBm 以内是极好-60 到 -70 是良好-80 以下就偏弱了。页面上可以顺便给个提示信号弱的时候建议换个位置或者换个 AP。另外扫描周边 WiFi 列表也是个加分项。WiFi.scanNetworks()能扫出一圈 SSID做成下拉框让用户选比手打强得多。但扫描比较耗时一般 2 到 4 秒建议做成按钮触发不要每次加载页面都扫。5.2 给配置接口加一层简单的访问保护浏览器改 NVS 虽然方便但也意味着同一个局域网里任何人都能改你的设备配置。如果是商用场景这个风险不能忽视。最简单的保护是加一个配置密码页面提交时要求输入后端校验通过才写入。if (server.arg(token) ! your_secret_token) { server.send(403, text/plain, Forbidden); return; }这个 token 可以存在 NVS 里首次烧录时写入后续可以改。更严格的做法是限制访问来源 IP或者只在 AP 模式下开放配置接口STA 模式下关闭。具体用哪种看你的安全等级要求。注意不要在页面上明文显示 token也不要用太简单的固定值。我见过有人直接用 123456 当配置密码等于没设。5.3 配置生效后的状态反馈与页面跳转用户点了保存之后最怕的是页面卡住不知道成没成。我的做法是保存接口立即返回一个正在重连的页面然后页面用 JavaScript 轮询/status接口拿到连接成功后再跳转到成功提示。void handleStatus() { if (WiFi.status() WL_CONNECTED) { server.send(200, text/plain, connected: WiFi.localIP().toString()); } else { server.send(200, text/plain, connecting); } }前端拿到connected后显示设备的局域网 IP方便用户后续访问。这个体验细节看起来小但现场用起来差别很大——用户知道设备连上了、IP 是多少心里就有底。6. 几个容易被忽略的工程细节6.1 看门狗与长耗时操作的相处之道ESP32 默认开启了任务看门狗TWDT如果某个任务长时间不让出 CPU就会触发复位。WiFi 重连、NVS 大批量写入这些操作都可能超时。除了前面说的用标志位把重连放到主循环还要注意在等待循环里加delay()或者vTaskDelay()让看门狗有机会喂狗。while (WiFi.status() ! WL_CONNECTED) { if (millis() - start timeout_ms) break; delay(100); // 关键让出 CPU }这个delay(100)不是可有可无的去掉它看门狗大概率会咬你。我早期就因为这个设备一改密码就重启查了半天才发现是看门狗。6.2 固件升级后 NVS 数据的兼容性NVS 的数据是独立于固件的刷固件不会清 NVS除非你手动擦除。这本来是好事但如果你在新固件里改了键名或者命名空间旧数据就读不出来了。我的做法是在 NVS 里存一个cfg_ver版本号固件启动时检查版本不匹配就执行迁移或者重置。prefs.begin(app_cfg, false); int ver prefs.getInt(cfg_ver, 0); if (ver CURRENT_CFG_VER) { // 执行迁移逻辑 prefs.putInt(cfg_ver, CURRENT_CFG_VER); } prefs.end();这个习惯在长期维护的项目里特别重要能避免很多升级后配置丢失的投诉。6.3 多设备批量配置时的效率问题如果你一次要给几十台设备配网一台台连热点、开浏览器、输密码效率太低。这时候可以做一个批量配置的变体设备上电后如果检测到某个按键被按住就进入 AP 模式并广播一个固定的 SSID 前缀比如CFG_ESP32_xxxx。配置人员用手机连上后页面里可以一次性填写多台设备的配置或者用脚本通过 HTTP 接口批量提交。更进一步如果设备已经在一个局域网里可以做一个 UDP 广播发现机制配置工具广播一个发现包所有设备回应自己的 IP然后工具批量调用每台设备的/save接口。这套东西做一次后面批量部署能省大量时间。7. 我在实际项目里踩过的两个真实教训第一个教训是关于AP 模式下的 DNS。早期版本我只起了 HTTP 服务没配 DNS结果手机连上 AP 后浏览器地址栏输入任何域名都打不开用户必须手动输 IP。后来我在 AP 配置里加了一个 DNS 服务器把所有域名都解析到 AP 的 IP这样用户输config.local或者随便什么域名都能跳到配置页。这个细节对非技术用户特别友好。// 简易 DNS所有查询都返回 AP IP DNSServer dnsServer; dnsServer.start(53, *, WiFi.softAPIP());第二个教训是关于NVS 的写入寿命。Flash 有擦写次数限制虽然 NVS 做了磨损均衡但如果你在循环里高频写 NVS比如每秒写一次传感器数据Flash 很快就会坏。我的做法是传感器数据攒够一定量或者定时比如 5 分钟才写一次 NVS中间数据放 RAM。配置类数据本来就是低频写入倒不用担心但业务数据一定要控制写入频率。这两个教训都是实际跑出来的文档里不会写但现场遇到就是大麻烦。浏览器改 NVS 这套方案本身不复杂难的是把那些边界情况都考虑到让它在各种手机、各种网络环境下都能稳定工作。我现在的做法是每做一个新项目都把这套配置页面做成一个可复用的组件改改命名空间和键名就能用省得每次重写。
