ESP32-S3+小智AI：环境搭建与烧录实操（从装环境到说上话）

上一篇《AI语音硬件选型与接线实操》讲了板子怎么选、外设怎么接，这篇把它真正跑起来：环境搭建、固件编译、烧录、配网，一路到对着它说"你好小智"。两种路线都给你：不想装编译环境的免编译烧录，和想改代码的 ESP-IDF 编译路线。

---

先泼一盆冷水：网上大部分小智AI环境教程还停留在 ESP-IDF v5.x，照着装会直接在 set-target 就报错——小智 v2.x 固件要求 ESP-IDF 5.4.0 或更高版本，报错长这样：

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

所以本篇所有步骤都按 ESP-IDF 5.4+ 来写，别再踩 v5.3 的坑了。

一、开工前的清单

硬件（承接上一篇选型）：

• ESP32-S3-DevKitC-1（认准 N16R8，八线 Octal PSRAM）
• 麦克风（INMP441）+ 功放（MAX98357A）+ 喇叭 + OLED——按上一篇接线表接好
• 一根能传数据的 Type-C 线（纯充电线烧不进去，这是第一大坑）

软件（两条路线二选一）：

项目	路线A：免编译烧录	路线B：ESP-IDF 编译
适合谁	首次上手、只想先跑起来	想改代码、二次开发、做毕设
需要装	Flash 下载工具 + 固件包	ESP-IDF 5.4+（约4~5GB）
改动能力	不能改代码	完全可控
耗时	10分钟	首次编译30分钟左右

二、路线A：免编译烧录（10分钟跑起来）

1. 下载工具和固件

• Flash 下载工具：乐鑫官网 Flash Download Tools（3.9.7 即可），解压后直接运行 flash_download_tool_3.9.7.exe，无需安装
• 固件：小智AI 发布页下载 vx.x.x_bread-compact-wifi.zip（面包板 WiFi 版；只有装了 ML307R 4G 模块才选 ml307 版），解压得到 merged-binary.bin

注意：工具和固件都不要放中文路径，否则可能加载失败。这是非常常见的翻车点。

2. 连接开发板

开发板正面 Type-C 朝下时，右边的接口是 UART 口（烧录用它），左边是 USB 口——接错口会找不到串口。

3. 烧录

打开工具后配置：

• ChipType：ESP32-S3
• WorkMode：Develop
• LoadMode：UART

点 OK 进入主界面，第一行空白框选择 merged-binary.bin，烧录地址填 0x0，点 START 开烧。看到进度条走完即成功。

如果工具弹 libpng warning 或找不到 sRGB 灯——开发板没焊灯开关导致的，不影响烧录，忽略即可。

三、路线B：ESP-IDF 编译（可改代码）

1. 安装 ESP-IDF 5.4+

去乐鑫官网下载 Windows 离线安装包（5.4.x 或更新），一路默认安装。装完开始菜单会出现 "ESP-IDF 5.4 CMD" 快捷方式——以后所有命令都在这个专用终端里跑（普通 cmd/PowerShell 里找不到 idf.py）。

2. 拉源码

git clone https://github.com/78/xiaozhi.git
cd xiaozhi

3. 配置目标芯片

idf.py set-target esp32s3

4. 菜单配置

idf.py menuconfig

进去之后重点看三块：

• WiFi 设置：默认已适配面包板方案，确认 SSID 相关的配置项
• 音频设置：确认麦克风/功放型号与接线对应（INMP441 / MAX98357A）
• 显示设置：OLED 是 0.96寸(128×64) 还是 0.91寸(128×32)——上一篇提过，选错配置白屏

5. 编译

idf.py build

首次编译要拉取组件、下载工具链，10~30 分钟不等，第二次就快了。成功后在 build 目录生成固件。

6. 烧录与看日志

idf.py flash    # 烧录（自动进下载模式）
idf.py monitor  # 串口日志，看启动和配网状态

编译报错先试 idf.py clean 再 idf.py build；还报错就看是不是版本没到 5.4。

四、配网 + 激活设备（关键一步）

固件跑起来后，还不是马上能对话——要配网 + 在控制面板绑定设备：

1. 进入配网模式：开发板开机（或按提示触发），屏幕提示进入配网模式
2. 手机连 WiFi：打开手机 Wi-Fi，连接以 xiaozhi- 开头的热点（密码 12345678）
3. 填写路由 WiFi：连接后自动跳转配网页（没跳转就浏览器访问 192.168.4.1），选择你家 2.4G 频段的 WiFi 并输密码（不支持 5G、不支持需要网页二次认证的 WiFi）
4. 唤醒设备：配网成功后对着设备说 "你好小智"，它会提示输入 6 位设备验证码（可重复唤醒重听）
5. 绑定设备：电脑浏览器打开小智控制面板（xiaozhi.me），登录后"添加设备"，把 6 位验证码填进去，绑定完成

至此，喊一声"你好小智，今天天气怎么样"，它就能对话了。

五、踩坑清单（亲测高频翻车点）

1. 版本必须 5.4+：老教程的 v5.x/v5.3 全部作废，set-target 直接报依赖错误
2. 烧录工具别放中文路径：工具和固件放 D:\tools 这类纯英文目录
3. UART 口和 USB 口别接混：Type-C 朝下时的右边是 UART（烧录），接错口找不到串口
4. 数据线必须是数据线：纯充电线烧录失败第一嫌疑人
5. WiFi 必须 2.4G：5G 频段或需二次认证的 WiFi 都连不上
6. OLED 型号和配置要一致：0.96 和 0.91 是两个固件选项，装错白屏
7. sRGB 灯警告可以忽略：板子没焊灯开关时工具弹警告，不影响烧录

六、写在最后

从选型、接线到烧录配网，小智AI 这套现在已经完整跑通了。下一篇进入二次开发：用 MCP 协议让小智AI 控制 GPIO、操作舵机和外设——语音控制硬件，这才是它最好玩的部分。

本文步骤基于小智AI官方文档与乐鑫 ESP-IDF 官方文档整理。本人嵌入式工程师（蓝牙音频/STM32/ESP32方向，3年原厂量产经验），本系列为个人技术记录，后续将陆续更新小智AI 二次开发系列教程。