ESP-IDF 開發環境搭建及編譯小智

本文說明如何搭建 ESP-IDF 開發環境並編譯小智韌體。範例以 Windows 為主，Linux 的命令列步驟相同。

開發環境選擇

• 編輯器：Cursor 或 VSCode，安裝 ESP-IDF 外掛，SDK 版本選擇 v6.0.1 或更高。
• 系統：官方建議優先使用 Linux，編譯速度更快，也免去序列埠驅動問題；Windows 同樣可用。
• 程式碼風格：專案使用 Google C++ 風格，提交程式碼前請參考 程式碼風格指南。

安裝 ESP-IDF

1. 下載安裝包

Windows 可以從以下位址取得 ESP-IDF 安裝程式：

• Espressif 官方下載
• Espressif 中國鏡像

安裝時請選擇 v6.0.1 或更高版本。如果要使用推薦的 release/v6.1 分支，可以透過 Git 取得：

git clone -b release/v6.1 --recursive https://github.com/espressif/esp-idf.git

2. 安裝步驟

1. 雙擊下載的安裝程式開始安裝
2. 同意授權協議
3. 選擇安裝路徑（建議不要安裝在 C 槽，路徑中不要包含中文）
4. 依照精靈完成安裝

3. 驗證安裝

1. 開啟安裝程式建立的 ESP-IDF PowerShell 捷徑（名稱隨所選版本略有不同）
2. 終端機會自動匯入 IDF 環境
3. 確認版本不低於 6.0.1：

idf.py --version

4. 編譯一個範例專案：

cd examples/get-started/hello_world/
idf.py build

編譯小智韌體

1. 取得原始碼

# 透過 Git 複製（推薦）
git clone https://github.com/78/xiaozhi-esp32

# 或者從 GitHub 下載 ZIP 壓縮包

2. 設定開發板

1. 設定目標晶片：

# ESP32-S3
idf.py set-target esp32s3

# ESP32-C3
idf.py set-target esp32c3

2. 選擇開發板：

idf.py menuconfig
# 進入 Xiaozhi Assistant -> Target Board

3. 編譯與燒錄

基本指令：

# 僅編譯
idf.py build

# 編譯並燒錄
idf.py build flash monitor

# 使用更快的燒錄速度
idf.py -b 2000000 build flash monitor

# 指定序列埠
idf.py -p COM5 build flash monitor

4. 常見設定修改

修改喚醒詞

idf.py menuconfig
# 進入 ESP Speech Recognition -> Wake Word

修改 WebSocket API

idf.py menuconfig
# 進入 Xiaozhi Assistant -> Websocket -> Websocket URL

切換 ESP-IDF 版本後的必做步驟

從 5.x（或其他版本）切換到 v6.0.1+ 後，需要讓相依套件與快取和新 SDK 對齊：

# 在 ESP-IDF 目錄中更新子模組
cd <esp-idf 目錄>
git submodule update --init --recursive

接著重新載入該目錄下的 export.sh（Windows 使用對應的 ESP-IDF PowerShell 環境），再回到小智專案目錄執行：

idf.py fullclean
idf.py build

常見問題

1. 提升編譯速度

• 關閉防毒軟體（包括 Windows Defender）
• 刪除 build 資料夾後重新編譯

2. 序列埠驅動問題

如果無法識別序列埠，需要安裝對應晶片的 USB 驅動。

3. I2C 衝突解決

如遇到 I2C 衝突問題：

1. 進入 idf.py menuconfig
2. 選擇 Component config -> Audio Codec Device Configuration
3. 關閉第一個選項
4. 重新編譯

4. 錯誤：project depends on idf (>=6.0.1)

如果遇到類似下面的錯誤：

ERROR: Because project depends on idf (>=6.0.1) which doesn't match any versions, version solving failed.

表示目前環境使用的 ESP-IDF 版本過舊（例如 5.x）。專案在 main/idf_component.yml 中宣告了 idf: '>=6.0.1'。請安裝 ESP-IDF v6.0.1 或更高版本（推薦 release/v6.1 分支），確認終端機載入的是新版本環境後重試：

idf.py set-target esp32s3
idf.py build

5. ESP32-C3 上 Wi-Fi 初始化失敗

如果使用的是 v6.1 發布標籤，並在 ESP32-C3 上遇到 Wi-Fi 初始化失敗，請改用 release/v6.1 分支，參見 issue #2344。

6. Windows 編譯提示命令列過長

如果 Ninja 回報 CreateProcess 錯誤（編譯器命令超過 32,767 字元上限），可在同一個專案目錄、同一個 ESP-IDF 終端機中執行：

idf.py -D CMAKE_NINJA_FORCE_RESPONSE_FILE=ON reconfigure
idf.py build

執行 idf.py fullclean 或清空 CMake 快取後需要重新執行 reconfigure。將專案移到較短的路徑（例如 E:\xz）也可能緩解問題。參見 issue #2340 中的解決方法。

注意事項

1. 專案路徑不要包含中文
2. 轉移專案時記得刪除 build 資料夾
3. 確保使用正確的晶片型號設定
4. 建議定期清理 build 目錄以解決編譯問題

進一步閱讀

• 自訂開發板指南
• 韌體下載與發布說明
• 來源：xiaozhi-esp32 README、main/idf_component.yml