ESP32 開發問題排查
本頁按症狀整理排查入口。每條建議都來自韌體原始碼、上游文件或站內已核對的頁面；沒有依據的經驗性說法不收錄。使用類問題（配網、啟用、綁定）請先看首次啟動和常見問題。
一、編譯與環境
| 症狀 | 檢查 | 處理 |
|---|---|---|
| 編譯報 ESP-IDF 相關錯誤 | idf.py --version | 韌體要求 ESP-IDF v6.0.1 或更高，推薦 v6.1；不支援 IDF 5.x，詳見 ESP-IDF 開發環境搭建 |
| ESP32-S31 變體編譯失敗 | IDF 版本 | 該晶片的變體需要 ESP-IDF 6.1 或以上，自行編譯時推薦 release/v6.1 分支 |
| 找不到板型或變體名 | 名稱拼寫 | 先執行 python3 scripts/build.py --list-boards 檢視準確的板目錄與變體名，再用 python3 scripts/build.py <板目錄> --name <變體名> 建置 |
| 切換板子後配置異常 | 本地建置狀態 | scripts/build.py 會改寫 sdkconfig 和建置狀態，不要假定舊的建置目錄還對應上一個目標，重新用指令碼建置 |
| 板子定義重複或缺失 | DECLARE_BOARD | 一次建置必須恰好匯出一個 DECLARE_BOARD(...)，參見自訂開發板指南 |
| 手工改過生成檔案後行為奇怪 | build/、managed_components/、sdkconfig*、main/assets/lang_config.h | 這些是生成物或第三方輸出，不要手工修改，恢復後重新建置 |
二、燒錄
- 預編譯韌體把合併映象寫入位址
0x0，步驟見韌體下載與安裝。 - 燒錄失敗或擦除失敗時，先把開發板從麵包板上取下，單獨連線電腦再試。
- 序列埠名稱因系統而異：Linux 常見為
/dev/ttyACM0或/dev/ttyUSB0，macOS 常見為/dev/cu.usbmodem*，Windows 為COMx；必要時用-p <序列埠>指定。 - 部分開發板有專用的 Flash 參數說明，見上游儲存庫中該板目錄下的 README。
三、沒有聲音或無法錄音
按下面的順序排查：
- 接線：對照硬體搭建指南的引腳表逐根核對，上電前用萬用表確認 GND 與 3.3V 之間沒有短路。
- 板級宣告：板級
config.h中的麥克風通道宣告（M或MR）必須與編解碼器回傳的交織 PCM 一致；R通道只能放回放參考，不能當作第二個麥克風（見上游main/audio/README.md）。 - I2S 模式：Simplex 與 Duplex 的引腳不同，改用其中一種時要同時改
config.h裡的引腳定義。 - 取樣率：多數板級配置為輸入 16 kHz、輸出 24 kHz，自訂板子需要與編解碼器匹配。
用 Audio Debugger 抓取音訊
韌體可以把採集到的音訊透過 UDP 發到電腦，用來判斷問題出在採集還是後面的環節：
- 在
menuconfig開啟USE_AUDIO_DEBUGGER（預設關閉），並把AUDIO_DEBUG_UDP_SERVER設為電腦的IP:埠（預設192.168.2.100:8000）。 - 在電腦上執行上游指令碼，它監聽 UDP 8000 埠並寫入 WAV 檔案：
python3 scripts/audio_debug_server.py --samplerate 16000 --channels 2--samplerate 預設 16000，--channels 預設 2，需要與你抓取的資料格式一致。
四、無法喚醒
- 沒有 PSRAM 的板子：預設不啟用本機喚醒詞，請用按鍵對話或外接喚醒模組，見ESP32 丐版。
- 晶片不匹配：AFE 喚醒詞和 MultiNet 自訂喚醒詞只支援帶 PSRAM 的 ESP32-S3 / P4 / S31，C3、C5、C6 以及帶 PSRAM 的 ESP32 使用無 AFE 的 WakeNet，見晶片支援與儲存規格。
- 自訂喚醒詞不靈敏：
CUSTOM_WAKE_WORD_THRESHOLD範圍 1-99，數值越小越靈敏，預設 20；中文喚醒詞要寫成用空格分隔的拼音。 - Assets 喚醒詞模型：見自訂 Assets 指南中的校驗與版本提示。
五、聯網、啟用與升級
- 配網與啟用問題見首次啟動和網路配置；
/activate回傳 202 時裝置會等待並重試，不是故障。 - 版本檢查失敗時裝置會按重試間隔再次檢查，不需要手動重啟。
- 如果自行部署了伺服器，對照 WebSocket 通訊協議與 MQTT + UDP 混合協議檢查握手與訊息格式。
六、assets 資源問題
| 日誌 | 含義 |
|---|---|
No assets partition found / Assets partition is disabled | 分區表沒有 assets 分區 |
| 校驗和不匹配 | assets.bin 損壞或寫入偏移不對 |
The assets version N is not supported, please upgrade the firmware | 索引版本高於韌體支援的版本 |
Assets file size ... is larger than partition size | 檔案超過分區大小 |
處理方法見自訂 Assets 指南。
七、反饋問題時請提供
- 韌體版本、板目錄與變體名（例如
bread-compact-wifi），以及晶片型號； - ESP-IDF 版本（
idf.py --version的輸出）； - 完整的序列埠日誌，從啟動到出錯的部分；
- 復現步驟，以及是否在實體硬體上驗證過。
可以到上游 GitHub Issues 反饋韌體問題。
相關文檔
對照來源：78/xiaozhi-esp32 v2.5.2 的 AGENTS.md、main/audio/README.md、main/Kconfig.projbuild、main/assets.cc、scripts/audio_debug_server.py。