★ FEATURED ARTICLE 1. 从改个密码要重刷固件说起ESP32 参数管理的真实痛点搞过 ESP32 量产或者小批量部署的朋友大概率都遇到过这个场景设备已经装到现场了客户突然说 WiFi 换了或者要改个 MQTT 服务器地址、改个设备编号。这时候你怎么办最原始的做法是改代码里的宏定义重新编译然后抱着笔记本和 USB 线跑到现场去刷固件。如果设备装在吊顶里、配电箱里、或者干脆在另一个城市这个成本就非常离谱了。我最早做 ESP32 项目的时候就是这么干的一个环境监测的小盒子部署了二十几台结果客户那边路由器换了一次我整整跑了两天。后来才认真去研究 NVSNon-Volatile Storage这套东西才发现 ESP32 本身就提供了非常成熟的键值对持久化存储机制问题根本不在芯片而在于我们没有一个趁手的工具去读写它。这篇要聊的就是这么一件事不重刷固件直接通过浏览器修改 ESP32 的 NVS 键值。核心思路是把设备变成一个带 Web 界面的配置终端浏览器打开就能看到当前存了哪些键、值是什么、直接改完保存重启生效。关键词里的 ESP32、WiFi、NVS、固件、浏览器工具其实指向的就是这一整套运行时配置的方案。适合谁看如果你正在做 ESP32 的联网设备、需要现场调试、需要给非技术用户提供配置入口或者你单纯想搞清楚 NVS 到底怎么用、Web 服务器怎么和 NVS 打通这篇内容都能直接拿去用。我会把原理、代码结构、踩过的坑、以及几个容易被忽略的细节都讲清楚尽量做到你照着做就能跑起来。先说结论这套方案的本质是用 ESP32 自带的 WebServer 库或者 ESP-IDF 的 httpd搭一个轻量 HTTP 服务前端页面负责展示和编辑后端接口负责读写 NVS。整个固件只需要刷一次之后所有参数变更都在浏览器里完成。听起来简单但里面有几个关键决策点比如 NVS 命名空间怎么规划、值类型怎么处理、密码这种敏感字段怎么回显、改完要不要立即重启这些才是真正决定这套东西好不好用的地方。2. NVS 到底存了什么键值存储的机制与边界2.1 NVS 不是文件系统别拿它当 SPIFFS 用很多人第一次接触 NVS会下意识把它和 SPIFFS、LittleFS 这类文件系统混为一谈。其实它们完全不是一回事。NVS 是 ESP32 在 flash 上划出的一块专门区域用键值对key-value的方式存储数据底层是一套带磨损均衡的日志结构。它不管理目录不支持文件你只能通过nvs_set_xxx和nvs_get_xxx这一套 API 去读写。这个区别很关键。文件系统适合存网页、图片、日志这种大块、非结构化的数据NVS 适合存配置项、校准参数、设备状态这种小、零散、需要频繁读写的键值。你把 WiFi 密码、服务器地址、设备 ID 放 NVS是正解你想往 NVS 里塞一个 100KB 的 HTML 文件那就是用错工具了。NVS 的默认分区大小在常见的 Arduino ESP32 分区表里大概是 20KB 左右nvs分区0x9000 起始0x5000 大小。这个容量听起来很小但存配置项绰绰有余。一个键值对的开销大概是几十字节你存几十上百个配置项完全没问题。但如果你要存大量数据就得考虑调整分区表把 nvs 分区调大。2.2 命名空间为什么你的键会消失NVS 有一个很容易踩的坑命名空间namespace。所有的键都必须属于某个命名空间读写时必须指定同一个命名空间否则你写进去的键在另一个命名空间里是读不到的。我见过有人写代码时读用storage写用config然后调试半天说NVS 存不进去。其实数据一直在只是你找错抽屉了。命名空间的名字最长 15 个字符键名最长 15 个字符这个限制也要注意超了会被截断或者直接失败。常见的做法是按功能划分命名空间比如命名空间用途典型键wifi网络配置ssid, password, modemqtt服务器配置host, port, user, passdevice设备信息id, name, locationcalib校准参数offset, scale这样划分的好处是Web 界面可以按命名空间分组展示用户看起来清晰代码里也好管理。缺点是命名空间多了之后遍历所有配置会稍微麻烦一点需要逐个命名空间去打开。2.3 值类型字符串、整数、二进制各有各的坑NVS 支持的类型主要有几种i8/u8/i16/u16/i32/u32/i64/u64、字符串、blob二进制大对象。在 Arduino 环境下最常用的是字符串和整数。这里有个细节NVS 的字符串是带长度信息的不是以\0结尾的 C 字符串。你用nvs_get_str读的时候必须先用nvs_get_str(handle, key, NULL, len)拿到长度再分配缓冲区去读。很多人直接传一个固定大小的 buffer 进去长度参数没设对结果读出来是乱码或者直接报错。整数类型也有讲究。你存的时候用nvs_set_i32读的时候就必须用nvs_get_i32类型不匹配会返回ESP_ERR_NVS_TYPE_MISMATCH。这个错误在调试时经常出现尤其是当你不确定某个键之前是用什么类型写进去的时候。我的建议是在 Web 工具里给每个键标注类型前端提交时按类型转换后端按类型写入避免混乱。还有一个容易被忽略的点NVS 的键是区分大小写的。SSID和ssid是两个不同的键。这个在跨平台协作时特别容易出问题建议团队里统一约定全小写或者驼峰别混着来。3. 浏览器改 NVS 的整体架构一次刷写终身可配3.1 为什么选 Web 而不是蓝牙或串口能改 NVS 的通道其实有好几种串口命令行、蓝牙 BLE、Web 服务器、甚至物理按键组合。为什么我最终推荐 Web串口最直接但需要物理接触现场部署后基本不可用。蓝牙 BLE 不需要网络但需要装 App而且 BLE 的配对、连接、MTU 协商一堆坑用户体验不稳定。物理按键只能做有限的几种操作改密码这种输入型任务根本做不了。Web 的优势在于只要有网络任何带浏览器的设备都能访问。手机、平板、电脑都行不需要装任何东西。而且前端可以做得很友好表单、下拉框、密码框、校验提示这些用 HTML 天然就支持。对于现场调试和非技术用户配置来说这是成本最低、门槛最低的方案。当然Web 方案有个前提设备得先连上网络。如果 WiFi 密码错了导致设备连不上那 Web 也访问不了这就成了死锁。所以实际项目里通常还会保留一个 AP 模式设备自己开热点作为兜底或者保留串口作为最后手段。这个后面会细说。3.2 固件里到底要放什么整个固件可以拆成三块NVS 读写层、HTTP 服务层、前端页面。NVS 读写层负责封装nvs_open、nvs_get_xxx、nvs_set_xxx、nvs_commit这些调用对外提供类似readConfig(namespace, key)和writeConfig(namespace, key, value)的接口。这一层要处理好类型转换和错误码。HTTP 服务层用WebServer库Arduino或者esp_http_serverESP-IDF搭建暴露几个接口一个返回当前所有配置的 JSON一个接收修改请求可能还有一个重启接口。接口设计要简单GET /api/config拿配置POST /api/config提交修改POST /api/reboot重启。前端页面可以直接编译进固件用 PROGMEM 存 HTML 字符串也可以放 SPIFFS 里。如果页面简单直接内嵌最省事不用管文件系统。页面用原生 JS 写就行fetch 调接口不需要框架ESP32 的资源也跑不动重前端。3.3 数据流从浏览器点击到 flash 落盘完整的数据流是这样的浏览器加载页面JS 发GET /api/configESP32 遍历预设的命名空间和键列表把值读出来拼成 JSON 返回。用户在页面上修改某个字段点保存JS 发POST /api/configbody 里带上命名空间、键、新值。ESP32 收到后调用nvs_set_xxx写入然后nvs_commit落盘。返回成功页面提示保存成功重启后生效。这里有个设计决策改完是立即生效还是重启生效。WiFi 密码这种改了必须重启才能重连因为 WiFi 连接是在启动时建立的。但有些参数比如 MQTT 的发布间隔其实可以在运行时重新读取。我的做法是在页面上标注每个参数是否需要重启需要重启的给个明显的提示并提供一键重启按钮。这样用户心里有数不会改完发现没反应以为坏了。4. 手把手实现从 NVS 封装到 Web 接口4.1 环境准备与依赖我用的是 Arduino IDE ESP32 开发板包版本 2.0.x 以上。如果你用 PlatformIO 也行库的引用方式略有不同。核心依赖就一个WiFi.h和WebServer.h这两个是 ESP32 Arduino 核心自带的不需要额外装。如果你用 ESP-IDF那就用nvs_flash.h和esp_http_server.h思路一样API 名字不同。下面我以 Arduino 为例因为它的门槛最低大部分人上手快。分区表用默认的就行nvs分区默认 0x500020KB够用。如果你要存的东西特别多可以在partitions.csv里把 nvs 调大比如 0x1000064KB。改分区表要注意别和其他分区重叠这个用 Arduino IDE 的话在Tools - Partition Scheme里选或者自定义 csv。4.2 NVS 封装把类型和错误码处理干净先写一个简单的封装。核心是处理字符串读取时的两段式调用以及类型匹配。#include nvs.h #include nvs_flash.h bool nvsReadString(const char* ns, const char* key, String out) { nvs_handle_t handle; esp_err_t err nvs_open(ns, NVS_READONLY, handle); if (err ! ESP_OK) return false; size_t len 0; err nvs_get_str(handle, key, NULL, len); if (err ! ESP_OK) { nvs_close(handle); return false; } char* buf (char*)malloc(len); if (!buf) { nvs_close(handle); return false; } err nvs_get_str(handle, key, buf, len); if (err ESP_OK) { out String(buf); } free(buf); nvs_close(handle); return err ESP_OK; } bool nvsWriteString(const char* ns, const char* key, const String val) { nvs_handle_t handle; esp_err_t err nvs_open(ns, NVS_READWRITE, handle); if (err ! ESP_OK) return false; err nvs_set_str(handle, key, val.c_str()); if (err ESP_OK) { err nvs_commit(handle); } nvs_close(handle); return err ESP_OK; }整数类似用nvs_get_i32/nvs_set_i32。注意nvs_commit这一步不能省虽然有些情况下不 commit 也会写但为了可靠性写完必须 commit。我遇到过不 commit 然后断电丢数据的情况虽然概率低但配置这种东西丢了很麻烦。4.3 HTTP 接口设计GET 拿配置POST 改配置接口尽量简单。我设计两个GET /api/config返回所有配置的 JSON。POST /api/config接收{ns, key, value, type}写入 NVS。返回的 JSON 结构大概这样{ wifi: { ssid: {value: MyHome, type: str, reboot: true}, password: {value: ******, type: str, reboot: true} }, mqtt: { host: {value: 192.168.1.100, type: str, reboot: false}, port: {value: 1883, type: i32, reboot: false} } }注意密码字段返回时不要回显真实值用******代替或者返回空。用户不修改就不提交修改了才提交新值。这是基本的安全习惯虽然局域网内风险不大但养成习惯没坏处。后端处理 POST 时根据type字段决定调用哪个 set 函数。字符串直接nvs_set_str整数先atoi再nvs_set_i32。写完 commit返回{ok: true}。4.4 前端页面够用就好的极简实现前端不用花哨一个表单按命名空间分组每个字段一个输入框下面一个保存按钮。用原生 JS 的fetch调接口。!DOCTYPE html html head meta charsetutf-8 meta nameviewport contentwidthdevice-width, initial-scale1 titleESP32 配置/title style body { font-family: sans-serif; margin: 20px; max-width: 600px; } .group { margin-bottom: 20px; border: 1px solid #ccc; padding: 10px; border-radius: 6px; } .group h3 { margin-top: 0; } label { display: block; margin: 8px 0 4px; font-size: 14px; } input { width: 100%; padding: 6px; box-sizing: border-box; } button { padding: 10px 20px; margin-top: 10px; } /style /head body h2ESP32 配置面板/h2 div idform/div button onclicksaveAll()保存全部/button button onclickreboot()重启设备/button script let config {}; async function load() { const r await fetch(/api/config); config await r.json(); render(); } function render() { const form document.getElementById(form); form.innerHTML ; for (const ns in config) { const div document.createElement(div); div.className group; div.innerHTML h3 ns /h3; for (const key in config[ns]) { const item config[ns][key]; const label document.createElement(label); label.textContent key (item.reboot ? (需重启) : ); const input document.createElement(input); input.value item.value; input.dataset.ns ns; input.dataset.key key; input.dataset.type item.type; div.appendChild(label); div.appendChild(input); } form.appendChild(div); } } async function saveAll() { const inputs document.querySelectorAll(input); for (const inp of inputs) { await fetch(/api/config, { method: POST, headers: {Content-Type: application/json}, body: JSON.stringify({ ns: inp.dataset.ns, key: inp.dataset.key, value: inp.value, type: inp.dataset.type }) }); } alert(保存成功); } async function reboot() { await fetch(/api/reboot, {method: POST}); alert(设备重启中); } load(); /script /body /html这个页面很朴素但功能完整。实际项目里你可以加个密码保护或者只在 AP 模式下开放配置接口避免被随便改。5. 实测中的坑那些文档不会告诉你的细节5.1 密码回显与空值覆盖陷阱前面提到密码字段不回显用******代替。但这里有个坑如果用户只改了 SSID没动密码前端把******原样提交上去后端就把密码真的改成******了。设备重启后连不上 WiFi你还得去现场救。解决办法有两个一是前端判断如果值还是******就不提交这个字段二是后端判断收到******就跳过不写。我一般两个都做双保险。更稳妥的做法是密码字段单独处理前端不显示原值只显示一个修改密码的按钮点了才出现输入框不点就不提交。5.2 写入后不 commit断电就丢前面提过nvs_commit这里再强调一次。NVS 的写入是分两步的nvs_set_xxx只是写到缓存nvs_commit才真正落盘。如果你写完不 commit然后设备因为某种原因重启比如看门狗复位、断电数据就丢了。我踩过一次这个坑改完配置页面提示成功我拔电重启结果配置还是旧的。查了半天才发现 commit 漏了。所以封装函数里set 之后必须 commit这个不能省。5.3 命名空间打开失败NVS 没初始化如果你在setup()里直接调nvs_open可能会失败返回ESP_ERR_NVS_NOT_INITIALIZED。这是因为 NVS 分区需要先初始化。Arduino 环境下WiFi.begin()之类的调用会隐式初始化 NVS但如果你在 WiFi 之前就操作 NVS就得手动调nvs_flash_init()。esp_err_t err nvs_flash_init(); if (err ESP_ERR_NVS_NO_FREE_PAGES || err ESP_ERR_NVS_NEW_VERSION_FOUND) { nvs_flash_erase(); err nvs_flash_init(); }这段代码建议放在setup()最前面确保 NVS 可用。nvs_flash_erase()会清空所有 NVS 数据只在初始化失败时用正常情况不会走到。5.4 Web 服务和 WiFi 连接的时序问题如果你把配置页面放在 STA 模式下设备连路由器你通过路由器访问它那有个时序问题WiFi 连接需要时间如果 WiFi 连不上比如密码错了Web 服务就起不来你就没法通过 Web 去改密码死锁。我的做法是启动时先尝试 STA 连接超时比如 10 秒后自动切到 AP 模式设备自己开一个热点你用手机连上去访问192.168.4.1改配置。改完重启再尝试 STA。这样就不会死锁。AP 模式的代码大概这样WiFi.mode(WIFI_AP); WiFi.softAP(ESP32-Config, 12345678);AP 的密码可以设一个默认的或者干脆不设开放热点看你的安全需求。配置页面在 AP 模式下也能访问接口一样。5.5 前端提交大量字段时的性能如果你的配置项很多比如几十个前端saveAll一个个 POST 会很慢而且容易超时。更好的做法是后端提供一个批量接口接收一个 JSON 数组一次性写入。或者前端用Promise.all并发提交但要注意 ESP32 的 HTTP 服务并发能力有限别开太多。我一般控制在 20 个字段以内超过就分批。实际项目里配置项不会太多这个问题不常见但如果你做的是复杂设备就得考虑。6. 进阶玩法让配置工具更贴近生产环境6.1 配置项元数据化用表驱动代替硬编码前面接口里返回的 JSON 带了type和reboot字段这些信息如果硬编码在代码里每加一个配置项就要改代码很麻烦。更好的做法是用一张表来驱动。struct ConfigItem { const char* ns; const char* key; const char* type; // str or i32 bool reboot; }; ConfigItem configTable[] { {wifi, ssid, str, true}, {wifi, password, str, true}, {mqtt, host, str, false}, {mqtt, port, i32, false}, // ... };遍历这张表就能生成 JSON也能校验提交的字段是否合法。加配置项只需要改表不用动逻辑。这个思路在生产环境里很实用尤其是配置项经常变的时候。6.2 配置导入导出一键备份和恢复既然能读能写那导出成 JSON 文件、导入恢复就是顺理成章的事。加一个GET /api/config/export返回完整 JSON前端做成下载再加一个POST /api/config/import接收 JSON 批量写入。这样设备换新、批量部署的时候配置一台导出其他导入效率极高。导入的时候要注意校验别把乱七八糟的 JSON 写进去。至少检查命名空间和键是否在表里类型是否匹配。不匹配的直接拒绝返回错误信息。6.3 安全考量别把配置接口裸奔在公网这套工具在局域网里用没问题但千万别把配置接口暴露到公网。ESP32 的 HTTP 服务没有 HTTPS除非你用 ESP-IDF 的 TLS但资源开销大也没有认证机制任何人访问到 IP 就能改你的配置。如果确实需要远程配置建议的做法是设备主动连到一个内网服务器通过 MQTT 或者自定义协议拉取配置而不是开一个公网可访问的 Web 端口。或者至少加一个简单的 token 校验请求头里带个密钥后端比对。虽然 token 也可能被截获但比裸奔强。AP 模式下也建议设个密码别用开放热点。默认密码可以在代码里设用户第一次配置时改掉。6.4 和 OTA 的关系配置和固件分开管理有人会问既然能 OTA 升级固件那配置是不是也可以跟着固件一起更新我的建议是分开。固件升级是代码逻辑的变更配置是运行参数的变更两者的生命周期不一样。固件可能几个月才升一次配置可能一周改几次。混在一起会导致每次改配置都要重新编译固件那就回到最初的问题了。正确的做法是固件里只放默认配置首次启动时写入 NVS之后所有变更都走 NVS。OTA 升级固件时不动 NVS 分区配置自然保留。这样固件和配置解耦各自独立演进。7. 几个实际项目中的经验补充7.1 默认配置的写入时机设备第一次启动时NVS 是空的你需要写入一套默认配置。这个逻辑要放在setup()里判断某个标志键是否存在不存在就写入默认值。bool nvsKeyExists(const char* ns, const char* key) { nvs_handle_t handle; if (nvs_open(ns, NVS_READONLY, handle) ! ESP_OK) return false; size_t len 0; esp_err_t err nvs_get_str(handle, key, NULL, len); nvs_close(handle); return err ESP_OK; }用nvsKeyExists(wifi, ssid)判断如果不存在就写入默认的 SSID 和密码。这样首次启动能连上默认网络之后用户通过 Web 改。注意别每次启动都写默认值那样用户改的配置会被覆盖。一定要先判断存在性。7.2 配置读取的缓存策略如果你的配置在运行时要频繁读取比如每次发 MQTT 消息都要读一下 host每次都nvs_opennvs_get会有性能开销。NVS 的读取虽然不慢但频繁调用也不划算。我的做法是启动时把所有配置读到一个全局结构体里运行时用结构体修改时同时更新结构体和 NVS。这样读取是内存操作极快写入才走 NVS。结构体和 NVS 保持同步逻辑清晰。7.3 调试技巧串口打印 NVS 内容调试 NVS 的时候串口打印是最直接的手段。写一个函数遍历所有命名空间和键打印出来。NVS 提供了迭代器 APInvs_entry_find、nvs_entry_next、nvs_entry_info。用这些可以列出所有键值确认数据是否正确写入。void dumpNVS() { nvs_iterator_t it NULL; esp_err_t err nvs_entry_find(nvs, NULL, NVS_TYPE_ANY, it); while (err ESP_OK) { nvs_entry_info_t info; nvs_entry_info(it, info); Serial.printf(ns%s key%s type%d\n, info.namespace_name, info.key, info.type); err nvs_entry_next(it); } nvs_release_iterator(it); }这个函数在调试时非常有用能看到实际存了什么避免我以为存进去了的错觉。7.4 关于改 WiFi 密码这个具体场景回到标题的场景。WiFi 密码改了设备要重连这个逻辑是启动时从 NVS 读 SSID 和密码调WiFi.begin(ssid, password)等待连接。如果连不上超时后切 AP 模式。用户在 AP 模式下改密码保存重启再尝试 STA。这里有个细节WiFi.begin之后要等WiFi.status() WL_CONNECTED但别死等设个超时。超时后切 AP同时可以在 AP 页面上提示当前无法连接请检查配置。另外改密码后重启如果新密码还是错的又会切 AP。这个循环是合理的用户总能通过 AP 进去改。关键是 AP 模式要稳定别因为 WiFi 库的状态混乱导致 AP 也起不来。实测下来先WiFi.disconnect()再WiFi.mode(WIFI_AP)比较稳。7.5 一个容易忽略的点NVS 键名长度限制前面提过键名最长 15 字符这个限制在实际项目中很容易踩。比如你想用mqtt_server_hostname这种长名字16 个字符直接超了。NVS 会返回ESP_ERR_NVS_KEY_TOO_LONG。解决办法就是缩写mqtt_host、mqtt_port控制在 15 以内。命名空间也是 15 字符限制。这个在项目初期就要规划好后期改键名意味着数据迁移麻烦。我一般会在代码里加个静态断言或者编译期检查确保键名不超长。Arduino 环境下可以用static_assert(sizeof(keyname) 16, key too long)把问题提前暴露。8. 写在最后配置工具的价值在于不用再碰固件这套东西做完之后最大的感受是现场调试的时间成本直线下降。以前改个参数要带电脑、找线、拆设备现在客户自己打开浏览器就能改。对于小批量部署和需要频繁调整参数的项目这个投入非常值得。代码量其实不大核心就是 NVS 封装加一个 Web 服务前端页面也很朴素。但就是这点东西解决了改配置要重刷固件这个老大难问题。如果你正在做 ESP32 的联网设备强烈建议把这套机制加上哪怕现在用不到后面一定会用到。最后分享一个小技巧在配置页面上加一个当前固件版本和当前 IP的显示方便确认设备状态。再在串口启动日志里打印配置加载情况出问题时一眼就能看出是配置没读到还是网络没连上。这些细节不起眼但能省下大量排查时间。
阅读完成 · 觉得有帮助？
