常见问题

本页按问题类型整理 ESP32 桌面小助手常见排查项。

🔌 烧录与串口

电脑找不到串口

• 换一根支持数据传输的 USB 线。
• 安装开发板对应的 USB 转串口驱动。
• 尝试按住 BOOT 后点按 EN / RESET，让设备进入下载模式。
• 换电脑主板直连 USB 口，避免部分扩展坞供电或数据不稳定。

烧录失败或中途超时

• 降低烧录波特率，例如从 921600 改成 460800 或 115200。
• 换 USB 口或 USB 线。
• 先执行 erase_flash 后再重新写入。
• 如果使用分散固件，请确认每个文件和地址都填对。

🖼️ 屏幕与触摸

屏幕白屏 / 花屏 / 方向不对

• 确认屏幕型号是 TK020F1131，分辨率为 240×300。
• 检查 MOSI、SCLK、CS、DC 是否接反。
• 确认下载的是匹配该硬件版本的固件。
• 如果使用面包板调试，可用万用表检查线材是否接触良好。

触摸位置不准

• 检查 TP SDA / TP SCL 是否接到 GPIO 1 / GPIO 2。
• 确认触摸屏 IC 为 CST816 系列兼容型号。
• 如果使用不同屏幕，需要重新适配触摸坐标方向。

屏幕没有点亮

• 检查屏幕供电和接地是否正确。
• 检查屏幕排线、转接板和杜邦线是否接触良好。
• 面包板质量有好坏，有问题时可以使用万用表测试通联情况。
• 如确定接线正确仍无法解决，可更换备用屏幕测试。

🔊 音频与麦克风

没有声音或麦克风无输入

• 确认音频模块与固件支持的方案一致。
• 检查 LRCLK、BCLK、SDA、DATA、CLK 五根信号线。
• 确认音频模块供电为 3.3V。
• 检查喇叭是否接好，一般红色线为正极，黑色线为负极。
• 如使用电脑 USB 口供电，喇叭功率较高时可能供电不足，建议改用稳定电源。

喇叭有沙哑声或电流声

• 检查数字功放接地是否稳定。
• 检查喇叭线、音频模块和 ESP32-S3 是否接触良好。
• 将设备远离强磁场设备、充放电模块或干扰源。
• 如确定接线正确仍无法解决，可更换备用喇叭和音频模块测试。

如何调整终端音量？

目前推荐引脚方案不支持通过外部引脚直接调节音量。后续如固件支持音量设置，会在文档中补充。

📶 Wi-Fi 与配网

终端提示配网，但是找不到 xiaozhi-xxx Wi-Fi

这通常说明 ESP32-S3 开发板 Wi-Fi 信号存在问题，可以尝试：

• 临时用手靠近开发板天线位置，或调整线束位置尝试增强信号。
• 让手机或电脑靠近设备重新扫描 Wi-Fi。
• 使用串口工具查看开发板输出信息，定位是否进入配网模式。
• 如果你的开发板带外接天线座，确认天线已经正确安装。

如何重新配网或切换 Wi-Fi？

• 将开发板重新上电或重启，在连接 Wi-Fi 闪烁蓝灯时，按下 BOOT 按钮然后松开，听到提示音后重新进入 Wi-Fi 配网模式。
• 当小智 AI 连接上次配置的 Wi-Fi 失败 3 次后，也会自动重新进入 Wi-Fi 配网模式。
• 当前小智 AI 默认只记住上次连接的 Wi-Fi 和密码，更换 Wi-Fi 或热点关闭时，需要重新配置。

🖥️ Media Saber 数据加载

看不到 Media Saber 数据

• 确认设备与 Media Saber 服务端在可互通的网络内。
• 检查服务地址、端口、认证信息是否正确。
• 用同一局域网的手机或电脑浏览器访问 Media Saber 地址，确认网络可达。
• 在 Media Saber 服务端确认相关接口和消息中心功能可正常使用。

消息中心快捷指令没有效果

• 确认 Media Saber 后端服务正常。
• 确认设备配置的认证信息仍然有效。
• 根据设备 Toast 或消息提示，在 Web 端检查对应功能是否可用。

🔐 两步验证码

两步验证码页面为空

• 确认已在「应用 → 用户中心」配置好 Media Saber 后端。
• 在 Media Saber Web 端添加自定义两步验证账号，或确认 PT 站点已填写两步验证密钥。
• 账号列表每 60 秒刷新一次，添加后稍等片刻。

验证码为什么会变色？

验证码每 30 秒滚动一次。倒计时 ≤10 秒变金色，≤5 秒变红色，用来提醒你尽快输入，或者等下一轮验证码。

🎬 排行订阅

排行推荐无法订阅

• 确认已在「应用 → 用户中心」配置好 Media Saber 后端。
• 在 Media Saber Web 端设置好默认订阅配置，区分电影和电视剧。
• 如果提示失败，按 Toast 文案在 Web 端检查订阅相关设置。

已订阅的卡片可以再次点击吗？

订阅成功后，卡片会显示「✓ 已订阅」标记；再次点击可取消订阅。

🗣️ 小智 AI 相关

支持更换唤醒词吗？

支持。需要在用户界面打开 Web 配置，进入唤醒词配置并填写拼音。

角色名称可以换吗？

可以。到小智 AI 管理后台控制面板的角色配置中修改 AI 角色名字，保存后生效。

注意：角色名字是大模型配置的智能体名称，与离线唤醒词「你好小智」无关，两者不存在关联。控制台地址：https://xiaozhi.dev/console/

支持更换声音或音色吗？

支持。到小智 AI 网站控制台的角色配置中切换角色声音，可以先试听，然后提交保存配置。下次对话会使用新的音色。管理后台：https://xiaozhi.dev

能听声辨人并记住我是谁吗？

可以，操作步骤：

1. 到小智 AI 网站后台控制台，进入智能体配置。
2. 找到声纹识别。
3. 在下拉菜单中选择一段语音记录，建议选择较长且清晰的语音。
4. 填写名称和描述。
5. 点击确认添加说话人。
6. 重新唤醒小智 AI，下次对话中询问时，它会知道你是谁。

声纹识别不是 100% 准确

受技术限制，识别准确率不是 100%；说话人越多，分辨准确率会下降。

为什么“你好小极”无法唤醒或无反应？

• 确认唤醒词正确，是“你好小极”，不是“小智小极”或其它词。
• 检查麦克风引脚接线是否正确且接触良好。
• 如果使用 INMP441 麦克风，通常带麦克风图标和丝印字母、带进声孔的一面朝上。
• 如接线正确仍无法解决，可更换备用麦克风测试。
• 使用串口通信工具检查开发板输出信息，也可以帮助定位问题。