文档类型：ESP-IDF 通用 API 教程，不绑定单一开发板。
板级例程见 热门例程详解。
版本说明：本页以 ESP-IDF 5.3.3 安装为例（图文步骤仍适用）。
视频系列：A01 · 总索引：文档总目录与视频教程大纲
学习时长：约 30 分钟（含安装等待时间） · 难度：★☆☆☆☆
酷世 DIY Korvo S3 和 ESP32P4-C5 例程推荐使用 5.5.x（如 5.5.3），安装时在安装器中选择对应版本并勾选 ESP32-P4 目标（P4 板必需）。
例程编译流程见 例程开发流程与公共组件。
建议阅读顺序：ESP-IDF 框架整体构成 → 工程结构（对比 Keil）。
学习目标
完成本节后，你将能够：
- 在 Windows 上成功安装 ESP-IDF 开发环境
- 使用
idf.py build/flash/monitor三件套完成编译、下载、调试 - 理解
set-target、-p COMx、-b等常用参数的含义 - 编译小智（xiaozhi-esp32）并选择板型
1、下载离线安装包
首先进入
https://dl.espressif.com/dl/esp-idf/
或者 https://dl.espressif.com.cn/dl/esp-idf/
如果无法下载也可以进百度云链接（仅 ESP-IDF 安装包，非例程资料）：
https://pan.baidu.com/s/11jwTFJbcOsV2K_IlkBriJQ?pwd=qm34 提取码: qm34
5.3.x～5.5.x 均可安装；Korvo / P4C5 例程请选 5.5.3。小智等项目 5.4+ 也支持。
这个链接是乐鑫官方的下载网，可以在这里下载离线安装包，选择所需版本（如 5.5.3 或 5.3.3）
网页最下面也可以选各种版本
选择任意你需要安装的版本
2、安装环境
自行选择需要安装的版本，双击 EXE 文件开始安装
勾选我同意之后，一直点下一步就行了
可以在此处设置一下自己的 IDF 需要安装到的文件夹，尽量别安装到 C 盘
一直点下一步直到安装完成，等待安装完成
3、测试是否安装成功
双击桌面上的 Powershell 会自动导入 idf 环境，电脑安装了 windows terminal（win11 自带，win10 可以搜索 store 打开商店安装）的可以直接打开终端，终端的 + 号可以直接运行 idf 环境
当出现 idf.py build 字样就是安装成功了，可以编译固件了
运行 cd .\examples\get-started\hello_world\ 进入工程的目录
输入 idf.py build
这就开始编译了，编译的时候记得把所有的杀毒软件关闭，包括 360、火绒、windows defender 之类的，会大大提高编译速度
编译完成之后可以运行
idf.py build flash monitor
进行下载和查看串口输出的日志信息
如果嫌下载速度慢，可以运行以下命令，增加-b 参数 后面就是下载的波特率
idf.py -b 2000000 build flash monitor
如果不想所有分区都下载一遍，就运行以下命令，就只会下载 app 分区
idf.py build app-flash monitor
当使用不同型号的芯片时，以下为设置芯片的命令示例：
idf.py set-target esp32 设置目标芯片为 esp32
idf.py set-target esp32s2 设置目标芯片为 esp32s2
idf.py set-target esp32s3 设置目标芯片为 esp32s3
idf.py set-target esp32c3 设置目标芯片为 esp32c3
如果电脑上插入了很多个 ESP32 开发板，则需要区分端口，可以打开设备管理器看通信端口，比如我的板子端口是 COM5，就需要运行：
P4C5 开发板需先执行 idf.py set-target esp32p4；Korvo / SP V4 用 esp32s3。
idf.py -p COM5 build flash monitor
把一个工程转移到别的路径时需要删除 build 文件夹
不要把工程放到中文目录路径下！
养成良好的删除 build 文件夹的习惯！能解决各种小问题
4、编译小智
1、下载源码
进入虾哥代码主页：https://github.com/78/xiaozhi-esp32
点击 Code - Download ZIP
电脑装了 git 的话，建议还是用命令 git clone ``https://github.com/78/xiaozhi-esp32，有时候下载 zip 会有问题
下载完成后解压到任意目录备用
进入终端，打开 IDF 5.3 或者双击桌面的 ESP IDF5.3 Powershell
我解压的目录和你们的不一样，各自输入 刚刚解压的目录：
cd J:\xiaozhi-esp32-main_2\xiaozhi-esp32-main
2、设置芯片类型
默认的编译芯片是 ESP32 的，所以自己的板子是 S3 的话一定要输入以下命令把芯片设置为 S3
idf.py set-target esp32s3
如果你使用的芯片是 ESP32C3 的话，需要输入 idf.py set-target esp32c3 先把芯片类型设置为 C3，再去 menuconfig 里选择对应的板子类型
3、更换编译板子类型
默认编译出的固件是面包板的，如果需要更换板子，需要输入 idf.py menuconfig
进入 Xiaozhi Assistant 选项
自己是什么板子就选什么型号，不是一定要选 Kevin SP V3 板子，如果你是 ESP32C3 板子就要选 C3 的，并且一定要先运行 idf.py set-target esp32c3
选择需要编译的板子固件后按键盘的‘S’键保存 然后 Esc 退出 menuconfig
4、开始编译
再次输入 idf.py build 进行编译
编译完成后输入 idf.py build flash monitor 进行下载和显示日志
5、如何修改唤醒词
输入 idf.py menuconfig 进入配置界面
键盘上下选择 ESP Speech Recognition
选择任意唤醒词后按 Enter 确定后按键盘的'S'保存退出
6、如何修改 websocket api 接口
最新的 1.6.1 版本已经取消了从 menuconfig 配置 websocket 接口的源码，需要切换到 1.6.0 或者以下才可以
执行 git checkout v1.6.0
输入 idf.py menuconfig 进入配置界面
键盘上下选择 Xiaozhi Assistant
选择 Websocket 确定
输入自己的 api 地址后保存退出重新编译
7、安装串口驱动
有的用户电脑没有串口驱动下载过程中一直卡着不动的情况下可以尝试一下安装以下驱动：
MAC 下的驱动：
Windows 下的驱动：
I2C 冲突的问题解决办法：
如果您编译烧录后发现出现以下问题：
当然在最新版本代码里已经修复了此问题
进入 idf.py menuconifg->Component config->Audio Codec Device Configuration
关掉第一行后重新编译烧录就可以了
