故障排查
以下条目按「现象 / 可能原因 / 处理办法」整理，主要来自官方常见问题 Q&A 与官方教程（烧录、配网教程的异常章节），以面包板方案为主。官方文档为早期固件口径，当前固件以 v2.5.2 发布包为准；接线引脚以官方接线教程的表格为准，照片仅供参考。
烧录失败或识别不到开发板
现象：Flash Download Tool 无法开始烧录、识别不到芯片或加载 bin 报错。
可能原因：芯片型号选错、UART 口插错、bin 未勾选、地址不是 0x0、COM 端口选错或被占用、只用了供电线的 USB 线、路径含中文、串口驱动未装。
处理办法：
- 芯片类型选 ESP32-S3，工作模式选 Develop，加载模式选 UART
- 开发板正面 TypeC 朝下时右边为 UART 口（背面丝印 COM），个别定制板按丝印识别
- bin 文件前的复选框一定要勾选
- 地址填 0x0 或 0x00 或 0
- COM 端口在设备管理器「端口（COM 和 LPT）」里查看，不确定时插拔板子看新增的端口
- 换一根可传数据的 Type-C 数据线（细小充电线只有两芯电源线，不能数据通信）
- 烧录工具和固件路径不能含中文
- 驱动按芯片型号装，CH340、CH343 到 wch.cn 对应产品页下载，CP210 等串口桥芯片同样先装驱动
- SPI SPEED 和 MODE 保持默认，不要选 QOUT 和 DOUT
- 若仍连不上，进 boot 模式再试：按住 BOOT 键不放，再按 RST 键约 0.5 秒，松开 BOOT，串口出现「烧录模式 / Auto program」提示即成功，可反复几次
烧录后反复重启或 E 级报错
现象：烧录完成后设备在串口控制台上不断重启，或出现 E 级报错，不能正常工作。
可能原因：开发板与固件不匹配。
处理办法：确认所选固件与开发板对应（选错了程序可能无法运行，屏幕也不显示）；没有默认支持的其他开发板直接烧录可能无法运行，需要修改程序源代码重新编译去适配。
ESP-Launchpad 网页 Program 按钮灰色
现象：已加载 bin 文件，但 Program 烧录按钮是灰色的，不能点击。
可能原因：开发板未 Connect、浏览器缓存、bin 未真正加载。
处理办法：
- 先确认网页显示 Connected to device: ESP32-S3，没有就先点菜单上的 Connect 授权连接
- 用 F5 或 Ctrl+R 刷新页面
- 刷新后「选择文件」未加载就重新加载 bin
- 或先 Disconnect 再重新 Connect
- 仍不行就重启或换一个浏览器
搜不到 Xiaozhi-xxx 热点
现象：配网有提示音或屏幕显示已进入配网，但手机或电脑搜不到 Xiaozhi-xxx 名称的 WiFi。
可能原因：开发板 WiFi 信号问题（部分非乐鑫官方模组的板子存在批次质量问题）。
处理办法：
- 用软导线围绕开发板上 ESP32-S3 模块的天线位置缠绕约 3 圈，增强天线信号接收
- 靠近 WiFi 路由器信号较好的位置
- 临时用手触摸天线位置完成联网
- 长期方案是选带天线座的开发板或乐鑫官方模组（带乐鑫 LOGO）
- 不确定固件是否烧录成功时，接串口工具看日志定位
连不上 WiFi 或配网失败
现象：在配网页面选了 WiFi、填了密码，仍连接失败。
可能原因：选到 5G 频段、密码错误、二次认证网络、iPhone 热点兼容性。
处理办法：
- 设备仅支持 2.4G 网络，请在热点扫描到的 2.4G 网络列表中选择自己的 WiFi（选中后 SSID 自动填写，不用手动输入）
- 需要二次验证的校园网或商业网络，ESP32 的 WiFi 模块默认连接不上，换普通 WiFi 或手机热点
- 用 iPhone 热点时打开「最大兼容性」选项
- 密码错误就重新配置一遍
说唤醒词无反应
现象：对着设备说唤醒词，没有任何反应。
可能原因：唤醒词不对、麦克风接线错误或器件损坏。
处理办法：
- 先核对唤醒词——官方 Q&A 说「唤醒词默认是 你好小智」并明确否定「小智你好」「小智小智」和配置的角色名字，官方 FAQ 却写「小智小智」，两处口径冲突，以设备实机首次播报或屏幕提示为准，先按设备提示的词试
- 再查 INMP441 麦克风 6 个引脚的接线：GPIO4 接 WS、GPIO5 接 SCK、GPIO6 接 SD、3V3 接 VDD、GND 接 GND 并短接 L/R，进声孔和麦克风图标丝印那面朝上，排针被焊反的按官方麦克风反接图对照接线，VDD 和 GND 不能反接否则容易烧坏
- 接线确认正确仍不行，更换备用麦克风测试（自己焊接的检查有没有短路，外围金色圆边是接地 GND，不能和数据引脚短接）
- 仍不能确认固件是否烧录成功，用串口工具选择 ESP32-S3 开发板右边对应 COM 端口连接，打开串口看输出日志
喇叭无声
现象：设备能唤醒、屏幕显示正常，但喇叭没有声音。
可能原因：正负极接反或接触不良、功放接线错误、供电不足。
处理办法：
- 喇叭一般红色线为正极、黑色线为负极，功放音频+接喇叭正极、音频-接负极
- 对照接线表查 MAX98357A：GPIO7 接 DIN、GPIO15 接 BCLK、GPIO16 接 LRC、3V3 接 Vin 并短接 SD、GND 接 GND 并短接 GAIN（BGA 封装功放可不短接 GAIN），面包板接触不良用万用表测通联
- 喇叭功率达到 3W 时用电脑 USB 口供电可能出现供电不足，喇叭卡顿或突然没有声音，改用 5V2A 及以上的 USB 充电头或 5V2.1A 的充电宝 USB 口供电，一般能恢复正常
- 仍不行更换备用喇叭和数字功放模块测试
声音沙哑或有杂音
现象：喇叭有沙哑的声音，或声音里有沙沙的电声。
可能原因：数字功放 GAIN 没有接地 GND 或接地不稳定、电磁干扰。
处理办法：检查 GAIN 引脚是否接到 GND 且接触良好，面包板质量差时用万用表测试通联；电磁干扰引起的话，将设备远离强磁场设备或模块、隔离充放电电源，或加锡箔片等金属屏蔽隔离。
屏幕不亮
现象：OLED 屏幕没有点亮。
可能原因：接线错误或接触不良、屏幕损坏。
处理办法：
- 查 4 脚 OLED 屏幕的引脚接线：GPIO41 接 SDA、GPIO42 接 SCK、3V3 接 VCC、GND 接 GND
- 先确认开发板是 44 引脚乐鑫标准版（第 1 版）还是 42 引脚果云版（第 2 版），对照对应版本的接线表格检查（照片只做参考），面包板问题用万用表测通联
- 确定接线正确还是不亮，更换备用屏幕测试，如果更换后可以使用，则原来的屏幕可能烧坏了
sRGB 彩灯不亮
现象：彩灯从通电起一直不亮，设备其他功能正常。
可能原因：RGB 灯旁边的两个焊点未接通（部分厂商出厂未焊）。
处理办法：用导线接通或用电烙铁短接 RGB 灯座旁的两个焊点，重启后查看是否会亮。该问题不影响配网和设备使用，但看不到配网状态和 AI 对话状态；烧录时这个焊点未接通只会出现 warning 警告，不影响烧录。也可断电拔下所有模块，单独给开发板上电看是否正常闪烁蓝灯，确认线路连接正确后再装回模块联网测试。
需要重新配网
现象：更换 WiFi、修改密码或原网络关闭后，设备连不上原来的网络。
处理办法：
- 将开发板重新上电或重启，在连接 WiFi 闪烁蓝灯时直接按下 Boot 按钮然后松开，听到提示音即重新进入 WiFi 配网模式（固件较新时，开机后直接按住 boot 键即重新配网，不再连接上次的 WiFi）
- 固件版本 ≥0.2.2 时，重试 3 次连接原 WiFi 失败后会自动重新进入配网模式
- v0.2.2 以下旧版需按住配网按键（连接 1 号引脚和 GND）同时按 RST，先松开 RST 再松开配网按键
设备默认只记住上次连接的 WiFi 及密码，换网络就要重新配置。以上版本号为官方教程的早期固件口径，当前固件以 v2.5.2 发布包为准。