ESP32 项目做久了谁都会遇到这么个场景设备已经装到客户现场或者塞在吊顶里结果路由器密码被人改了一次整台设备立刻失联。以前碰到这种情况我基本只有一个办法——跑一趟现场拆设备、找串口线、重新编译烧固件。一套折腾下来半小时起步运气不好就是一下午。后来我在几个项目里陆续换了一种做法把 WiFi 配置从固件里彻底拆出来存进 NVS 键值区然后用设备内置的浏览器配置页直接改键值。这样用户只要手机连上设备的配置热点、打开网页、填个新密码设备重启后就能连上新网络。没错改 WiFi 密码这件事应该从“重刷固件”降级成“改一下 NVS 键值”。这套方案我用了很久思路清晰实现也就半天今天完整拿出来说说。1. 先想清楚WiFi 凭据为什么能独立于固件修改1.1 每次改 WiFi 就重刷固件代价到底有多大先说一个很现实的问题你以为“改个 WiFi 密码”只是改一行WiFi.begin()参数但实际走到现场才明白这行代码背后藏着一整条麻烦链。第一是时间成本。代码里改一个宏定义、重新编译即使是最小的 ESP32 工程编译也要几十秒以上烧录又得几分钟。如果你的工程用了 OTA那还得先把设备从故障状态救回来如果 OTA 链路已经被断网切断就只能用 USB 串口线连电脑硬刷。第二是物理成本。设备一旦部署起来一般不会放在手边。挂在墙上、装在柜子里、塞进设备舱想把它拆下来重刷先得准备螺丝刀、线缆还得考虑断电风险。我见过不少项目为了一个小小的 WiFi 配置问题花四五个小时跑现场结果真正操作只要一分钟。第三是使用者的门槛。设备做出来不是为了只给开发者自己用。最终用户拿到的是一台成品你总不能指望他们打开 Arduino IDE 改代码。在你的认知里是“改一行配置重新编译”在用户眼里就是“这东西坏了”。所以结论很清楚联网设备的 WiFi 配置天生就不应该绑死在固件里。它应该是一份可独立修改的数据而这份数据的存放位置恰好就是 NVS。1.2 NVS 是独立的一块“配置寄存柜”和固件根本不是一回事很多人对 ESP32 的存储结构理解得不够深总觉得“改配置”和“重刷固件”是一回事其实完全不是。ESP32 的 flash 里分了很多个分区固件代码放在 app 分区OTA 临时固件放在 otadata 和 app 等各种区域另外还有一个专门用来存键值数据的 nvs 分区。NVS 全称叫 Non-Volatile Storage非易失性存储本质就是一个基于 flash 的键值数据库。你写进去一个字符串、一个整数、一段二进制数据断电之后它还在再上电还能读出来。用生活类比的话固件是“程序光盘”NVS 是设备旁边的一个“小本子”。程序跑起来会去读这个小本子根据上面记录的 WiFi 名和密码来决定连哪个路由器。你改这个小本子上的内容完全不需要重刻光盘。同理改 NVS 键值也完全不需要重新烧固件。这个机制在 ESP-IDF 和 Arduino 框架里都支持。Arduino 环境下最常用的是 Preferences 库底层封装的就是 NVS 能力。你只要搞清楚固件负责干活NVS 负责记配置两者互不干扰。1.3 一套完整的冷启动逻辑读 NVS → 连 WiFi → 不行就开配置页既然 WiFi 配置存在 NVS 里那设备的启动逻辑就要跟着改不再是简单地在代码里写死WiFi.begin(my_ssid, my_password)而是要变成一条完整的状态机开机后从 NVS 中读取wifinamespace 下的ssid和password键值。如果读取成功且非空进入 STA 模式尝试连接路由器。如果读取不到配置或者连接超时失败进入 AP 配置模式开一个 SoftAP 热点和一个 Web 服务器。用户手机连上这个热点浏览器访问192.168.4.1在网页表单里填入新的 WiFi 名和密码。Web 服务器收到提交后写回 NVS 键值然后调用ESP.restart()重启设备。重启后设备读到新配置按新 Wi-Fi 连接成功。这套逻辑并不复杂但它把“改 WiFi 密码”变成了一次纯用户操作开发者彻底不用到场。这也正是市面上 WiFiManager 库的核心原理——它帮你在后台做了 NVS 的读写。但如果你只知道用库、不理解底层键值是怎么落地的一旦出问题你连排查方向都没有。所以我建议至少手写一遍把原理吃透。2. 动手前先规划好 NVS 键值2.1 namespace 与键名设计一张表说清楚写 NVS 之前第一件事是设计键值结构。ESP32 的 NVS 里每条数据都由 namespace key 两级定位namespace 相当于文件夹key 相当于文件名。我通常会给设备建一个wifinamespace里面放两三个键键名类型说明取值范围ssidString路由器 WiFi 名最长 32 字节passwordStringWiFi 密码最长 63 字节开放网络可留空lastErrorI32 或 String最近一次连接失败原因可选自定义这里有几个关键细节必须注意。NVS 的 key 最长只支持 15 个字符超出会直接报错所以你千万别写什么wifi_router_password_last_time这种键名“password”就够了。另外WiFi 名最长 32 字节、WPA2 密码最长 63 字节这个长度限制要写死在网页校验里别让用户乱填。键值设计也建议留一点扩展空间。设备不可能只存 WiFi 凭据后面大概率还要存 MQTT 服务器地址、设备名称、上报周期、阈值参数等等。我的习惯是另外建一个cfgnamespace 专门放业务配置WiFi 凭据单独放一个wifinamespace逻辑清晰互不干扰。后面想清空配置也很方便——只要清除对应 namespace 就行。2.2 Preferences 还是原生 nvs_flash APIArduino 环境下操作 NVS最舒服的方式是 Preferences 库它把 namespace 和读写逻辑封得干干净净。ESP-IDF 环境下则直接用nvs_flash系列 API更底层、更灵活但代码写起来也啰嗦一点。Preferences 的典型写法如下#include Preferences.h Preferences prefs; // 读取配置 prefs.begin(wifi, true); // 第二个参数 true 表示只读 String ssid prefs.getString(ssid, ); String password prefs.getString(password, ); prefs.end(); // 写入配置 prefs.begin(wifi, false); // 写模式 prefs.putString(ssid, newSsid); prefs.putString(password, newPassword); prefs.end(); // end() 的时候会做 NVS commitPreferences 在底层调用的其实就是 nvs_flash API但它帮你处理了缓存和提交时机。我平时基本用 Preferences因为代码可读性好不容易漏掉nvs_close这种细节。如果你在 ESP-IDF 里开发原生写法大概是nvs_handle_t handle; esp_err_t err; err nvs_open(wifi, NVS_READWRITE, handle); if (err ESP_OK) { nvs_set_str(handle, ssid, newSsid); nvs_set_str(handle, password, newPassword); nvs_commit(handle); nvs_close(handle); }注意这个nvs_commit它才真正把数据落到 flash。Preferences 的end()也会触发 commit所以别小看这个动作写 NVS 不做 commit等于白干。2.3 首次开机没有配置怎么办新设备第一次上电NVS 里是空的此时如果固件一上来就强制进 STA 模式那就永远连不上网。所以启动逻辑里一定要有一个判断NVS 里读到的 ssid 为空或密码不符合基本长度就自动进入 AP 配置模式。这也意味着“出厂默认配置”这个概念要看场景。开发阶段你可以在代码里留一个默认 WiFi 宏方便自己快速联调但真正部署给客户时最好不要写死默认 WiFi 凭据。客户家的路由器名和密码你根本不知道就算你知道隔几个月换一次密码你的默认配置就废了。让设备首次开机自动开配置页是最稳妥的产品行为。还有一个细节NVS 键值如果以前存过一遍之后想更新也不难但要注意清理旧键。Preferences 的remove可以移除单个键clear()可以清空整个 namespace。我在“恢复出厂”功能里就是这么做的。3. 浏览器配置页内嵌 Web 服务器的实现细节3.1 页面从哪里来直接内嵌还是挂文件系统浏览器配置页的核心是 ESP32 上跑一个 Web 服务器。常见做法有两种把 HTML 字符串直接写在代码里或者把网页文件放在 LittleFS/SPIFFS 文件系统里动态读取。小项目、快速原型、配置页就一个表单的情况下我强烈建议直接内嵌字符串。代码量小不涉及文件系统挂载串口烧录时也不用额外烧录文件系统镜像。一个简单的配置页HTML 加起来也就几行到几十行直接拼字符串发送完全够用。如果配置页涉及大量前端逻辑、多语言、样式复杂再考虑 LittleFS。文件系统方案的好处是前端代码和固件分离改网页不一定要重新烧固件但这也增加了复杂度和打包流程。我的经验是先内嵌字符串跑通等界面真的复杂到不可维护了再迁移到文件系统不要一开始就上重型方案。内嵌页面代码大概长这样#include WiFi.h #include WebServer.h WebServer server(80); void handleRoot() { String html !DOCTYPE htmlhtmlheadmeta charsetutf-8titleWiFi 配置/title/head body stylefont-family:sans-serif;margin:2rem h2WiFi 配置/h2 form methodPOST action/save labelWiFi 名称/labelbr input namessid maxlength32 placeholder输入路由器 SSID stylewidth:90%;padding:.5rembrbr labelWiFi 密码/labelbr input namepassword typepassword maxlength63 placeholder留空表示开放网络 stylewidth:90%;padding:.5rembrbr button typesubmit stylepadding:.5rem 1rem;background:#1b8f5b;color:#fff;border:0保存并重启/button /form pa href/clear stylecolor:#999清除配置并进入 AP 模式/a/p /body/html; server.send(200, text/html, html); }这段代码在 AP 模式下能直接跑浏览器访问192.168.4.1就能看到页面。3.2 保存流程校验参数、写 NVS、重启并确认配置页表单的 action 指向/save提交方式用 POST。服务端收到请求以后一定不要直接写入重启先做参数校验。校验点至少有三个ssid 非空长度不超过 32 字节。password 长度不超过 63 字节如果非空则不能小于 8 位因为 WPA2 密码最短就是 8 位。可选如果想让用户输入“开放网络”场景允许 password 为空但要明确提示。校验通过后执行写入 NVS 并重启。这里有一个经验细节HTTP 响应要先发出去设备再重启。如果你一写入 NVS 立刻调用ESP.restart()浏览器这边连接直接被断开用户看到的往往是一片空白体验很不好。正确做法是server.send(200, ...)之后再delay(500)确保响应包已经离开协议栈然后再重启。保存接口的完整代码void handleSave() { if (!server.hasArg(ssid)) { server.send(400, text/plain, missing ssid); return; } String ssid server.arg(ssid); String password server.arg(password); ssid.trim(); if (ssid.length() 0 || ssid.length() 32) { server.send(400, text/plain, ssid invalid); return; } if (password.length() 0 password.length() 8) { server.send(400, text/plain, password too short); return; } prefs.begin(wifi, false); prefs.putString(ssid, ssid); prefs.putString(password, password); prefs.end(); server.send(200, text/plain, saved, restarting...); delay(500); ESP.restart(); }/clear处理也很简单清除 namespace 后重启进 APvoid handleClear() { prefs.begin(wifi, false); prefs.clear(); prefs.end(); server.send(200, text/plain, cleared, restarting...); delay(500); ESP.restart(); }3.3 配置页顺手加一个扫描 WiFi 功能解决中文 SSID 的坑很多人做配置页的时候只放两个输入框我建议加一个“扫描 WiFi”按钮让设备扫描周围网络并把结果列出来用户点击某一项自动填入 ssid 输入框。这个功能不仅体验好更重要的是能帮你绕开中文 SSID 的编码坑。ESP32 的 WiFi 扫描结果是驱动直接返回的原始字节序列当你从扫描结果里拿到 SSID 并原样填入表单时字节内容不会经过手打输入就不会出现编码转换问题。如果让用户手动敲一个中文 WiFi 名网页大概率按 UTF-8 提交而不少老路由器广播的是 GBK 编码两边对不上直接导致设备搜索不到目标网络。这个坑我踩过一次后来再也不敢让用户手输中文 SSID 了。扫描接口可以写成返回 JSON 列表void handleScan() { int n WiFi.scanNetworks(); String json [; for (int i 0; i n; i) { if (i) json ,; json {\ssid\:\ WiFi.SSID(i) \,\rssi\: String(WiFi.RSSI(i)) }; } json ]; WiFi.scanDelete(); server.send(200, application/json, json); }注意这个示例里的 JSON 没有做引号转义。如果环境中存在 SSID 里带双引号的怪名字前端解析就会出问题。生产环境建议用 ArduinoJson 库来序列化而不是手拼字符串。3.4 进阶体验DNS 劫持让配网页面自动弹出光有一个 Web 页面用户还得手动输入192.168.4.1对非技术用户来说还是不够傻瓜。更好的做法是加一个 DNS 劫持也就是 Captive Portal 思路用户连上设备的热点后不管他打开什么网址都会被重定向到配置页。原理很简单AP 模式下监听 53 端口的 DNS 请求把所有域名解析都指向192.168.4.1。这样用户手机连上热点随便点开一个网页系统自动弹出配置页不需要记 IP。在 ESP32 上用 DNSServer 库就能实现#include DNSServer.h DNSServer dnsServer; IPAddress apIP(192, 168, 4, 1); dnsServer.start(53, *, apIP); // loop 里 dnsServer.processNextRequest();这里有一个重要警告DNS 劫持只能在 AP 配置模式下开启。设备正常连上路由器、进入 STA 模式后绝不能继续运行 DNS 劫持否则会把设备所在局域网内的所有域名解析都拦截掉影响范围瞬间扩大。我见过有人把 DNSServer 的start无条件放在setup()里结果设备正常工作时全家网络 DNS 都被污染了排查了整半天。4. 防失联设计连接失败后自动回到配置页4.1 连接超时与失败重试的推荐参数如果用户把 WiFi 密码填错了或者路由器没开机设备的表现不能是“傻等”或彻底失联它应该在失败后自动回到配置模式给用户第二次机会。我测试下来比较稳的一组参数是单次 STA 连接超时 15 秒连续失败 3 次后进入 AP 模式。这个 15 秒很关键太短了有些信号弱的路由器还没来得及回包就被判失败太长了用户现场调试验证时等得着急。15 秒属于折中实测大部分路由器在 2 到 8 秒内就能完成握手15 秒足够覆盖大多数异常情况。连接逻辑可以这样写bool connectToSTA(const String ssid, const String password) { WiFi.mode(WIFI_STA); WiFi.begin(ssid.c_str(), password.c_str()); uint32_t start millis(); while (WiFi.status() ! WL_CONNECTED millis() - start 15000) { delay(200); } return WiFi.status() WL_CONNECTED; }主流程里如果这个函数返回 false就进入startAPMode()。这个自动回退机制是设备最后一道保住可用性的防线务必加上。4.2 物理按键兜底长按进入 AP 模式软件逻辑做得再完善也挡不住一些极端情况比如用户设备已经配过网但现在家里换了个新路由器而旧路由器已经被搬走了设备启动后连不上旧网络按理说会自动回 AP 模式。但如果你的回退策略次数限制设得太高或者设备短暂连上过新路由器后来又被踢下线用户还是不知道怎么重新触发配置。这时候一个物理按键兜底很有价值。ESP32 开发板上通常自带一个 BOOT 键对应 GPIO0默认上拉按下为低电平。我们可以设置一个“长按 5 秒清除 NVS 并进入 AP 模式”的功能。实现思路const int BUTTON_PIN 0; uint32_t pressStart 0; void loop() { if (digitalRead(BUTTON_PIN) LOW) { if (pressStart 0) pressStart millis(); if (millis() - pressStart 5000) { prefs.begin(wifi, false); prefs.clear(); prefs.end(); ESP.restart(); } } else { pressStart 0; } }这个按钮在开发和维护阶段也是救命稻草设备要换环境、换网络按 5 秒就能恢复出厂配置流程完全不需要拆机。4.3 用 LED 快速判断设备状态排查现场问题的时候没有串口输出也没有网页可看这时候板载 LED 就是唯一的“显示器”。我习惯把 LED 状态设计得很简单LED 状态含义每秒快闪 2 次AP 配置模式等待用户配网慢闪2 秒一次正在尝试连接路由器常亮已连接路由器正常工作逻辑不复杂就是在loop()里根据设备状态控制 GPIO。别小看这个功能现场工程师不需要连终端就能判断当前设备处在哪个环节排查效率高很多。5. 实测全流程与常见问题速查5.1 完整实测链路从烧录到换密码我按这个方案在 ESP32 DevKitC 上完整跑过一遍。硬件就是一块普通开发板加一个板载 LED没有外接任何元器件。第一次烧录时烧录工具里我特意保留了 NVS 分区。这里要提醒一句很多烧录工具默认是“全擦 flash”如果你之前已经通过配置页写过 WiFi 信息全擦会把 NVS 里的配置一并清掉。日常迭代固件时最好只擦 app 分区或者明确确认要保留配置。实测流程如下烧录固件设备启动后 NVS 为空自动进入 AP 模式。手机 WiFi 列表里看到一个ESP32_Config的热点连接它。注意配网模式下设备没有外网手机会提示“此 Wi-Fi 无法连接互联网”这是正常的不要惊慌。浏览器打开192.168.4.1配置页正常显示。点击“扫描 WiFi”附近的路由器列表都出来了点击家里的网络SSID 自动填入。输入密码点“保存并重启”浏览器显示 “saved, restarting...”页面稍后断开设备进入重启流程。手机切回家里 WiFi再访问路由器的后台管理页面看到设备重新上线。整个过程从用户角度来看不到任何“刷机”动作只是一次简单的页面填写。我还特意验证了断电持久性设备配置好之后拔电再上电WiFi 能自动重连证明配置已经真正落到 NVS 里而不是仅存于内存。这一点是最基本的底线测试建议所有做这个方案的读者都跑一次。5.2 常见问题速查表我只记录真实踩过的坑现象原因解决办法手机连上配置热点后配置页打不开手机还在优先用蜂窝数据浏览网页或者连错了热点手动在浏览器地址栏输入192.168.4.1保存后设备没反应页面白屏HTTP 响应还没发出就重启了server.send后加至少 500ms 延迟再ESP.restart()中文 SSID 搜索不到或连接失败网页提交的 UTF-8 编码与路由器广播的编码不一致用扫描结果点击填入而不是手输填的密码正确但仍然连不上路由器路由器可能开启了 MAC 过滤或隐藏 SSID检查路由器后台把设备 MAC 加入白名单修改 NVS 后重启设备仍连旧网络代码启动逻辑里直接调用了WiFi.begin(固定SSID)确认固件是从 NVS 读配置而不是写死默认凭据烧录后配置页一直不出现烧录工具把 flash 全擦了但 NVS 区存在旧的有效配置检查 NVS 区的读取逻辑或者用prefs.clear()后再测一次NVS 写入返回失败分区表里没有 nvs 分区或分区空间被占满检查分区表确保有 nvs 分区并分配足够大小默认 24KB 通常够用这些坑里第 4 条和第 5 条最隐蔽因为它们不是代码本身的问题而是环境或者逻辑结构的问题。尤其是第 5 条很多人改了配置页却发现设备还是连旧路由器第一个反应是查 NVS 写入但真正的 bug 是固件里还残留着旧的WiFi.begin(old_ssid, old_password)直接绕过了 NVS。排查的时候先全局搜索代码里有没有硬编码的 WiFi 凭据再怀疑存储写入这个顺序能省很多时间。5.3 手写配置页 vs WiFiManager 库选型建议我知道说到这一步肯定有人会问既然 WiFiManager 这种库已经写好了我为什么还要手写我的建议很简单原型项目用 WiFiManager 完全没问题但产品化项目我强烈建议手写或者至少把底层流程吃透。WiFiManager 的优点很明显API 简单autoConnect()一行就能启动配网流程内置 Web 界面、DNS 劫持、参数保存开箱即用。对快速验证、个人DIY、小批量自制设备它确实好用。但用它也会有触到天花板的时候。第一配置页的样式和交互是固定的你想改成一套完整的产品级配置界面比如带设备名称、MQTT 地址、传感器参数就得去读它的源码改内部实现反而比手写更费劲。第二WiFiManager 的异常处理逻辑不一定符合你的产品场景比如它默认在连接失败后重新进入配置模式但什么时候失败、失败几次进入、要不要清空配置这些细粒度控制还是自己写更顺手。第三手写一遍 NVS 方案的整个链路你对设备行为的掌控感是完全不同的后续排查问题不看源码也知道哪里可能出错。所以我的结论是理解原理并且跑通一次手写方案然后把 WiFiManager 当成一个高级轮子来用也行如果你只希望配置页完全符合自己的产品设计直接手写并不复杂花不了半天。我个人在实际项目中已经把 WiFi 配置、MQTT 地址、上报间隔、设备别名全放在 NVS 里统一管理了配置页也扩展成了几个分区页签。每次想到再也不用因为改个密码跑现场心里都踏实很多。最后留一个扩展建议这套 NVS 键值管理方案本质上还能延伸到设备参数备份、批量配置导入导出。你在配网页面写个小功能把整个 namespace 的键值序列化成 JSON一键导出换设备时一键写入整机配置迁移就不再是噩梦了。 
长河君 · 2026/10/3 12:26:58 · 阅读 1.2k ESP32免拆机改WiFi密码：NVS键值存储实现Web配网全解析
ESP32 项目做久了谁都会遇到这么个场景设备已经装到客户现场或者塞在吊顶里结果路由器密码被人改了一次整台设备立刻失联。以前碰到这种情况我基本只有一个办法——跑一趟现场拆设备、找串口线、重新编译烧固件。一套折腾下来半小时起步运气不好就是一下午。后来我在几个项目里陆续换了一种做法把 WiFi 配置从固件里彻底拆出来存进 NVS 键值区然后用设备内置的浏览器配置页直接改键值。这样用户只要手机连上设备的配置热点、打开网页、填个新密码设备重启后就能连上新网络。没错改 WiFi 密码这件事应该从“重刷固件”降级成“改一下 NVS 键值”。这套方案我用了很久思路清晰实现也就半天今天完整拿出来说说。1. 先想清楚WiFi 凭据为什么能独立于固件修改1.1 每次改 WiFi 就重刷固件代价到底有多大先说一个很现实的问题你以为“改个 WiFi 密码”只是改一行WiFi.begin()参数但实际走到现场才明白这行代码背后藏着一整条麻烦链。第一是时间成本。代码里改一个宏定义、重新编译即使是最小的 ESP32 工程编译也要几十秒以上烧录又得几分钟。如果你的工程用了 OTA那还得先把设备从故障状态救回来如果 OTA 链路已经被断网切断就只能用 USB 串口线连电脑硬刷。第二是物理成本。设备一旦部署起来一般不会放在手边。挂在墙上、装在柜子里、塞进设备舱想把它拆下来重刷先得准备螺丝刀、线缆还得考虑断电风险。我见过不少项目为了一个小小的 WiFi 配置问题花四五个小时跑现场结果真正操作只要一分钟。第三是使用者的门槛。设备做出来不是为了只给开发者自己用。最终用户拿到的是一台成品你总不能指望他们打开 Arduino IDE 改代码。在你的认知里是“改一行配置重新编译”在用户眼里就是“这东西坏了”。所以结论很清楚联网设备的 WiFi 配置天生就不应该绑死在固件里。它应该是一份可独立修改的数据而这份数据的存放位置恰好就是 NVS。1.2 NVS 是独立的一块“配置寄存柜”和固件根本不是一回事很多人对 ESP32 的存储结构理解得不够深总觉得“改配置”和“重刷固件”是一回事其实完全不是。ESP32 的 flash 里分了很多个分区固件代码放在 app 分区OTA 临时固件放在 otadata 和 app 等各种区域另外还有一个专门用来存键值数据的 nvs 分区。NVS 全称叫 Non-Volatile Storage非易失性存储本质就是一个基于 flash 的键值数据库。你写进去一个字符串、一个整数、一段二进制数据断电之后它还在再上电还能读出来。用生活类比的话固件是“程序光盘”NVS 是设备旁边的一个“小本子”。程序跑起来会去读这个小本子根据上面记录的 WiFi 名和密码来决定连哪个路由器。你改这个小本子上的内容完全不需要重刻光盘。同理改 NVS 键值也完全不需要重新烧固件。这个机制在 ESP-IDF 和 Arduino 框架里都支持。Arduino 环境下最常用的是 Preferences 库底层封装的就是 NVS 能力。你只要搞清楚固件负责干活NVS 负责记配置两者互不干扰。1.3 一套完整的冷启动逻辑读 NVS → 连 WiFi → 不行就开配置页既然 WiFi 配置存在 NVS 里那设备的启动逻辑就要跟着改不再是简单地在代码里写死WiFi.begin(my_ssid, my_password)而是要变成一条完整的状态机开机后从 NVS 中读取wifinamespace 下的ssid和password键值。如果读取成功且非空进入 STA 模式尝试连接路由器。如果读取不到配置或者连接超时失败进入 AP 配置模式开一个 SoftAP 热点和一个 Web 服务器。用户手机连上这个热点浏览器访问192.168.4.1在网页表单里填入新的 WiFi 名和密码。Web 服务器收到提交后写回 NVS 键值然后调用ESP.restart()重启设备。重启后设备读到新配置按新 Wi-Fi 连接成功。这套逻辑并不复杂但它把“改 WiFi 密码”变成了一次纯用户操作开发者彻底不用到场。这也正是市面上 WiFiManager 库的核心原理——它帮你在后台做了 NVS 的读写。但如果你只知道用库、不理解底层键值是怎么落地的一旦出问题你连排查方向都没有。所以我建议至少手写一遍把原理吃透。2. 动手前先规划好 NVS 键值2.1 namespace 与键名设计一张表说清楚写 NVS 之前第一件事是设计键值结构。ESP32 的 NVS 里每条数据都由 namespace key 两级定位namespace 相当于文件夹key 相当于文件名。我通常会给设备建一个wifinamespace里面放两三个键键名类型说明取值范围ssidString路由器 WiFi 名最长 32 字节passwordStringWiFi 密码最长 63 字节开放网络可留空lastErrorI32 或 String最近一次连接失败原因可选自定义这里有几个关键细节必须注意。NVS 的 key 最长只支持 15 个字符超出会直接报错所以你千万别写什么wifi_router_password_last_time这种键名“password”就够了。另外WiFi 名最长 32 字节、WPA2 密码最长 63 字节这个长度限制要写死在网页校验里别让用户乱填。键值设计也建议留一点扩展空间。设备不可能只存 WiFi 凭据后面大概率还要存 MQTT 服务器地址、设备名称、上报周期、阈值参数等等。我的习惯是另外建一个cfgnamespace 专门放业务配置WiFi 凭据单独放一个wifinamespace逻辑清晰互不干扰。后面想清空配置也很方便——只要清除对应 namespace 就行。2.2 Preferences 还是原生 nvs_flash APIArduino 环境下操作 NVS最舒服的方式是 Preferences 库它把 namespace 和读写逻辑封得干干净净。ESP-IDF 环境下则直接用nvs_flash系列 API更底层、更灵活但代码写起来也啰嗦一点。Preferences 的典型写法如下#include Preferences.h Preferences prefs; // 读取配置 prefs.begin(wifi, true); // 第二个参数 true 表示只读 String ssid prefs.getString(ssid, ); String password prefs.getString(password, ); prefs.end(); // 写入配置 prefs.begin(wifi, false); // 写模式 prefs.putString(ssid, newSsid); prefs.putString(password, newPassword); prefs.end(); // end() 的时候会做 NVS commitPreferences 在底层调用的其实就是 nvs_flash API但它帮你处理了缓存和提交时机。我平时基本用 Preferences因为代码可读性好不容易漏掉nvs_close这种细节。如果你在 ESP-IDF 里开发原生写法大概是nvs_handle_t handle; esp_err_t err; err nvs_open(wifi, NVS_READWRITE, handle); if (err ESP_OK) { nvs_set_str(handle, ssid, newSsid); nvs_set_str(handle, password, newPassword); nvs_commit(handle); nvs_close(handle); }注意这个nvs_commit它才真正把数据落到 flash。Preferences 的end()也会触发 commit所以别小看这个动作写 NVS 不做 commit等于白干。2.3 首次开机没有配置怎么办新设备第一次上电NVS 里是空的此时如果固件一上来就强制进 STA 模式那就永远连不上网。所以启动逻辑里一定要有一个判断NVS 里读到的 ssid 为空或密码不符合基本长度就自动进入 AP 配置模式。这也意味着“出厂默认配置”这个概念要看场景。开发阶段你可以在代码里留一个默认 WiFi 宏方便自己快速联调但真正部署给客户时最好不要写死默认 WiFi 凭据。客户家的路由器名和密码你根本不知道就算你知道隔几个月换一次密码你的默认配置就废了。让设备首次开机自动开配置页是最稳妥的产品行为。还有一个细节NVS 键值如果以前存过一遍之后想更新也不难但要注意清理旧键。Preferences 的remove可以移除单个键clear()可以清空整个 namespace。我在“恢复出厂”功能里就是这么做的。3. 浏览器配置页内嵌 Web 服务器的实现细节3.1 页面从哪里来直接内嵌还是挂文件系统浏览器配置页的核心是 ESP32 上跑一个 Web 服务器。常见做法有两种把 HTML 字符串直接写在代码里或者把网页文件放在 LittleFS/SPIFFS 文件系统里动态读取。小项目、快速原型、配置页就一个表单的情况下我强烈建议直接内嵌字符串。代码量小不涉及文件系统挂载串口烧录时也不用额外烧录文件系统镜像。一个简单的配置页HTML 加起来也就几行到几十行直接拼字符串发送完全够用。如果配置页涉及大量前端逻辑、多语言、样式复杂再考虑 LittleFS。文件系统方案的好处是前端代码和固件分离改网页不一定要重新烧固件但这也增加了复杂度和打包流程。我的经验是先内嵌字符串跑通等界面真的复杂到不可维护了再迁移到文件系统不要一开始就上重型方案。内嵌页面代码大概长这样#include WiFi.h #include WebServer.h WebServer server(80); void handleRoot() { String html !DOCTYPE htmlhtmlheadmeta charsetutf-8titleWiFi 配置/title/head body stylefont-family:sans-serif;margin:2rem h2WiFi 配置/h2 form methodPOST action/save labelWiFi 名称/labelbr input namessid maxlength32 placeholder输入路由器 SSID stylewidth:90%;padding:.5rembrbr labelWiFi 密码/labelbr input namepassword typepassword maxlength63 placeholder留空表示开放网络 stylewidth:90%;padding:.5rembrbr button typesubmit stylepadding:.5rem 1rem;background:#1b8f5b;color:#fff;border:0保存并重启/button /form pa href/clear stylecolor:#999清除配置并进入 AP 模式/a/p /body/html; server.send(200, text/html, html); }这段代码在 AP 模式下能直接跑浏览器访问192.168.4.1就能看到页面。3.2 保存流程校验参数、写 NVS、重启并确认配置页表单的 action 指向/save提交方式用 POST。服务端收到请求以后一定不要直接写入重启先做参数校验。校验点至少有三个ssid 非空长度不超过 32 字节。password 长度不超过 63 字节如果非空则不能小于 8 位因为 WPA2 密码最短就是 8 位。可选如果想让用户输入“开放网络”场景允许 password 为空但要明确提示。校验通过后执行写入 NVS 并重启。这里有一个经验细节HTTP 响应要先发出去设备再重启。如果你一写入 NVS 立刻调用ESP.restart()浏览器这边连接直接被断开用户看到的往往是一片空白体验很不好。正确做法是server.send(200, ...)之后再delay(500)确保响应包已经离开协议栈然后再重启。保存接口的完整代码void handleSave() { if (!server.hasArg(ssid)) { server.send(400, text/plain, missing ssid); return; } String ssid server.arg(ssid); String password server.arg(password); ssid.trim(); if (ssid.length() 0 || ssid.length() 32) { server.send(400, text/plain, ssid invalid); return; } if (password.length() 0 password.length() 8) { server.send(400, text/plain, password too short); return; } prefs.begin(wifi, false); prefs.putString(ssid, ssid); prefs.putString(password, password); prefs.end(); server.send(200, text/plain, saved, restarting...); delay(500); ESP.restart(); }/clear处理也很简单清除 namespace 后重启进 APvoid handleClear() { prefs.begin(wifi, false); prefs.clear(); prefs.end(); server.send(200, text/plain, cleared, restarting...); delay(500); ESP.restart(); }3.3 配置页顺手加一个扫描 WiFi 功能解决中文 SSID 的坑很多人做配置页的时候只放两个输入框我建议加一个“扫描 WiFi”按钮让设备扫描周围网络并把结果列出来用户点击某一项自动填入 ssid 输入框。这个功能不仅体验好更重要的是能帮你绕开中文 SSID 的编码坑。ESP32 的 WiFi 扫描结果是驱动直接返回的原始字节序列当你从扫描结果里拿到 SSID 并原样填入表单时字节内容不会经过手打输入就不会出现编码转换问题。如果让用户手动敲一个中文 WiFi 名网页大概率按 UTF-8 提交而不少老路由器广播的是 GBK 编码两边对不上直接导致设备搜索不到目标网络。这个坑我踩过一次后来再也不敢让用户手输中文 SSID 了。扫描接口可以写成返回 JSON 列表void handleScan() { int n WiFi.scanNetworks(); String json [; for (int i 0; i n; i) { if (i) json ,; json {\ssid\:\ WiFi.SSID(i) \,\rssi\: String(WiFi.RSSI(i)) }; } json ]; WiFi.scanDelete(); server.send(200, application/json, json); }注意这个示例里的 JSON 没有做引号转义。如果环境中存在 SSID 里带双引号的怪名字前端解析就会出问题。生产环境建议用 ArduinoJson 库来序列化而不是手拼字符串。3.4 进阶体验DNS 劫持让配网页面自动弹出光有一个 Web 页面用户还得手动输入192.168.4.1对非技术用户来说还是不够傻瓜。更好的做法是加一个 DNS 劫持也就是 Captive Portal 思路用户连上设备的热点后不管他打开什么网址都会被重定向到配置页。原理很简单AP 模式下监听 53 端口的 DNS 请求把所有域名解析都指向192.168.4.1。这样用户手机连上热点随便点开一个网页系统自动弹出配置页不需要记 IP。在 ESP32 上用 DNSServer 库就能实现#include DNSServer.h DNSServer dnsServer; IPAddress apIP(192, 168, 4, 1); dnsServer.start(53, *, apIP); // loop 里 dnsServer.processNextRequest();这里有一个重要警告DNS 劫持只能在 AP 配置模式下开启。设备正常连上路由器、进入 STA 模式后绝不能继续运行 DNS 劫持否则会把设备所在局域网内的所有域名解析都拦截掉影响范围瞬间扩大。我见过有人把 DNSServer 的start无条件放在setup()里结果设备正常工作时全家网络 DNS 都被污染了排查了整半天。4. 防失联设计连接失败后自动回到配置页4.1 连接超时与失败重试的推荐参数如果用户把 WiFi 密码填错了或者路由器没开机设备的表现不能是“傻等”或彻底失联它应该在失败后自动回到配置模式给用户第二次机会。我测试下来比较稳的一组参数是单次 STA 连接超时 15 秒连续失败 3 次后进入 AP 模式。这个 15 秒很关键太短了有些信号弱的路由器还没来得及回包就被判失败太长了用户现场调试验证时等得着急。15 秒属于折中实测大部分路由器在 2 到 8 秒内就能完成握手15 秒足够覆盖大多数异常情况。连接逻辑可以这样写bool connectToSTA(const String ssid, const String password) { WiFi.mode(WIFI_STA); WiFi.begin(ssid.c_str(), password.c_str()); uint32_t start millis(); while (WiFi.status() ! WL_CONNECTED millis() - start 15000) { delay(200); } return WiFi.status() WL_CONNECTED; }主流程里如果这个函数返回 false就进入startAPMode()。这个自动回退机制是设备最后一道保住可用性的防线务必加上。4.2 物理按键兜底长按进入 AP 模式软件逻辑做得再完善也挡不住一些极端情况比如用户设备已经配过网但现在家里换了个新路由器而旧路由器已经被搬走了设备启动后连不上旧网络按理说会自动回 AP 模式。但如果你的回退策略次数限制设得太高或者设备短暂连上过新路由器后来又被踢下线用户还是不知道怎么重新触发配置。这时候一个物理按键兜底很有价值。ESP32 开发板上通常自带一个 BOOT 键对应 GPIO0默认上拉按下为低电平。我们可以设置一个“长按 5 秒清除 NVS 并进入 AP 模式”的功能。实现思路const int BUTTON_PIN 0; uint32_t pressStart 0; void loop() { if (digitalRead(BUTTON_PIN) LOW) { if (pressStart 0) pressStart millis(); if (millis() - pressStart 5000) { prefs.begin(wifi, false); prefs.clear(); prefs.end(); ESP.restart(); } } else { pressStart 0; } }这个按钮在开发和维护阶段也是救命稻草设备要换环境、换网络按 5 秒就能恢复出厂配置流程完全不需要拆机。4.3 用 LED 快速判断设备状态排查现场问题的时候没有串口输出也没有网页可看这时候板载 LED 就是唯一的“显示器”。我习惯把 LED 状态设计得很简单LED 状态含义每秒快闪 2 次AP 配置模式等待用户配网慢闪2 秒一次正在尝试连接路由器常亮已连接路由器正常工作逻辑不复杂就是在loop()里根据设备状态控制 GPIO。别小看这个功能现场工程师不需要连终端就能判断当前设备处在哪个环节排查效率高很多。5. 实测全流程与常见问题速查5.1 完整实测链路从烧录到换密码我按这个方案在 ESP32 DevKitC 上完整跑过一遍。硬件就是一块普通开发板加一个板载 LED没有外接任何元器件。第一次烧录时烧录工具里我特意保留了 NVS 分区。这里要提醒一句很多烧录工具默认是“全擦 flash”如果你之前已经通过配置页写过 WiFi 信息全擦会把 NVS 里的配置一并清掉。日常迭代固件时最好只擦 app 分区或者明确确认要保留配置。实测流程如下烧录固件设备启动后 NVS 为空自动进入 AP 模式。手机 WiFi 列表里看到一个ESP32_Config的热点连接它。注意配网模式下设备没有外网手机会提示“此 Wi-Fi 无法连接互联网”这是正常的不要惊慌。浏览器打开192.168.4.1配置页正常显示。点击“扫描 WiFi”附近的路由器列表都出来了点击家里的网络SSID 自动填入。输入密码点“保存并重启”浏览器显示 “saved, restarting...”页面稍后断开设备进入重启流程。手机切回家里 WiFi再访问路由器的后台管理页面看到设备重新上线。整个过程从用户角度来看不到任何“刷机”动作只是一次简单的页面填写。我还特意验证了断电持久性设备配置好之后拔电再上电WiFi 能自动重连证明配置已经真正落到 NVS 里而不是仅存于内存。这一点是最基本的底线测试建议所有做这个方案的读者都跑一次。5.2 常见问题速查表我只记录真实踩过的坑现象原因解决办法手机连上配置热点后配置页打不开手机还在优先用蜂窝数据浏览网页或者连错了热点手动在浏览器地址栏输入192.168.4.1保存后设备没反应页面白屏HTTP 响应还没发出就重启了server.send后加至少 500ms 延迟再ESP.restart()中文 SSID 搜索不到或连接失败网页提交的 UTF-8 编码与路由器广播的编码不一致用扫描结果点击填入而不是手输填的密码正确但仍然连不上路由器路由器可能开启了 MAC 过滤或隐藏 SSID检查路由器后台把设备 MAC 加入白名单修改 NVS 后重启设备仍连旧网络代码启动逻辑里直接调用了WiFi.begin(固定SSID)确认固件是从 NVS 读配置而不是写死默认凭据烧录后配置页一直不出现烧录工具把 flash 全擦了但 NVS 区存在旧的有效配置检查 NVS 区的读取逻辑或者用prefs.clear()后再测一次NVS 写入返回失败分区表里没有 nvs 分区或分区空间被占满检查分区表确保有 nvs 分区并分配足够大小默认 24KB 通常够用这些坑里第 4 条和第 5 条最隐蔽因为它们不是代码本身的问题而是环境或者逻辑结构的问题。尤其是第 5 条很多人改了配置页却发现设备还是连旧路由器第一个反应是查 NVS 写入但真正的 bug 是固件里还残留着旧的WiFi.begin(old_ssid, old_password)直接绕过了 NVS。排查的时候先全局搜索代码里有没有硬编码的 WiFi 凭据再怀疑存储写入这个顺序能省很多时间。5.3 手写配置页 vs WiFiManager 库选型建议我知道说到这一步肯定有人会问既然 WiFiManager 这种库已经写好了我为什么还要手写我的建议很简单原型项目用 WiFiManager 完全没问题但产品化项目我强烈建议手写或者至少把底层流程吃透。WiFiManager 的优点很明显API 简单autoConnect()一行就能启动配网流程内置 Web 界面、DNS 劫持、参数保存开箱即用。对快速验证、个人DIY、小批量自制设备它确实好用。但用它也会有触到天花板的时候。第一配置页的样式和交互是固定的你想改成一套完整的产品级配置界面比如带设备名称、MQTT 地址、传感器参数就得去读它的源码改内部实现反而比手写更费劲。第二WiFiManager 的异常处理逻辑不一定符合你的产品场景比如它默认在连接失败后重新进入配置模式但什么时候失败、失败几次进入、要不要清空配置这些细粒度控制还是自己写更顺手。第三手写一遍 NVS 方案的整个链路你对设备行为的掌控感是完全不同的后续排查问题不看源码也知道哪里可能出错。所以我的结论是理解原理并且跑通一次手写方案然后把 WiFiManager 当成一个高级轮子来用也行如果你只希望配置页完全符合自己的产品设计直接手写并不复杂花不了半天。我个人在实际项目中已经把 WiFi 配置、MQTT 地址、上报间隔、设备别名全放在 NVS 里统一管理了配置页也扩展成了几个分区页签。每次想到再也不用因为改个密码跑现场心里都踏实很多。最后留一个扩展建议这套 NVS 键值管理方案本质上还能延伸到设备参数备份、批量配置导入导出。你在配网页面写个小功能把整个 namespace 的键值序列化成 JSON一键导出换设备时一键写入整机配置迁移就不再是噩梦了。