小智 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]。