1. 从一个让人抓狂的场景说起
如果你玩过 ESP32，大概率经历过这个场景：设备已经焊好、装进壳子、挂在墙上，跑了大半年，突然要换 WiFi 密码。你翻出数据线，拆壳，找串口，打开 Arduino IDE 或者 ESP-IDF，改两行代码，重新编译，重新烧录，运气不好还得按住 BOOT 键进下载模式。整个过程十分钟起步，如果设备装在难拆的位置，半小时都搞不定。
问题的根源在于：很多人把 WiFi 的 SSID 和密码直接写死在代码里，编译进固件。固件是只读的，改一个字符就得整体重刷。而 ESP32 其实自带一块叫NVS（Non-Volatile Storage，非易失性存储）的区域，专门用来存这种"运行时可变的配置数据"。把 WiFi 凭据放进 NVS，固件只负责读，改密码就变成了改一个键值对，根本不用碰固件。
更进一步，如果 ESP32 上跑了一个内嵌的 Web 服务，浏览器打开一个页面就能改 NVS 里的键值，那连数据线都不需要了。手机连上设备的热点，或者设备已经在局域网里，打开浏览器输入 IP，填个表单提交，重启，新密码生效。这就是标题里说的"浏览器工具直接改 NVS 键值"。
这篇内容适合三类人：一是刚接触 ESP32、还在把配置写死在代码里的新手；二是做过几个项目、想给设备加"免拆机配置"能力的进阶玩家；三是做小批量产品、需要给客户留一个配置入口的开发者。我会把 NVS 的原理、Web 服务的搭建、键值读写的完整代码、以及实际踩过的坑都讲清楚，代码可以直接抄。
2. 为什么是 NVS，而不是其他方案
2.1 配置存储的几种常见做法对比
在决定用 NVS 之前，我试过几种存配置的方式，各有各的问题。先摆一张表，把常见方案拉出来对比。
| 方案 | 掉电保存 | 运行时修改 | 擦写寿命 | 适用场景 |
|---|---|---|---|---|
| 代码硬编码 | 是 | 否 | 不涉及 | 一次性烧录、永不改配置 |
| EEPROM 模拟 | 是 | 是 | 约 10 万次 | 少量字节配置 |
| SPIFFS/LittleFS 文件 | 是 | 是 | 约 10 万次 | 大块数据、JSON 配置 |
| NVS | 是 | 是 | 约 10 万次 | 键值对配置、WiFi 凭据 |
| SD 卡 | 是 | 是 | 极高 | 大数据、可插拔 |
硬编码的问题不用多说，改一次刷一次。EEPROM 在 ESP32 上其实是 Flash 模拟出来的，用起来要自己算地址偏移，键多了容易冲突。文件系统适合存大块 JSON，但读写一个键要把整个文件读出来解析再写回去，小配置用它是杀鸡用牛刀，而且文件系统本身占用的 Flash 空间比 NVS 大。
NVS 的设计目标就是"键值对存储"，天生适合存 WiFi SSID、密码、设备名、阈值参数这类零散配置。它内部做了磨损均衡，你不用关心写哪个扇区。API 也简单，nvs_set_str、nvs_get_str几个函数就搞定。
2.2 NVS 的底层结构，理解了这个才不慌
NVS 在 Flash 上占用一个独立分区，默认大小 0x5000（20KB），在分区表里通常长这样：
# Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x5000,这 20KB 被划分成多个 4KB 的扇区（page）。每个扇区里存若干条"条目（entry）"，每条 32 字节。一个键值对可能占用一条或多条 entry，取决于值的长度。字符串短的话一条就够，长字符串会跨多条。
关键点在于：NVS 写入不是原地覆盖，而是写到新位置，然后把旧条目标记为已删除。这就是磨损均衡的实现方式。所以频繁写同一个键，会加速扇区消耗。这也是为什么我不建议把 NVS 当日志用，一秒写一次，几周就能写坏一个扇区。
注意：NVS 的键名最长 15 个字符（不含结束符），超过会被截断。命名空间（namespace）名字最长 15 个字符。这个限制很多人第一次用会踩，键名写太长，读的时候读不到，排查半天。
2.3 为什么选 Web 服务作为配置入口
配置入口有好几种：串口命令行、蓝牙、按键组合、Web 页面。串口要接线，蓝牙要装 App，按键组合能配的东西太少。Web 页面的优势是零安装——任何有浏览器的设备都能用，手机、电脑、平板都行，界面还能做得直观。
ESP32 跑 Web 服务完全没压力。用WebServer库（Arduino 环境）或者esp_http_server（IDF 环境），几十行代码就能起一个 HTTP 服务。配置页面就是一个简单的 HTML 表单，提交后 POST 到某个路径，后端解析参数写进 NVS。
这里有个设计取舍：配置页面是放在 Flash 里（PROGMEM）还是动态生成。放 Flash 里省内存，但改页面要重刷固件，又回到老问题。动态生成灵活，但代码里拼 HTML 字符串比较丑。我的做法是页面结构固定、用PROGMEM存模板，只有少量动态内容（比如当前 SSID）用代码填充。这样既省内存，又不用为了改个样式重刷。
3. 核心实现：从 NVS 读写到 Web 配置页
3.1 环境准备与依赖说明
我用的是 Arduino 环境，因为上手快，库生态成熟。ESP-IDF 也能做，原理一样，API 换成nvs_open、nvs_set_str那套。Arduino 环境下，NVS 的封装在Preferences库里，比裸调 IDF 的 NVS API 舒服很多。
需要的库：
Preferences.h：Arduino ESP32 核心自带，不用额外装WiFi.h：自带WebServer.h：自带
如果你用的是 PlatformIO，platformio.ini里指定 ESP32 平台即可，这些库都在核心包里。Arduino IDE 的话，确保 ESP32 开发板包版本在 2.0 以上，Preferences库的 API 在 2.0 之后稳定了。
提示：
Preferences库本质是对 IDF NVS API 的 C++ 封装，底层还是 NVS。所以前面讲的键名长度限制、磨损均衡特性，在这里同样适用。
3.2 NVS 读写的最小可用代码
先看最核心的部分——怎么把 WiFi 凭据存进去、读出来。下面这段是能直接跑的最小示例：
#include <Preferences.h> Preferences prefs; void saveWifiConfig(const String& ssid, const String& password) { prefs.begin("wifi", false); // 打开命名空间 "wifi"，false 表示读写模式 prefs.putString("ssid", ssid); // 写入 SSID prefs.putString("pass", password); // 写入密码 prefs.end(); // 关闭，释放句柄 } bool loadWifiConfig(String& ssid, String& password) { prefs.begin("wifi", true); // true 表示只读模式 ssid = prefs.getString("ssid", ""); // 第二个参数是默认值 password = prefs.getString("pass", ""); prefs.end(); return ssid.length() > 0; // SSID 为空说明没配置过 }几个细节值得说清楚。prefs.begin的第一个参数是命名空间，你可以理解成 NVS 里的一个"文件夹"，不同项目的配置放不同命名空间，互不干扰。第二个参数readOnly，读的时候传true，写的时候传false。这个参数很多人忽略，但它影响底层打开 NVS 的方式，只读模式不会触发擦写，更安全。
getString的第二个参数是默认值。当键不存在时返回这个默认值。这个设计很关键——第一次开机时 NVS 是空的，getString返回空字符串，你的代码就能判断"还没配置过"，然后进入配网模式。
注意：
prefs.begin之后一定要prefs.end。虽然 ESP32 的 NVS 句柄数量有限（默认最多同时打开几个），但更重要的是，写完不 end，数据可能还在缓存里没落盘。我遇到过写完立刻断电、重启后配置丢失的情况，就是没 end 导致的。
3.3 把配置页面跑起来：Web 服务完整实现
有了 NVS 读写，接下来搭 Web 服务。整体流程是：设备启动 → 读 NVS → 有配置就连接 WiFi → 起 Web 服务 → 浏览器访问配置页 → 提交表单 → 写 NVS → 重启生效。
先看 HTML 页面。我用PROGMEM存一个模板，里面用占位符标记要动态填充的地方：
const char CONFIG_PAGE[] PROGMEM = R"rawliteral( <!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>设备配置</title> <style> body{font-family:sans-serif;max-width:400px;margin:40px auto;padding:0 20px;} input{width:100%;padding:10px;margin:8px 0;box-sizing:border-box;} button{width:100%;padding:12px;background:#2c7;color:#fff;border:none;font-size:16px;} </style> </head> <body> <h2>WiFi 配置</h2> <form action="/save" method="POST"> <label>SSID</label> <input name="ssid" value="%SSID%" maxlength="32"> <label>密码</label> <input name="pass" type="password" value="%PASS%" maxlength="64"> <button type="submit">保存并重启</button> </form> </body> </html> )rawliteral";这个页面很朴素，但够用。%SSID%和%PASS%是占位符，服务端处理请求时替换成 NVS 里的当前值，这样用户打开页面能看到已配置的内容，改起来方便。
然后是服务端的路由处理：
#include <WebServer.h> WebServer server(80); String renderPage() { String ssid, pass; loadWifiConfig(ssid, pass); String page = FPSTR(CONFIG_PAGE); page.replace("%SSID%", ssid); page.replace("%PASS%", pass); return page; } void handleRoot() { server.send(200, "text/html", renderPage()); } void handleSave() { if (server.hasArg("ssid") && server.hasArg("pass")) { String ssid = server.arg("ssid"); String pass = server.arg("pass"); saveWifiConfig(ssid, pass); server.send(200, "text/html", "<meta charset='UTF-8'><h3>已保存，设备重启中...</h3>"); delay(1000); ESP.restart(); // 重启让新配置生效 } else { server.send(400, "text/plain", "missing params"); } } void setupWebServer() { server.on("/", handleRoot); server.on("/save", HTTP_POST, handleSave); server.begin(); }FPSTR宏把PROGMEM里的字符串读到 RAM，然后replace替换占位符。这里有个性能考量：每次请求都读一次 NVS 再拼页面，对配置页这种低频访问完全够用，不用做缓存。
handleSave里保存完先返回一个提示页面，delay(1000)给浏览器一点时间渲染，然后ESP.restart()。为什么要重启？因为 WiFi 连接是在setup里建立的，运行中改 SSID 需要重新走一遍连接流程。重启是最简单可靠的做法，虽然粗暴但有效。
3.4 主流程串起来：启动逻辑与配网兜底
把上面的片段拼成完整的setup：
void setup() { Serial.begin(115200); String ssid, pass; bool configured = loadWifiConfig(ssid, pass); if (configured) { WiFi.mode(WIFI_STA); WiFi.begin(ssid.c_str(), pass.c_str()); unsigned long start = millis(); while (WiFi.status() != WL_CONNECTED && millis() - start < 15000) { delay(500); Serial.print("."); } } if (WiFi.status() == WL_CONNECTED) { Serial.println("\nConnected: " + WiFi.localIP().toString()); } else { // 连不上就开热点，让用户来配 WiFi.mode(WIFI_AP); WiFi.softAP("ESP32-Config", "12345678"); Serial.println("AP mode: " + WiFi.softAPIP().toString()); } setupWebServer(); } void loop() { server.handleClient(); }这段逻辑的关键是兜底。如果 NVS 里没配置，或者配置的 WiFi 连不上（比如密码改了、路由器换了），设备自动切到 AP 模式，自己发一个热点。用户连上这个热点，浏览器打开192.168.4.1，就能重新配置。这样设备永远不会"失联"——最坏情况你还能连它的热点进去改。
提示：AP 模式的默认密码
12345678建议改掉，或者做成开放热点但加个配置页面的简单校验。开放热点方便，但同环境下任何人都能连进来改你的配置，看你的使用场景取舍。
4. 实操中踩过的坑与排查技巧
4.1 NVS 相关的典型问题
问题一：写完配置重启后读不到。最常见的原因是prefs.end()没调用，数据没落盘。另一个原因是命名空间写错了——begin("wifi")和begin("WiFi")是两个不同的命名空间，大小写敏感。我见过有人读的时候用大写、写的时候用小写，排查了一下午。
问题二：键名超长被截断。NVS 键名上限 15 字符。"wifi_password"是 13 字符没问题，"wifi_password_config"就超了，会被截断成前 15 个字符。写进去和读出来用的是同一个截断后的名字，所以能对上，但如果你在代码里用完整名字去比对，就会困惑。养成习惯：键名短一点，ssid、pass、dev_name这种。
问题三：NVS 分区满了。默认 20KB，存几十个键值对没问题，但如果你存了很长的字符串（比如证书、大段 JSON），可能写满。写满后putString会返回 0（失败），但很多人不检查返回值。建议关键写入检查一下返回值：
size_t written = prefs.putString("ssid", ssid); if (written == 0) { Serial.println("NVS write failed!"); }4.2 Web 服务相关的坑
坑一：表单提交后页面卡住。因为handleSave里delay(1000)然后重启，浏览器在等服务端关闭连接。如果重启太快，浏览器可能报"连接被重置"。我的做法是先server.send把响应发完，再delay，再重启。顺序反了就会出现页面加载不出来的情况。
坑二：中文乱码。HTML 里必须声明<meta charset="UTF-8">，服务端send时 Content-Type 也要带 charset：server.send(200, "text/html; charset=utf-8", page)。少一个都可能乱码。SSID 里如果有中文，还要注意 URL 编码的问题，server.arg会自动解码，一般不用管。
坑三：AP 模式下手机连不上。有些手机在 AP 模式下会提示"无互联网连接"，然后自动切回移动数据，导致打不开配置页。解决办法是在手机上手动选择"保持连接"，或者关掉移动数据。这是手机系统的行为，不是 ESP32 的问题，但用户不知道就会以为设备坏了。可以在配置页面上加一句提示。
4.3 常见问题速查表
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 配置保存后丢失 | 没调 end / 写后立即断电 | 检查 end 调用，写后延时再断电 |
| 读不到刚写的键 | 命名空间或键名大小写不一致 | 统一命名，打印出来比对 |
| 写入返回 0 | NVS 分区满 | 清理无用键，或扩大分区 |
| 配置页打不开 | AP 模式手机切回移动数据 | 手动保持连接，关移动数据 |
| 页面中文乱码 | 缺 charset 声明 | HTML 和响应头都加 UTF-8 |
| 提交后无响应 | 重启早于响应发送 | 先 send 再 delay 再 restart |
| 连不上新 WiFi | 密码含特殊字符 | 检查转义，避免引号等 |
4.4 几个提升体验的小技巧
技巧一：配置页加一个"扫描周边 WiFi"按钮。用WiFi.scanNetworks()扫一圈，把 SSID 列成下拉框，用户点选就行，不用手打。这个功能在 AP 模式下也能用，体验提升很大。实现上就是加一个/scan接口返回 JSON，前端用 JS 填充下拉框。
技巧二：保存前做一次连接测试。不要直接写 NVS 然后重启，而是先用新凭据尝试连接，连上了再写、再重启。连不上就返回错误提示，让用户重新填。这样避免了"填错密码→重启→连不上→再进 AP 模式→再填"的循环。代价是保存时多等几秒，但值得。
技巧三：给配置页加个简单的访问密码。如果设备在公共网络里，任何人都能访问配置页改你的 WiFi。加一个 HTTP Basic Auth，或者页面上加个密码输入框，校验通过才允许保存。简单但有效。
技巧四：OTA 和 NVS 配置配合。既然配置在 NVS 里，固件升级（OTA）时配置不会丢。这意味着你可以放心地远程升级固件，WiFi 凭据、设备参数都保留。这是 NVS 方案相比硬编码的一个隐藏优势——升级和配置解耦了。
5. 这套方案还能怎么扩展
把 WiFi 配置放进 NVS、用 Web 页面管理，这个模式可以推广到很多其他配置项。比如设备的 MQTT 服务器地址、上报间隔、传感器校准系数、设备别名，全都可以做成 NVS 键值，在同一个配置页面上分组展示。页面稍微改改，加几个输入框，后端多几个putString/putInt就行。
再进一步，可以做一个通用的"配置项注册表"：代码里定义一个结构体数组，描述每个配置项的键名、类型、默认值、显示名称，配置页面根据这个表自动生成表单。这样加新配置项不用改页面代码，只改注册表。这个思路在做过几个项目之后会特别省事。
我在实际使用中发现，最容易被忽略的是配置的版本管理。当固件升级、配置项结构变了（比如某个键改名了、类型从字符串变成整数），旧 NVS 里的数据可能读不出来或者读错。稳妥的做法是在 NVS 里存一个config_ver键，启动时检查版本，不匹配就迁移或重置。这个坑我在第二个项目才意识到，第一个项目升级固件后配置全乱，排查了很久。
最后分享一个小技巧：调试 NVS 的时候，可以写一个/dump接口，把当前命名空间下所有键值以 JSON 形式打印出来。Preferences库没有直接列所有键的 API，但你可以维护一个键名列表，遍历读取。这个接口在排查"到底存进去没有"的时候特别好用，比反复重启看串口快得多。
