1. 为什么改个 WiFi 密码要动固件搞过 ESP32 项目的人大概率都经历过这个场景设备已经装到现场了外壳封好、螺丝拧紧、电源接上结果甲方或者自己突然想换个 WiFi 密码。按照传统做法你得把设备拆下来连上电脑打开 Arduino IDE 或者 ESP-IDF改代码里的ssid和password重新编译重新烧录再装回去。整个过程少说十几分钟多则半小时如果设备装在不好够到的地方那体验简直酸爽。这个问题的本质在于WiFi 凭据被硬编码在固件里了。编译的时候写死运行时从代码常量读取改一次就得重新走一遍编译烧录流程。而 ESP32 本身是带 NVSNon-Volatile Storage非易失性存储的NVS 就是一块专门用来存键值对数据的 Flash 分区掉电不丢。WiFi 的 SSID 和密码完全可以存在 NVS 里运行时从 NVS 读这样改密码就变成了改一个键值对根本不需要碰固件。那为什么很多人还是硬编码因为改 NVS 需要额外的工具和通道。串口可以改但得接线蓝牙可以改但得写 APPMQTT 可以改但设备得先连上网——鸡生蛋蛋生鸡。所以最优雅的方案是在 ESP32 上跑一个内嵌 Web 服务器浏览器打开一个页面就能直接读写 NVS 键值。设备本身作为一个 WiFi 热点或者连在局域网里手机、电脑打开浏览器就能操作不需要装任何软件不需要接线不需要重新烧录。这篇文章就把这套方案的完整实现思路拆开讲清楚。从 NVS 的存储原理、Web 服务器的搭建、键值编辑页面的设计到实际部署中会遇到的各种坑比如并发写入、分区大小、掉电保护、安全认证等等。适合已经会用 Arduino 框架或者 ESP-IDF 开发 ESP32、想给设备加一个免拆机配置能力的开发者。读完你就能把这套东西移植到自己的项目里以后改 WiFi 密码、改设备参数浏览器点几下就完事。2. NVS 到底能存什么、怎么存、有什么坑2.1 NVS 的存储结构和读写机制NVS 在 ESP32 的 Flash 里是一块独立的分区默认大小通常是 0x500020KB在分区表里以nvs类型标记。它的内部结构不是简单的文件系统而是一套基于页page和条目entry的键值存储引擎。每个页默认 4096 字节页头记录状态信息后面跟着若干条目每个条目包含键名最长 15 个字符、数据类型和值。支持的数据类型包括uint8_t、int8_t、uint16_t、int16_t、uint32_t、int32_t、uint64_t、int64_t、字符串包括 blob。对于 WiFi 密码这种场景用字符串类型就够了。键名建议用简短的英文标识比如wifi_ssid、wifi_pass因为键名长度直接影响存储效率。读写 API 在 Arduino 框架下是Preferences库在 ESP-IDF 下是nvs.h。两者底层一样只是封装不同。Preferences用起来更简单#include Preferences.h Preferences prefs; void saveWifiConfig(const char* ssid, const char* pass) { prefs.begin(wifi, false); // 命名空间 wififalse 表示读写模式 prefs.putString(ssid, ssid); prefs.putString(pass, pass); prefs.end(); } String loadSsid() { prefs.begin(wifi, true); // true 表示只读模式 String s prefs.getString(ssid, ); prefs.end(); return s; }这里有个细节begin()的第二个参数是只读标志。如果你只是读取传true可以减少不必要的写入操作延长 Flash 寿命。NVS 的写入次数是有限的虽然 ESP32 的 Flash 通常能撑 10 万次擦写但频繁写入还是会加速老化。2.2 命名空间的设计与隔离NVS 支持命名空间namespace相当于数据库里的表。不同功能模块用不同命名空间互不干扰。比如 WiFi 配置放wifi命名空间设备参数放device命名空间用户数据放user命名空间。这样做的好处是清空某个模块的配置时不会误删其他数据。命名空间名称最长 15 个字符建议用有意义的短名称。实际项目中我见过有人把所有东西都塞进一个叫config的命名空间结果键名冲突、管理混乱。分开命名空间之后代码可读性和维护性都会好很多。2.3 NVS 的容量限制和分区调整默认 20KB 的 NVS 分区对于存几个 WiFi 凭据来说绰绰有余但如果你打算存大量数据比如日志、用户列表就需要调整分区表。在 Arduino 框架下可以通过Tools - Partition Scheme选择不同的分区方案或者自定义partitions.csv文件。一个典型的自定义分区表长这样# Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x5000, otadata, data, ota, 0xe000, 0x2000, app0, app, ota_0, 0x10000, 0x140000, app1, app, ota_1, 0x150000,0x140000, spiffs, data, spiffs, 0x290000,0x160000,如果你把 NVS 改大比如改成0x1000064KB那就要相应调整后面分区的偏移地址。改分区表有风险改错了设备起不来建议改之前先备份原始分区表。注意NVS 分区一旦格式化里面所有数据都会丢失。ESP32 在 NVS 分区损坏或者首次使用时会自动格式化但如果你手动调用了nvs_flash_erase()那就是彻底清空。2.4 掉电保护和写入原子性NVS 的设计本身有一定的掉电保护能力。它采用页轮转机制写入新数据时先写到新页写完了再标记旧页为无效最后擦除。这个过程如果中途掉电最坏情况是这次写入没生效但不会破坏已有数据。不过如果你在代码里连续写入多个键值对中间掉电可能导致部分写入成功、部分失败。比如先写 SSID 再写密码写到一半断电结果 SSID 是新的、密码是旧的设备就连不上了。解决办法是要么把相关配置打包成一个 blob 一次性写入要么在写入完成后做一个校验标记。// 打包写入示例 struct WifiConfig { char ssid[32]; char pass[64]; uint32_t crc; }; void saveWifiConfigAtomic(const char* ssid, const char* pass) { WifiConfig cfg; strncpy(cfg.ssid, ssid, sizeof(cfg.ssid)); strncpy(cfg.pass, pass, sizeof(cfg.pass)); cfg.crc calculateCRC(cfg, sizeof(cfg) - sizeof(cfg.crc)); prefs.begin(wifi, false); prefs.putBytes(config, cfg, sizeof(cfg)); prefs.end(); }读取的时候先校验 CRC不匹配就说明数据损坏回退到默认配置。这套机制在工业现场特别有用因为现场断电是家常便饭。3. 在 ESP32 上搭一个能改 NVS 的 Web 服务器3.1 Web 服务器的选型ESPAsyncWebServer 还是同步方案ESP32 上跑 Web 服务器有两个主流选择同步的WebServer库Arduino 自带和异步的ESPAsyncWebServer。同步方案代码简单但每个请求都会阻塞主循环如果同时有多个请求或者请求处理时间较长设备会显得很卡。异步方案基于事件回调不阻塞能同时处理多个连接适合这种配置页面场景。我实测下来ESPAsyncWebServer在响应速度和并发处理上明显优于同步方案。特别是当你需要在处理请求的同时维持 WiFi 连接、跑其他任务时异步方案几乎是必选。安装方式也简单Arduino IDE 的库管理器里搜ESPAsyncWebServer和AsyncTCP就行。#include WiFi.h #include ESPAsyncWebServer.h #include Preferences.h AsyncWebServer server(80); Preferences prefs;这里有个版本兼容性问题ESPAsyncWebServer对 ESP32 核心库的版本比较敏感。如果你用的是较新的 ESP32 Arduino Core3.x可能需要用特定分支的库。我踩过的坑是核心库 3.0.0 配老版本 AsyncWebServer 编译报错换成 GitHub 上最新的 master 分支就好了。3.2 配网模式与常连模式的切换逻辑设备启动时应该先尝试用 NVS 里存的凭据连 WiFi。如果连不上比如密码改了、路由器换了就自动切换到 AP 模式自己做一个热点让用户连上来配置。这个逻辑用状态机实现最清晰enum WifiState { CONNECTING, CONNECTED, AP_MODE }; WifiState currentState CONNECTING; void setupWifi() { String ssid loadSsid(); String pass loadPass(); if (ssid.length() 0) { enterApMode(); return; } WiFi.begin(ssid.c_str(), pass.c_str()); unsigned long start millis(); while (WiFi.status() ! WL_CONNECTED millis() - start 15000) { delay(500); } if (WiFi.status() WL_CONNECTED) { currentState CONNECTED; Serial.println(WiFi.localIP()); } else { enterApMode(); } } void enterApMode() { WiFi.mode(WIFI_AP); WiFi.softAP(ESP32-Config, 12345678); currentState AP_MODE; Serial.println(WiFi.softAPIP()); }AP 模式的默认密码建议设一个简单的比如12345678方便用户第一次连接。但要注意这个密码也应该允许用户修改否则就成了固定后门。可以在 Web 页面里加一个修改 AP 密码的选项存到 NVS 的另一个键里。3.3 路由设计读取、写入、重启三个核心接口Web 服务器只需要三个核心路由一个返回当前配置的 HTML 页面一个接收 POST 请求写入新配置一个触发重启。页面用简单的 HTML 表单就行不需要前端框架减少 Flash 占用。const char index_html[] PROGMEM Rrawliteral( !DOCTYPE html html head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleESP32 配置/title style body { font-family: Arial; max-width: 400px; margin: 40px auto; padding: 20px; } input { width: 100%; padding: 10px; margin: 8px 0; box-sizing: border-box; } button { width: 100%; padding: 12px; background: #007bff; color: white; border: none; } /style /head body h2WiFi 配置/h2 form action/save methodPOST labelSSID/label input typetext namessid value%SSID% maxlength32 label密码/label input typetext namepass value%PASS% maxlength64 button typesubmit保存并重启/button /form /body /html )rawliteral;注意%SSID%和%PASS%是占位符需要在请求处理时替换成实际值。ESPAsyncWebServer提供了processor机制来做模板替换String processor(const String var) { if (var SSID) return loadSsid(); if (var PASS) return loadPass(); return String(); } server.on(/, HTTP_GET, [](AsyncWebServerRequest *request) { request-send_P(200, text/html, index_html, processor); });写入接口用 POST 处理从请求体里解析表单数据server.on(/save, HTTP_POST, [](AsyncWebServerRequest *request) { if (request-hasParam(ssid, true) request-hasParam(pass, true)) { String ssid request-getParam(ssid, true)-value(); String pass request-getParam(pass, true)-value(); saveWifiConfig(ssid.c_str(), pass.c_str()); request-send(200, text/plain, 保存成功设备将在 3 秒后重启); delay(3000); ESP.restart(); } else { request-send(400, text/plain, 参数缺失); } });这里有个细节hasParam的第二个参数true表示从 POST body 里取false表示从 URL query 里取。表单提交默认是application/x-www-form-urlencoded所以要用true。3.4 页面模板的轻量化处理ESP32 的 Flash 和 RAM 都有限页面不能太臃肿。我见过有人往 ESP32 里塞 Bootstrap 和 jQuery结果编译出来固件快 2MB运行起来还卡。其实配置页面只需要最基本的 HTML 和 CSS几十行就够了。把 HTML 用PROGMEM存到 Flash 里不占 RAM。如果需要更复杂的交互比如实时显示 WiFi 扫描结果可以用一小段原生 JavaScript 发 AJAX 请求但不要引入任何框架。ESP32 的 Web 服务器处理能力有限前端越简单越稳。4. 键值编辑页面的交互细节与安全考量4.1 表单字段的校验与边界处理用户输入是不可信的。SSID 最长 32 字节密码最长 64 字节WPA2 标准这些边界必须在服务端校验。如果用户输入超长字符串直接写入 NVS 可能导致截断或者写入失败。bool validateInput(const String ssid, const String pass) { if (ssid.length() 0 || ssid.length() 32) return false; if (pass.length() 0 pass.length() 8) return false; // WPA2 最少 8 位 if (pass.length() 64) return false; return true; }另外SSID 里可能包含特殊字符比如中文、空格、引号。这些在 HTML 表单里需要正确转义否则页面会乱掉。ESPAsyncWebServer的send_P不会自动转义需要自己处理。简单做法是在processor里对返回值做 HTML 实体编码String htmlEscape(const String input) { String output input; output.replace(, amp;); output.replace(, lt;); output.replace(, gt;); output.replace(\, quot;); return output; }4.2 配置页面的访问控制AP 模式下任何连上热点的人都能访问配置页面。如果设备部署在公共场所这就是个安全隐患。至少应该加一个简单的 HTTP Basic Authserver.on(/, HTTP_GET, [](AsyncWebServerRequest *request) { if (!request-authenticate(admin, esp32config)) { return request-requestAuthentication(); } request-send_P(200, text/html, index_html, processor); });用户名和密码也可以存在 NVS 里允许用户修改。但要注意HTTP Basic Auth 是明文传输的在局域网里问题不大但如果设备暴露在公网不建议这么做就必须上 HTTPS。ESP32 跑 HTTPS 会消耗大量 RAM一般项目没必要。4.3 写入后的状态反馈与重启策略用户点击保存后设备需要重启才能用新配置连 WiFi。但直接重启会让浏览器显示连接中断用户体验不好。我的做法是先返回一个保存成功即将重启的页面延迟 3 秒再重启。这样浏览器能正常收到响应用户也能看到提示。request-send(200, text/html, h3保存成功/h3p设备将在 3 秒后重启请重新连接 WiFi。/p scriptsetTimeout((){location.href/;}, 5000);/script);重启后如果新配置正确设备会连上新的 WiFiAP 模式关闭。如果配置错误设备会再次进入 AP 模式用户可以重新配置。这个失败回退机制很重要否则配错了就只能拆机。4.4 多用户并发写入的冲突避免虽然配置页面通常只有一个人用但万一两个人同时打开页面提交就可能出现写入冲突。NVS 本身没有锁机制两个任务同时写同一个键可能出问题。简单的解决办法是加一个软件标志位volatile bool isSaving false; server.on(/save, HTTP_POST, [](AsyncWebServerRequest *request) { if (isSaving) { request-send(429, text/plain, 正在保存请稍后重试); return; } isSaving true; // ... 保存逻辑 ... isSaving false; });更严谨的做法是用 FreeRTOS 的互斥锁mutex但对于这种低频操作一个布尔标志就够了。5. 实际部署中遇到的坑与排查过程5.1 连不上 WiFi 但 AP 模式也进不去有一次我把设备装到现场上电后既连不上原来的 WiFi也搜不到 AP 热点。排查了半天发现是 NVS 里的 SSID 存了一个空字符串但代码逻辑判断ssid.length() 0才进 AP 模式而空字符串的长度确实是 0应该进 AP 才对。后来发现是loadSsid()返回了乱码因为 NVS 分区被意外格式化了读取时返回了默认值但默认值我设的是按理说没问题。最终定位到是Preferences库的begin()调用失败返回了false但我没检查返回值后续的getString就返回了未定义内容。修复方法很简单检查begin()的返回值失败就进 AP 模式。bool loadWifiConfig(String ssid, String pass) { if (!prefs.begin(wifi, true)) { return false; } ssid prefs.getString(ssid, ); pass prefs.getString(pass, ); prefs.end(); return ssid.length() 0; }这个坑的教训是所有 NVS 操作都要检查返回值不能假设一定成功。5.2 保存后重启新密码不生效另一个常见问题是用户保存了新密码设备重启后还是连不上。排查发现是保存的时候写入了 NVS但重启后读取的还是旧值。原因是Preferences的putString之后没有调用end()数据还在缓存里没刷到 Flash。Preferences库在end()时才会真正提交写入如果中间断电或者直接重启数据就丢了。修复方法每次写入后必须调用end()或者用prefs.putString后跟一个prefs.end()。另外写入完成后最好加一个短暂的延迟比如 100ms确保 Flash 操作完成。5.3 页面加载慢或者样式丢失有用户反馈配置页面打开要好几秒而且 CSS 不生效。排查发现是 HTML 页面太大而且每次请求都从 Flash 读取并拼接字符串效率低。优化方法是把静态部分用PROGMEM存储动态部分只替换占位符。另外CSS 直接内联在 HTML 里不要单独请求.css文件减少 HTTP 请求次数。还有一个细节ESPAsyncWebServer默认的 TCP 发送缓冲区较小如果页面超过 2KB可能会分多次发送导致浏览器渲染慢。可以在AsyncWebServer初始化时调整缓冲区大小或者把页面压缩到 2KB 以内。5.4 AP 模式下手机连不上或者频繁掉线ESP32 的 AP 模式默认最多支持 4 个客户端而且如果信道拥挤连接会不稳定。我遇到过手机连上 AP 后几秒就断开的情况排查发现是 AP 的信道和周围路由器冲突。解决办法是在softAP时指定一个相对空闲的信道WiFi.softAP(ESP32-Config, 12345678, 6); // 指定信道 6另外AP 模式下如果同时尝试连接路由器STA 模式会互相干扰。建议在 AP 模式下关闭 STA 接口只保留 AP。6. 从能用到好用几个提升体验的扩展思路6.1 扫描周围 WiFi 并下拉选择让用户手动输入 SSID 容易出错尤其是那些隐藏了 SSID 或者名字很长的网络。可以在配置页面加一个扫描按钮点击后 ESP32 扫描周围 WiFi把结果返回给前端用下拉框展示。server.on(/scan, HTTP_GET, [](AsyncWebServerRequest *request) { int n WiFi.scanNetworks(); String json [; for (int i 0; i n; i) { if (i 0) json ,; json {\ssid\:\ WiFi.SSID(i) \,\rssi\: String(WiFi.RSSI(i)) }; } json ]; request-send(200, application/json, json); });前端用一小段 JavaScript 发请求并填充下拉框。注意扫描操作会阻塞几秒钟期间 WiFi 连接会中断所以最好在 AP 模式下做这个操作。6.2 配置导入导出与批量部署如果你有多个设备要部署一个个配置太麻烦。可以加一个导出功能把当前 NVS 里的配置以 JSON 格式下载下来然后在其他设备上导入。实现方式就是加两个路由/export返回 JSON/import接收 JSON 并写入 NVS。这个功能在批量生产或者现场调试时特别有用。我做过一个项目20 台设备用导出导入功能5 分钟全部配好比一台台手动输入快多了。6.3 OTA 升级与配置保留的配合设备支持 OTA 升级后固件更新不会影响 NVS 里的配置这是 NVS 的一大优势。但要注意如果新固件改了 NVS 的键名或者数据结构旧配置可能读不出来。解决办法是在固件里加一个版本号启动时检查 NVS 里的配置版本不匹配就迁移或者重置。#define CONFIG_VERSION 2 void checkConfigVersion() { prefs.begin(wifi, false); uint32_t ver prefs.getUInt(cfg_ver, 0); if (ver ! CONFIG_VERSION) { // 执行迁移逻辑 prefs.putUInt(cfg_ver, CONFIG_VERSION); } prefs.end(); }6.4 把配置页面做成可复用的组件如果你经常做 ESP32 项目建议把这套 Web 配置功能封装成一个独立的库或者头文件下次直接引用。核心接口就三个beginConfigPortal()启动服务器loadConfig()读取配置saveConfig()保存配置。这样不同项目之间可以复用不用每次都重写。我在实际使用中发现把这套东西封装好之后新项目的配置功能开发时间从半天缩短到十分钟。而且因为经过了多个项目的验证稳定性也有保障。最后分享一个小技巧在 NVS 里存一个config_dirty标志位每次保存配置时置位设备成功连上 WiFi 后清零。如果启动时发现这个标志是置位的说明上次配置后没连上可以自动进入 AP 模式让用户重新配置。这个机制能避免设备变砖在现场部署时特别有用。
1. 为什么改个 WiFi 密码要动固件搞过 ESP32 项目的人大概率都经历过这个场景设备已经装到现场了外壳封好、螺丝拧紧、电源接上结果甲方或者自己突然想换个 WiFi 密码。按照传统做法你得把设备拆下来连上电脑打开 Arduino IDE 或者 ESP-IDF改代码里的ssid和password重新编译重新烧录再装回去。整个过程少说十几分钟多则半小时如果设备装在不好够到的地方那体验简直酸爽。这个问题的本质在于WiFi 凭据被硬编码在固件里了。编译的时候写死运行时从代码常量读取改一次就得重新走一遍编译烧录流程。而 ESP32 本身是带 NVSNon-Volatile Storage非易失性存储的NVS 就是一块专门用来存键值对数据的 Flash 分区掉电不丢。WiFi 的 SSID 和密码完全可以存在 NVS 里运行时从 NVS 读这样改密码就变成了改一个键值对根本不需要碰固件。那为什么很多人还是硬编码因为改 NVS 需要额外的工具和通道。串口可以改但得接线蓝牙可以改但得写 APPMQTT 可以改但设备得先连上网——鸡生蛋蛋生鸡。所以最优雅的方案是在 ESP32 上跑一个内嵌 Web 服务器浏览器打开一个页面就能直接读写 NVS 键值。设备本身作为一个 WiFi 热点或者连在局域网里手机、电脑打开浏览器就能操作不需要装任何软件不需要接线不需要重新烧录。这篇文章就把这套方案的完整实现思路拆开讲清楚。从 NVS 的存储原理、Web 服务器的搭建、键值编辑页面的设计到实际部署中会遇到的各种坑比如并发写入、分区大小、掉电保护、安全认证等等。适合已经会用 Arduino 框架或者 ESP-IDF 开发 ESP32、想给设备加一个免拆机配置能力的开发者。读完你就能把这套东西移植到自己的项目里以后改 WiFi 密码、改设备参数浏览器点几下就完事。2. NVS 到底能存什么、怎么存、有什么坑2.1 NVS 的存储结构和读写机制NVS 在 ESP32 的 Flash 里是一块独立的分区默认大小通常是 0x500020KB在分区表里以nvs类型标记。它的内部结构不是简单的文件系统而是一套基于页page和条目entry的键值存储引擎。每个页默认 4096 字节页头记录状态信息后面跟着若干条目每个条目包含键名最长 15 个字符、数据类型和值。支持的数据类型包括uint8_t、int8_t、uint16_t、int16_t、uint32_t、int32_t、uint64_t、int64_t、字符串包括 blob。对于 WiFi 密码这种场景用字符串类型就够了。键名建议用简短的英文标识比如wifi_ssid、wifi_pass因为键名长度直接影响存储效率。读写 API 在 Arduino 框架下是Preferences库在 ESP-IDF 下是nvs.h。两者底层一样只是封装不同。Preferences用起来更简单#include Preferences.h Preferences prefs; void saveWifiConfig(const char* ssid, const char* pass) { prefs.begin(wifi, false); // 命名空间 wififalse 表示读写模式 prefs.putString(ssid, ssid); prefs.putString(pass, pass); prefs.end(); } String loadSsid() { prefs.begin(wifi, true); // true 表示只读模式 String s prefs.getString(ssid, ); prefs.end(); return s; }这里有个细节begin()的第二个参数是只读标志。如果你只是读取传true可以减少不必要的写入操作延长 Flash 寿命。NVS 的写入次数是有限的虽然 ESP32 的 Flash 通常能撑 10 万次擦写但频繁写入还是会加速老化。2.2 命名空间的设计与隔离NVS 支持命名空间namespace相当于数据库里的表。不同功能模块用不同命名空间互不干扰。比如 WiFi 配置放wifi命名空间设备参数放device命名空间用户数据放user命名空间。这样做的好处是清空某个模块的配置时不会误删其他数据。命名空间名称最长 15 个字符建议用有意义的短名称。实际项目中我见过有人把所有东西都塞进一个叫config的命名空间结果键名冲突、管理混乱。分开命名空间之后代码可读性和维护性都会好很多。2.3 NVS 的容量限制和分区调整默认 20KB 的 NVS 分区对于存几个 WiFi 凭据来说绰绰有余但如果你打算存大量数据比如日志、用户列表就需要调整分区表。在 Arduino 框架下可以通过Tools - Partition Scheme选择不同的分区方案或者自定义partitions.csv文件。一个典型的自定义分区表长这样# Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x5000, otadata, data, ota, 0xe000, 0x2000, app0, app, ota_0, 0x10000, 0x140000, app1, app, ota_1, 0x150000,0x140000, spiffs, data, spiffs, 0x290000,0x160000,如果你把 NVS 改大比如改成0x1000064KB那就要相应调整后面分区的偏移地址。改分区表有风险改错了设备起不来建议改之前先备份原始分区表。注意NVS 分区一旦格式化里面所有数据都会丢失。ESP32 在 NVS 分区损坏或者首次使用时会自动格式化但如果你手动调用了nvs_flash_erase()那就是彻底清空。2.4 掉电保护和写入原子性NVS 的设计本身有一定的掉电保护能力。它采用页轮转机制写入新数据时先写到新页写完了再标记旧页为无效最后擦除。这个过程如果中途掉电最坏情况是这次写入没生效但不会破坏已有数据。不过如果你在代码里连续写入多个键值对中间掉电可能导致部分写入成功、部分失败。比如先写 SSID 再写密码写到一半断电结果 SSID 是新的、密码是旧的设备就连不上了。解决办法是要么把相关配置打包成一个 blob 一次性写入要么在写入完成后做一个校验标记。// 打包写入示例 struct WifiConfig { char ssid[32]; char pass[64]; uint32_t crc; }; void saveWifiConfigAtomic(const char* ssid, const char* pass) { WifiConfig cfg; strncpy(cfg.ssid, ssid, sizeof(cfg.ssid)); strncpy(cfg.pass, pass, sizeof(cfg.pass)); cfg.crc calculateCRC(cfg, sizeof(cfg) - sizeof(cfg.crc)); prefs.begin(wifi, false); prefs.putBytes(config, cfg, sizeof(cfg)); prefs.end(); }读取的时候先校验 CRC不匹配就说明数据损坏回退到默认配置。这套机制在工业现场特别有用因为现场断电是家常便饭。3. 在 ESP32 上搭一个能改 NVS 的 Web 服务器3.1 Web 服务器的选型ESPAsyncWebServer 还是同步方案ESP32 上跑 Web 服务器有两个主流选择同步的WebServer库Arduino 自带和异步的ESPAsyncWebServer。同步方案代码简单但每个请求都会阻塞主循环如果同时有多个请求或者请求处理时间较长设备会显得很卡。异步方案基于事件回调不阻塞能同时处理多个连接适合这种配置页面场景。我实测下来ESPAsyncWebServer在响应速度和并发处理上明显优于同步方案。特别是当你需要在处理请求的同时维持 WiFi 连接、跑其他任务时异步方案几乎是必选。安装方式也简单Arduino IDE 的库管理器里搜ESPAsyncWebServer和AsyncTCP就行。#include WiFi.h #include ESPAsyncWebServer.h #include Preferences.h AsyncWebServer server(80); Preferences prefs;这里有个版本兼容性问题ESPAsyncWebServer对 ESP32 核心库的版本比较敏感。如果你用的是较新的 ESP32 Arduino Core3.x可能需要用特定分支的库。我踩过的坑是核心库 3.0.0 配老版本 AsyncWebServer 编译报错换成 GitHub 上最新的 master 分支就好了。3.2 配网模式与常连模式的切换逻辑设备启动时应该先尝试用 NVS 里存的凭据连 WiFi。如果连不上比如密码改了、路由器换了就自动切换到 AP 模式自己做一个热点让用户连上来配置。这个逻辑用状态机实现最清晰enum WifiState { CONNECTING, CONNECTED, AP_MODE }; WifiState currentState CONNECTING; void setupWifi() { String ssid loadSsid(); String pass loadPass(); if (ssid.length() 0) { enterApMode(); return; } WiFi.begin(ssid.c_str(), pass.c_str()); unsigned long start millis(); while (WiFi.status() ! WL_CONNECTED millis() - start 15000) { delay(500); } if (WiFi.status() WL_CONNECTED) { currentState CONNECTED; Serial.println(WiFi.localIP()); } else { enterApMode(); } } void enterApMode() { WiFi.mode(WIFI_AP); WiFi.softAP(ESP32-Config, 12345678); currentState AP_MODE; Serial.println(WiFi.softAPIP()); }AP 模式的默认密码建议设一个简单的比如12345678方便用户第一次连接。但要注意这个密码也应该允许用户修改否则就成了固定后门。可以在 Web 页面里加一个修改 AP 密码的选项存到 NVS 的另一个键里。3.3 路由设计读取、写入、重启三个核心接口Web 服务器只需要三个核心路由一个返回当前配置的 HTML 页面一个接收 POST 请求写入新配置一个触发重启。页面用简单的 HTML 表单就行不需要前端框架减少 Flash 占用。const char index_html[] PROGMEM Rrawliteral( !DOCTYPE html html head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleESP32 配置/title style body { font-family: Arial; max-width: 400px; margin: 40px auto; padding: 20px; } input { width: 100%; padding: 10px; margin: 8px 0; box-sizing: border-box; } button { width: 100%; padding: 12px; background: #007bff; color: white; border: none; } /style /head body h2WiFi 配置/h2 form action/save methodPOST labelSSID/label input typetext namessid value%SSID% maxlength32 label密码/label input typetext namepass value%PASS% maxlength64 button typesubmit保存并重启/button /form /body /html )rawliteral;注意%SSID%和%PASS%是占位符需要在请求处理时替换成实际值。ESPAsyncWebServer提供了processor机制来做模板替换String processor(const String var) { if (var SSID) return loadSsid(); if (var PASS) return loadPass(); return String(); } server.on(/, HTTP_GET, [](AsyncWebServerRequest *request) { request-send_P(200, text/html, index_html, processor); });写入接口用 POST 处理从请求体里解析表单数据server.on(/save, HTTP_POST, [](AsyncWebServerRequest *request) { if (request-hasParam(ssid, true) request-hasParam(pass, true)) { String ssid request-getParam(ssid, true)-value(); String pass request-getParam(pass, true)-value(); saveWifiConfig(ssid.c_str(), pass.c_str()); request-send(200, text/plain, 保存成功设备将在 3 秒后重启); delay(3000); ESP.restart(); } else { request-send(400, text/plain, 参数缺失); } });这里有个细节hasParam的第二个参数true表示从 POST body 里取false表示从 URL query 里取。表单提交默认是application/x-www-form-urlencoded所以要用true。3.4 页面模板的轻量化处理ESP32 的 Flash 和 RAM 都有限页面不能太臃肿。我见过有人往 ESP32 里塞 Bootstrap 和 jQuery结果编译出来固件快 2MB运行起来还卡。其实配置页面只需要最基本的 HTML 和 CSS几十行就够了。把 HTML 用PROGMEM存到 Flash 里不占 RAM。如果需要更复杂的交互比如实时显示 WiFi 扫描结果可以用一小段原生 JavaScript 发 AJAX 请求但不要引入任何框架。ESP32 的 Web 服务器处理能力有限前端越简单越稳。4. 键值编辑页面的交互细节与安全考量4.1 表单字段的校验与边界处理用户输入是不可信的。SSID 最长 32 字节密码最长 64 字节WPA2 标准这些边界必须在服务端校验。如果用户输入超长字符串直接写入 NVS 可能导致截断或者写入失败。bool validateInput(const String ssid, const String pass) { if (ssid.length() 0 || ssid.length() 32) return false; if (pass.length() 0 pass.length() 8) return false; // WPA2 最少 8 位 if (pass.length() 64) return false; return true; }另外SSID 里可能包含特殊字符比如中文、空格、引号。这些在 HTML 表单里需要正确转义否则页面会乱掉。ESPAsyncWebServer的send_P不会自动转义需要自己处理。简单做法是在processor里对返回值做 HTML 实体编码String htmlEscape(const String input) { String output input; output.replace(, amp;); output.replace(, lt;); output.replace(, gt;); output.replace(\, quot;); return output; }4.2 配置页面的访问控制AP 模式下任何连上热点的人都能访问配置页面。如果设备部署在公共场所这就是个安全隐患。至少应该加一个简单的 HTTP Basic Authserver.on(/, HTTP_GET, [](AsyncWebServerRequest *request) { if (!request-authenticate(admin, esp32config)) { return request-requestAuthentication(); } request-send_P(200, text/html, index_html, processor); });用户名和密码也可以存在 NVS 里允许用户修改。但要注意HTTP Basic Auth 是明文传输的在局域网里问题不大但如果设备暴露在公网不建议这么做就必须上 HTTPS。ESP32 跑 HTTPS 会消耗大量 RAM一般项目没必要。4.3 写入后的状态反馈与重启策略用户点击保存后设备需要重启才能用新配置连 WiFi。但直接重启会让浏览器显示连接中断用户体验不好。我的做法是先返回一个保存成功即将重启的页面延迟 3 秒再重启。这样浏览器能正常收到响应用户也能看到提示。request-send(200, text/html, h3保存成功/h3p设备将在 3 秒后重启请重新连接 WiFi。/p scriptsetTimeout((){location.href/;}, 5000);/script);重启后如果新配置正确设备会连上新的 WiFiAP 模式关闭。如果配置错误设备会再次进入 AP 模式用户可以重新配置。这个失败回退机制很重要否则配错了就只能拆机。4.4 多用户并发写入的冲突避免虽然配置页面通常只有一个人用但万一两个人同时打开页面提交就可能出现写入冲突。NVS 本身没有锁机制两个任务同时写同一个键可能出问题。简单的解决办法是加一个软件标志位volatile bool isSaving false; server.on(/save, HTTP_POST, [](AsyncWebServerRequest *request) { if (isSaving) { request-send(429, text/plain, 正在保存请稍后重试); return; } isSaving true; // ... 保存逻辑 ... isSaving false; });更严谨的做法是用 FreeRTOS 的互斥锁mutex但对于这种低频操作一个布尔标志就够了。5. 实际部署中遇到的坑与排查过程5.1 连不上 WiFi 但 AP 模式也进不去有一次我把设备装到现场上电后既连不上原来的 WiFi也搜不到 AP 热点。排查了半天发现是 NVS 里的 SSID 存了一个空字符串但代码逻辑判断ssid.length() 0才进 AP 模式而空字符串的长度确实是 0应该进 AP 才对。后来发现是loadSsid()返回了乱码因为 NVS 分区被意外格式化了读取时返回了默认值但默认值我设的是按理说没问题。最终定位到是Preferences库的begin()调用失败返回了false但我没检查返回值后续的getString就返回了未定义内容。修复方法很简单检查begin()的返回值失败就进 AP 模式。bool loadWifiConfig(String ssid, String pass) { if (!prefs.begin(wifi, true)) { return false; } ssid prefs.getString(ssid, ); pass prefs.getString(pass, ); prefs.end(); return ssid.length() 0; }这个坑的教训是所有 NVS 操作都要检查返回值不能假设一定成功。5.2 保存后重启新密码不生效另一个常见问题是用户保存了新密码设备重启后还是连不上。排查发现是保存的时候写入了 NVS但重启后读取的还是旧值。原因是Preferences的putString之后没有调用end()数据还在缓存里没刷到 Flash。Preferences库在end()时才会真正提交写入如果中间断电或者直接重启数据就丢了。修复方法每次写入后必须调用end()或者用prefs.putString后跟一个prefs.end()。另外写入完成后最好加一个短暂的延迟比如 100ms确保 Flash 操作完成。5.3 页面加载慢或者样式丢失有用户反馈配置页面打开要好几秒而且 CSS 不生效。排查发现是 HTML 页面太大而且每次请求都从 Flash 读取并拼接字符串效率低。优化方法是把静态部分用PROGMEM存储动态部分只替换占位符。另外CSS 直接内联在 HTML 里不要单独请求.css文件减少 HTTP 请求次数。还有一个细节ESPAsyncWebServer默认的 TCP 发送缓冲区较小如果页面超过 2KB可能会分多次发送导致浏览器渲染慢。可以在AsyncWebServer初始化时调整缓冲区大小或者把页面压缩到 2KB 以内。5.4 AP 模式下手机连不上或者频繁掉线ESP32 的 AP 模式默认最多支持 4 个客户端而且如果信道拥挤连接会不稳定。我遇到过手机连上 AP 后几秒就断开的情况排查发现是 AP 的信道和周围路由器冲突。解决办法是在softAP时指定一个相对空闲的信道WiFi.softAP(ESP32-Config, 12345678, 6); // 指定信道 6另外AP 模式下如果同时尝试连接路由器STA 模式会互相干扰。建议在 AP 模式下关闭 STA 接口只保留 AP。6. 从能用到好用几个提升体验的扩展思路6.1 扫描周围 WiFi 并下拉选择让用户手动输入 SSID 容易出错尤其是那些隐藏了 SSID 或者名字很长的网络。可以在配置页面加一个扫描按钮点击后 ESP32 扫描周围 WiFi把结果返回给前端用下拉框展示。server.on(/scan, HTTP_GET, [](AsyncWebServerRequest *request) { int n WiFi.scanNetworks(); String json [; for (int i 0; i n; i) { if (i 0) json ,; json {\ssid\:\ WiFi.SSID(i) \,\rssi\: String(WiFi.RSSI(i)) }; } json ]; request-send(200, application/json, json); });前端用一小段 JavaScript 发请求并填充下拉框。注意扫描操作会阻塞几秒钟期间 WiFi 连接会中断所以最好在 AP 模式下做这个操作。6.2 配置导入导出与批量部署如果你有多个设备要部署一个个配置太麻烦。可以加一个导出功能把当前 NVS 里的配置以 JSON 格式下载下来然后在其他设备上导入。实现方式就是加两个路由/export返回 JSON/import接收 JSON 并写入 NVS。这个功能在批量生产或者现场调试时特别有用。我做过一个项目20 台设备用导出导入功能5 分钟全部配好比一台台手动输入快多了。6.3 OTA 升级与配置保留的配合设备支持 OTA 升级后固件更新不会影响 NVS 里的配置这是 NVS 的一大优势。但要注意如果新固件改了 NVS 的键名或者数据结构旧配置可能读不出来。解决办法是在固件里加一个版本号启动时检查 NVS 里的配置版本不匹配就迁移或者重置。#define CONFIG_VERSION 2 void checkConfigVersion() { prefs.begin(wifi, false); uint32_t ver prefs.getUInt(cfg_ver, 0); if (ver ! CONFIG_VERSION) { // 执行迁移逻辑 prefs.putUInt(cfg_ver, CONFIG_VERSION); } prefs.end(); }6.4 把配置页面做成可复用的组件如果你经常做 ESP32 项目建议把这套 Web 配置功能封装成一个独立的库或者头文件下次直接引用。核心接口就三个beginConfigPortal()启动服务器loadConfig()读取配置saveConfig()保存配置。这样不同项目之间可以复用不用每次都重写。我在实际使用中发现把这套东西封装好之后新项目的配置功能开发时间从半天缩短到十分钟。而且因为经过了多个项目的验证稳定性也有保障。最后分享一个小技巧在 NVS 里存一个config_dirty标志位每次保存配置时置位设备成功连上 WiFi 后清零。如果启动时发现这个标志是置位的说明上次配置后没连上可以自动进入 AP 模式让用户重新配置。这个机制能避免设备变砖在现场部署时特别有用。
