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。