ESP32浏览器直改WiFi密码：NVS存储+Web Server配置方案详解

上个月帮朋友维护一批 ESP32 设备对方一句话让我头疼了半天“WiFi 密码改了你重新烧一下固件吧。”重新编译倒是小事关键是设备已经装在天花板配电箱里了要么拆回来要么抱着笔记本爬到现场用串口线捅。后来我索性给这批 ESP32 加了一个浏览器配置工具设备自己开一个网页手机连上就能改 WiFi 的 SSID 和密码改完直接把键值写进 NVS重启自动连接新网络。用下来非常爽今天把这个方案从头到尾拆开讲一遍。这个需求不是个别现场才有的。只要是量产过的 ESP32 设备面临的第一大运维痛点往往不是代码 Bug而是“配置变了”。WiFi 密码换了、服务器地址改了、设备名称想更新传统做法就是重新编译、重新烧录对一个已经封装好、装在高处或者远程地点的设备来说这代价太高了。而 NVS 这个键值存储机制加上 ESP32 自带的 Web Server完全可以组合出一套“浏览器直改配置”的维护方案。这篇文章会把原理、代码、部署、避坑全部讲透适合用 ESP-IDF 或 Arduino 开发 ESP32 的开发者也适合正在做 IoT 产品、需要考虑现场维护成本的朋友。1. NVS 是怎么回事为什么 WiFi 密码要存在这里1.1 NVS 的本质是 Flash 上的键值小数据库NVS 的全称是 Non-Volatile Storage非易失性存储。它是 ESP-IDF 提供的一套基于片内 Flash 的键值对存储系统掉电不丢失专门用来保存小体量配置数据。你可以把它理解成一个“迷你数据库”每条数据就是一个 Key 加一个 ValueValue 可以存字符串、整型、浮点、二进制块等。很多刚接触 ESP32 的朋友会分不清 NVS、SPIFFS、LittleFS 和 EEPROM 这几个概念。简单说NVS按“键值对”存取适合存少量结构化配置API 最简洁写完调用nvs_commit落盘。SPIFFS / LittleFS文件系统适合存网页文件、证书、日志等成块的数据。EEPROMArduino 里的那个模拟出来的本质上也是在 Flash 上划一块区域适合极简单场景。在 Arduino 生态里Preferences库封装的就是 NVS 的底层实现在 ESP-IDF 里nvs.h接口就是直接和它打交道。WiFi 的 SSID、密码、设备 ID、MQTT 地址、传感器阈值这类“键值”天然适合 NVS。1.2 把 WiFi 配置编译进固件为什么是费力不讨好最粗暴的做法是把 WiFi 凭据写死在代码里const char* ssid MyHomeWiFi; const char* password 12345678;这种代码我在很多初学者项目里见过。它的问题不是“不能跑”而是每改一次配置就要重新编译一次固件然后重新烧录。编译少则几十秒多则几分钟烧录还要接串口、进烧录模式。更麻烦的是固件一旦发布出去用户手里拿到的已经是一个成品你没法要求每个用户自己去编译。再说说扫码配网SmartConfig和 SoftAP 配网。它们解决的问题是“首次配网”也就是设备新出场、还没有任何 WiFi 信息时通过手机 App 或微信小程序把 WiFi 凭据发给设备。这个体验确实不错但问题在于很多方案是一次性的配完网之后配置入口就关了后面要改 WiFi 密码或者换一个网络又得重新触发配网流程甚至需要恢复出厂设置。NVS 的价值就在这里WiFi 配置只作为“数据”存放在 Flash 的键值区里固件本身不绑定任何具体网络。改数据不等于改程序自然就不用重刷固件。2. 方案选型浏览器直改 NVS 的三条技术路线2.1 内嵌 Web Server最推荐的现场维护方案ESP32 自带的esp_http_server组件可以在设备上开一个轻量级 HTTP 服务。设备上电后网络层可以维持两种形态已经连上路由器时Web 服务监听在局域网 IP 的 80 端口手机或电脑在同一局域网内访问http://设备IP/就能进入配置页。没有连上 WiFi 时ESP32 自动开启 SoftAP 热点手机连接这个热点后访问http://192.168.4.1/同样进入配置页。这种方式用户体验最接近“网页后台”不需要安装任何 App浏览器打开就行。我在现场维护时直接掏出手机连设备热点改完配置点保存设备重启连上新 WiFi整个过程不到一分钟。2.2 Web Serial调试阶段很好用的网页串口工具如果你的设备已经烧好固件、无法开启热点、也不想加 Web 逻辑还有一种思路电脑浏览器通过 Web Serial API 直接读写 ESP32 的串口配合设备端预留的一个文本协议也能改 NVS 键值。设备端只需要一个命令解析函数比如收到SET wifi_ssid mywifi\r\n就写入 NVS收到GET wifi_ssid就返回当前值。这套方案的好处是网页工具可以免安装、跨平台而且不占用设备的网络资源。缺点是 Web Serial 只能在 Chrome、Edge 等 Chromium 内核浏览器上使用而且设备必须能接串口不适合已经安装到现场的情况。2.3 局域网自定义 UDP/TCP面向 App 和自动化系统如果客户端不是浏览器而是一个 App 或者 PC 上位机可以走自定义的 TCP 或 UDP 协议。设备监听一个固定端口收到特定格式的配置帧后解析并写入 NVS。这种方式的好处是灵活、可以集成到批量管理工具里比如一台电脑给同网段的多台设备推配置。缺点是需要额外开发客户端体验和通用性都不如网页。三条路线对比一下方案适用场景客户端要求开发成本安全性内嵌 Web Server现场/局域网维护任意浏览器中可做 Token 鉴权Web Serial调试/串口可接Chromium 浏览器低取决于协议UDP/TCP 自定义App/批量管理专用客户端高可做白名单加密我最推荐内嵌 Web Server。因为对于绝大多数维护场景“手机浏览器打开网页填表单”是用户学习成本最低、最容易接受的交互方式。3. 核心原理Web 页面如何和 NVS “对话”3.1 一条配置数据在浏览器和 Flash 之间的完整旅程理清这条链路后面的代码就好写了。用户输入一个 WiFi 密码点击保存数据是这样流动的浏览器把表单内容编码成一个 HTTP POST 请求发到 ESP32 的/api/config路由。ESP32 的 HTTP Server 回调函数里收到请求体里面是一段 JSON比如{ssid:HomeWiFi,password:12345678}。回调函数解析 JSON拿到字符串值。调用nvs_set_str把 SSID 写入 NVS 键值区再调用nvs_commit确保落盘。向浏览器返回{code:0,msg:ok}。设备端收到成功后延时几百毫秒调用esp_restart()重启。重启后程序从 NVS 读回新的 SSID 和密码执行 WiFi 连接。整个过程没有任何代码重新编译固件一个字都没变变的只是 Flash 里的数据。3.2 为什么必须调 nvs_commitNVS 写入不是即时的。nvs_set_str只是把数据放到了内存中的缓存区真正写进 Flash 要等nvs_commit执行。如果省掉这一步就断电配置可能丢失。有些场景更隐蔽同一个 NVS 分区在擦写前需要做磨损均衡如果频繁写入不 commit底层也不知道该什么时候合并条目。所以标准姿势是nvs_set_str(handle, password, new_pass); nvs_commit(handle);3.3 安全边界配置页不能裸奔轻量不代表可以裸奔。任何一个连接到设备热点的陌生人都能改配置这在公网环境或者开放场所里是不可接受的。至少要加一层基础保护配置页登录口令。在 NVS 里存一个admin_token用户必须输入口令才能打开页面。仅在 SoftAP 模式开放 Web 配置。如果设备已经连上了可信路由器配置端口只在局域网开放如果连不上 WiFi、进入配置热点就要求口令。生产环境建议做简单的 IP 白名单或者关闭公网端口映射。不要天真地以为“设备在局域网里很安全”。同一个 WiFi 下的任何设备都可以发起请求哪怕是隔壁工位同事的手机。加上口令验证成本很低收益很大。4. 动手实现完整代码拆解与集成指南4.1 NVS 读写封装我先封装一个通用的读写接口避免业务代码里到处nvs_open。#include nvs.h #include nvs_flash.h #include string.h esp_err_t nvs_write_str(const char* app_namespace, const char* key, const char* value) { nvs_handle_t handle; esp_err_t err nvs_open(app_namespace, NVS_READWRITE, handle); if (err ! ESP_OK) return err; err nvs_set_str(handle, key, value); if (err ESP_OK) { err nvs_commit(handle); } nvs_close(handle); return err; } esp_err_t nvs_read_str(const char* app_namespace, const char* key, char* out, size_t* len) { nvs_handle_t handle; esp_err_t err nvs_open(app_namespace, NVS_READONLY, handle); if (err ! ESP_OK) return err; err nvs_get_str(handle, key, out, len); nvs_close(handle); return err; }这里有个关键点nvs_get_str第一次调用时如果传入的out为 NULL函数会把实际字符串长度写入len这是获取长度的标准姿势。所以我建议的读取流程是size_t len 0; nvs_read_str(wifi_cfg, ssid, NULL, len); if (len 0) { char* ssid malloc(len); nvs_read_str(wifi_cfg, ssid, ssid, len); }需要注意的是NVS 字符串长度在上层一般建议不要超过 4000 字节WiFi 的 SSID 和密码远小于这个限制可以放心用。4.2 HTTP Server 与 JSON 配置接口接下来是 HTTP 部分。我用 ESP-IDF 的esp_http_server实现两个路由GET /返回配置页面 HTML。POST /api/config解析 JSON 并写入 NVS。#include esp_http_server.h #include cJSON.h static esp_err_t api_config_handler(httpd_req_t *req) { char buf[512] {0}; int total_len req-content_len; int ret httpd_req_recv(req, buf, total_len 511 ? total_len : 511); if (ret 0) { httpd_resp_send_err(req, HTTPD_400_BAD_REQUEST, recv failed); return ESP_FAIL; } cJSON* root cJSON_Parse(buf); if (root NULL) { httpd_resp_send_err(req, HTTPD_400_BAD_REQUEST, invalid json); return ESP_FAIL; } cJSON* ssid cJSON_GetObjectItem(root, ssid); cJSON* pass cJSON_GetObjectItem(root, password); if (!cJSON_IsString(ssid) || !cJSON_IsString(pass)) { cJSON_Delete(root); httpd_resp_send_err(req, HTTPD_400_BAD_REQUEST, missing fields); return ESP_FAIL; } // 先校验 SSID 长度WiFi 标准是 1-32 字节 if (ssid-valuestring NULL || strlen(ssid-valuestring) 0 || strlen(ssid-valuestring) 32) { cJSON_Delete(root); httpd_resp_send_err(req, HTTPD_400_BAD_REQUEST, bad ssid); return ESP_FAIL; } esp_err_t err nvs_write_str(wifi_cfg, ssid, ssid-valuestring); if (err ESP_OK) { err nvs_write_str(wifi_cfg, password, pass-valuestring); } cJSON_Delete(root); if (err ! ESP_OK) { httpd_resp_send_err(req, HTTPD_500_INTERNAL_SERVER_ERROR, nvs write failed); return ESP_FAIL; } httpd_resp_set_type(req, application/json); httpd_resp_sendstr(req, {\code\:0,\msg\:\ok\}); // 延迟重启 vTaskDelay(pdMS_TO_TICKS(500)); esp_restart(); return ESP_OK; }那段对所有字段做校验的代码建议保留。因为如果直接把valuestring写入 NVS万一用户的 SSID 是空字符串设备重启后会拿空 SSID 去连 WiFi连不上就进 AP 模式用户可能以为设备坏了。4.3 配置页面 HTML配置页不需要复杂。一个标题、两个输入框、一个密码框、一个保存按钮、一个提示区就足够了。为了少一个文件我直接把 HTML 内嵌在固件里以字符串形式返回。!DOCTYPE html html head meta charsetutf-8 meta nameviewport contentwidthdevice-width,initial-scale1 titleESP32 Config/title /head body h3WiFi 配置/h3 labelWiFi 名称(SSID)/label input idssid typetext maxlength32 labelWiFi 密码/label input idpassword typepassword maxlength64 button onclicksave()保存并重启/button div idmsg/div script function save() { var ssid document.getElementById(ssid).value; var password document.getElementById(password).value; fetch(/api/config, { method: POST, headers: {Content-Type: application/json}, body: JSON.stringify({ssid: ssid, password: password}) }).then(function(r){ return r.json(); }) .then(function(d){ document.getElementById(msg).innerText d.msg; }) .catch(function(){ document.getElementById(msg).innerText 请求失败; }); } /script /body /html注意页面里的按钮文案直接写“保存并重启”不要只写“保存”因为这一步会真重启设备。用户如果没有心理准备看到设备重启还会以为出了故障。4.4 启动流程如何优雅地决定“连 WiFi 还是开热点”这是整个方案的灵魂。设备上电后不能老想着“先连接上次的 WiFi”也要考虑“万一 WiFi 没了怎么办”。我的建议是一个带超时和回退的状态机初始化 NVS。读取wifi_cfg.ssid和wifi_cfg.password。如果 SSID 存在设置 WiFi 为 STA 模式开始连接。等待 WiFi 连接事件。我一般给 15 到 20 秒超时。如果连上了获取 IP启动 HTTP Server在局域网 IP 上提供服务。如果超时未连上设置 WiFi 为 AP 模式启动 SoftAP 热点默认 SSID 比如ESP32-Config同时启动 HTTP Server监听192.168.4.1。在 AP 模式下配置 Web 页正常使用。如果是用户误触发了 AP 模式他可以重新配置 WiFi 并重启。事件处理可以用 ESP-IDF 的esp_event_handler注册也可以简单轮询esp_wifi_connect()的返回值。为了稳定性我倾向于事件驱动。还有一点经验如果设备作为 STA 连接路由器失败不要立刻死循环重试。可以先尝试扫描一下周围网络看 SSID 是否存在如果找不到 SSID说明用户改的名字不对直接开 AP 提示用户重新配置更高效。4.5 Arduino 环境下的等价实现很多用户不用 ESP-IDF而是用 Arduino Preferences库。核心逻辑完全一样只是换了一套 API。#include WiFi.h #include WebServer.h #include Preferences.h #include ArduinoJson.h Preferences prefs; void setup() { Serial.begin(115200); prefs.begin(wifi_cfg, false); String ssid prefs.getString(ssid, ); String password prefs.getString(password, ); if (ssid.length() 0) { WiFi.begin(ssid.c_str(), password.c_str()); // 等待连接或超时后开热点 } else { setupConfigAP(); } }Arduino 生态固定思路就是把 HTML 塞进一个 PROGMEM 字符串WebServer 库的on(/api/config, HTTP_POST, handler)处理和 ESP-IDF 大同小异。如果你只是给自己做个小设备Arduino 这套上手更快如果是要做产品我还是推荐 ESP-IDF资源占用和稳定性都更可控。5. 实操记录从编译到现场改密完整走一遍5.1 编译烧录与首次验证我的实验环境是 ESP32-S3 DevKitCESP-IDF v5.2。新建工程后把上面三段代码分别放进nvs_util.c、http_server.c、main.c然后idf.py set-target esp32s3 idf.py build idf.py flash monitor上电后串口日志里应该能看到 NVS 初始化成功因为 NVS 里还没有ssid键值所以直接进入了 AP 模式。我特意把 AP 的 SSID 设置成ESP32-Config密码留空方便手机连上。打开手机 WiFi找到ESP32-Config热点连接后访问http://192.168.4.1/浏览器弹出配置页。填上我家的 WiFi SSID 和密码点击“保存并重启”。十几秒后设备重启并成功连接路由器从路由器管理界面能看到它的 IP。5.2 改 WiFi 密码的完整实验重点来了。设备连上路由器后我故意把手机热点改了个名字模拟用户换 WiFi然后在浏览器里输入设备的局域网 IP重新提交新的配置。这次的区别在于设备已经处于 STA 模式且能正常访问所以不需要先重置设备。整个过程手机连上同一个路由器。浏览器访问http://设备IP/。输入新的 SSID 和密码保存。设备写入 NVS 并重启。串口日志显示设备用新 SSID 连上了新网络。没有重刷固件整个过程只改了一个键值。5.3 当 WiFi 彻底消失时回退到配置热点还有一个场景值得单独实验设备当前在 STA 模式下但路由器突然关了。设备会怎么样我的代码里处理了这种状态WiFi 连接断开后先尝试重连几次确认无法重连后自动切换为 AP 模式重新开启ESP32-Config热点。此时配置页依然可以打开用户可以直接改配置。这个机制保证了“设备永远有一个可触达的配置入口”不会变成一块砖。为了验证我把路由器断电等了 30 秒用手机搜索热点果然又看到了ESP32-Config。5.4 把配置项扩展到 WiFi 之外这套机制的价值不止于改 WiFi。我在实际项目里还这样用把mqtt_server、mqtt_port存进 NVS网页管理员可以直接改 MQTT 服务器地址不需要重新烧录固件。把device_name存进 NVS用来修改设备在局域网里的显示名。把upload_interval存进 NVS远程调整传感器上报频率。把cal_offset存进 NVS现场校准传感器零点。每次扩展一个新配置项只需要在 NVS 里加一个键值、在配置页里加一个输入框、在 JSON 解析里加一个字段改动成本非常低。但运维上省下来的功夫是成倍的。6. 常见问题与排查技巧实录6.1 NVS 写入失败或重启后配置丢失排查顺序现象可能原因解决方式nvs_open返回ESP_ERR_NVS_NO_FREE_PAGESNVS 分区不足检查分区表partitions.csv适当加大 NVS 分区写入成功但重启后读不到没调nvs_commit每个nvs_set_*后必须 commit读出的字符串是乱码nvs_get_str传入的长度指针不正确第一次传 NULL 拿长度再分配缓冲区键名看起来一样但读不到NVS 键名最长 15 字符超长会被拒绝缩短键名比如ssid而不是wifi_ssid_nameNVS 键名限制是 15 个字符这个很隐性。我之前用了一个 20 个字符的键名nvs_open能成功但nvs_set_str一直返回错误查了半天才看到文档里的说明。6.2 HTTP 请求体被截断httpd_req_recv一次不一定能收完整个 body。尤其手机浏览器发出 POST 请求时如果 JSON 内容比较大虽然我们的很小函数可能只读到一部分。我建议用一个循环把content_len全部接收完再做 JSON 解析。代码里简单写httpd_req_recv(req, buf, req-content_len)是有隐患的。一个稳妥的做法int remaining req-content_len; int offset 0; while (remaining 0) { int ret httpd_req_recv(req, buf offset, remaining); if (ret 0) break; offset ret; remaining - ret; }6.3 手机浏览器访问不到配置页最常见的原因是手机和 ESP32 不在同一网段。比如 ESP32 连的是路由器的 2.4G 频段手机却连了 5G 频段而路由器做了 AP 隔离两个频段互不可见。解决办法是关闭 AP 隔离或者固定设备 IP让手机直接访问。另一种情况是设备没有成功获取 IP。检查串口日志确认 DHCP 是否正常。如果路由器没有开 DHCP就要在固件里设置一个静态 IP否则设备看似连上了 WiFi实际上没有 IP 地址。6.4 网页能打开但点保存无反应打开浏览器开发者工具的 Network 面板看 POST/api/config的返回状态。如果返回400说明 JSON 解析失败检查是不是浏览器把请求体发成了application/x-www-form-urlencoded而不是application/json。如果返回500检查串口日志里的 NVS 错误码。还有一个容易忽略的点HTTP Server 默认的max_uri_handlers是 8如果你的工程里还注册了其他路由配置路由可能排不进去。要么调大配置要么精简路由。6.5 设备频繁重启在 AP 和 STA 之间来回跳这是因为逻辑里没有设置“失败冷静期”。WiFi 连不上立刻开 AP用户还没来得及操作AP 没人连又尝试回 STA连不上又开 AP。这种死循环会让设备非常耗电也让用户困惑。解决方式状态切换之间加一个“最多尝试次数”或“最短停留时间”。我习惯在进入 AP 模式后保持至少 5 分钟除非用户主动保存配置否则不自动回 STA。6.6 配置页被浏览器缓存成旧版本在开发调试阶段每次改动 HTML 字符串后手机浏览器打开的可能还是旧页面。解决办法是在 HTML 的head里加一个meta http-equivCache-Control contentno-cache或者在 HTTP 响应头里设置Cache-Control: no-store。我实测下来浏览器对局域网内嵌页面的缓存策略比较随意很容易踩坑。建议写 HTTP 响应时统一加上这个头。提示给用户提供的配置页一定要显示当前版本号比如页面底部加一行v1.0.3。否则你更新了固件里的配置页用户却说看到的还是老界面那时候很难判断是浏览器缓存问题还是固件没刷进去。6.7 小技巧日志里加一条“当前生效配置”我在开机日志里会打印一句话[NVS] WiFi config: ssidHomeWiFi password********密码会打码但 SSID 不打码。这样做的好处是如果用户报障说“设备没联网”我可以让他把串口日志发过来一眼就能看出设备正在尝试连接哪个 WiFi是不是密码错了。这个排查效率比反复询问高太多了。7. 我在实际项目中的扩展与反思做了这套方案之后我把维护设备的方式完全换了个思路。以前修改配置我要么发一个新固件让用户刷要么专程跑一趟现场。现在大部分配网和参数调整问题都能远程解决只要设备能联网不管是连路由器还是开热点我都能通过浏览器进入配置页操作。后来我还做了一个更实用的扩展页面里加了一个“恢复出厂设置”按钮。用户点击后程序清空 NVS 分区中wifi_cfg命名空间下的所有键值然后重启进入 AP 模式。这比让用户长按物理按键恢复出厂设置更直接也适合那些没有接按键的设备。如果要继续往下走还可以把配置页从“只读 WiFi 信息”升级成“完整参数管理”设备名称、时区、上报周期、传感器告警阈值都放进去。甚至可以把固件升级也做成网页上传用 OTA 接口配合这个配置页形成一个完整的产品运维闭环。不过一定要记住网页配置功能越强大安全责任也越大。设备的核心控制参数如果被恶意修改后果可能不只是“连不上网”。建议哪怕是一个小项目也要在配置页入口加密码在写 NVS 之前校验参数的合法性在日志里记录每一次配置变更。这些底线不能丢。