小智 ESP32 固件 v2.5 解读：ESP-IDF 6、全矩阵发布与安全加固
小智 ESP32 固件 v2.5 解读：ESP-IDF 6、全矩阵发布与安全加固
October 23, 2026
上游固件仓库 78/xiaozhi-esp32 在 2026 年 7 月到 10 月之间连续发布了 v2.4.x 和 v2.5.x。这一轮变化里，真正会影响你操作的只有三件事：自行编译必须换到 ESP-IDF 6、预编译固件的发布方式变了、协议实现补了一批校验。本文按版本梳理，每一条都标注了来源提交或文档，方便你自己核对。
本文的版本归属按“提交首次出现在哪个标签”判断，数字取自
v2.5.2 标签与该版本的发布清单。上游继续演进，请以官方发布页为准。一、先看结论
| 你是谁 | 需要做什么 |
|---|---|
| 只想烧录现成固件 | 到固件下载页选择自己的开发板变体，不需要安装开发环境 |
| 自己编译固件 | 安装 ESP-IDF v6.0.1 或更高版本（推荐 release/v6.1 分支），不再支持 ESP-IDF 5.x，见开发环境搭建 |
| 维护自定义开发板 | 板级代码要跟随 ESP-IDF 6 调整，见自定义开发板迁移到 ESP-IDF 6 |
| 自建服务端或写客户端 | 协议文档已更新，见 WebSocket 与 MQTT + UDP |
二、版本脉络
| 版本 | 主要变化 | 来源 |
|---|---|---|
| v2.4.0 | 迁移到 ESP-IDF 6.0，随后补充迁移加固 | 3e78cd7（#2120）、0f6c435（#2123） |
| v2.4.2 | 新增 ESP32-S31 板卡支持 | 3e86f0a（#2151） |
| v2.5.0 | 移除 ESP-IDF 5.x 支持；新增流式 notify 播放；MCP 增加字符串长度校验与 JSON-RPC 错误码；新增巴西葡萄牙语界面 | 4a5d446、bb9122a（#2191）、acb2fc7（#1847）、d68505f（#2243） |
| v2.5.2 | 新增手动触发的全矩阵固件发布工作流；WebSocket 与 OTA 安全修复；以太网 IP101 驱动迁移到 ESP-IDF 6 | 49b4380（#2302）、d436097、f05adce、d395220 |
v2.5.2 的 PROJECT_VER 为 2.5.2。
三、构建：迁移到 ESP-IDF 6
- 一次大迁移：
3e78cd7一个提交改动了 119 个文件，涉及各板卡的驱动头文件、依赖版本与音频编解码器；板级写法的变化见迁移文章。 - 版本要求：
main/idf_component.yml中写明idf: '>=6.0.1'；上游 README 推荐使用release/v6.1分支，不再支持 ESP-IDF 5.x。 - 一个已知问题：README 提醒避免使用
v6.1发布标签，该标签在 ESP32-C3 上有 Wi-Fi 初始化失败的报告（issue #2344）。 - 切换 SDK 的步骤：执行
git submodule update --init --recursive，重新加载export.sh，再执行idf.py fullclean，详见开发环境搭建。 - ESP32-S31：该芯片的变体需要 ESP-IDF 6.1 或以上。
四、发布：全矩阵固件工作流
49b4380 新增了手动触发的 Release Firmware 工作流，规则写在上游 docs/releasing.md：
- 用
scripts/build.py <board> --name <variant> --zip构建 ESP-IDF 6.1 支持的全部发布变体； - 每个变体产出
v<version>_<variant>.zip，里面是一个merged-binary.bin； - 另附完整变体清单
release-manifest.json和所有压缩包的SHA256SUMS。
v2.5.2 的发布清单记录了 154 个板目录、188 个固件变体，由 ESP-IDF 6.1.0 构建，完整名单见支持的开发板。
上游 README 里“支持 138 个板卡目录、171 个固件发布变体”的数字比发布清单旧，本站以发布清单为准。下载后建议用
SHA256SUMS 校验压缩包。五、功能与协议
- 流式 notify：
bb9122a增加流式播放，设备可以在对话之外异步播放服务端推送的语音通知，说明见异步语音通知。 - Glyph Push：服务端可以下发本地字体缺失的字形，说明见Glyph Push 扩展。
- MCP 校验：设备端 MCP 对字符串参数增加
max_length校验，并返回 JSON-RPC 错误码，见 MCP 协议。 - ESP32-P4：每个 P4 构建拆成 rev < 3 与
-p4x两个变体（b7dc88f）。 - 界面语言：新增 pt-BR 界面语言（
d68505f）。
六、安全加固
下面是上游提交说明中明确写出的加固点：
| 位置 | 变化 | 来源 |
|---|---|---|
| MQTT | 校验 goodbye 消息的 session id | e182471（#2023） |
| WebSocket | 服务端 hello 的 transport 不是字符串时，旧实现会对空指针调用 strcmp 导致设备崩溃；现在先检查类型 | d436097（#2247） |
| OTA | 拒绝不安全的 eFuse 序列号 | f05adce |
| 加密 | MQTT 与 BluFi 加密迁移到 PSA Crypto | 上游 README“近期更新” |
这些修复在 v2.5.2 中都已包含。
七、文档变化
上游 docs/ 现在以英文为主，中文版以 *_zh.md 命名。新增或大改的文档包括 custom-board、websocket、mqtt-udp、mcp-protocol、mcp-usage、blufi、glyph-push、notify 与 releasing。本站对应页面已按 v2.5.2 重写：
对照来源
- 上游标签
v2.5.2、v2.5.0的提交历史、README_zh.md、docs/releasing.md与main/idf_component.yml； - 核对日期：2026-10-23。更正或补充请发邮件到 [email protected]。