Mac 安装 ESP-IDF 开发环境,并使用 idf.py 烧录 ESP32 项目
本文详细解析了在 macOS 上安装 ESP-IDF 开发环境并使用 `idf.py` 烧录 ESP32-S3 项目的完整流程,包括通过 Espressif Installation Manag
最近开始学习 ESP32,我手上是一块小智 AI 相关的开发板,商家说板型是 Bread Compact WiFi + LCD,芯片是 ESP32-S3。
在烧录和编译固件时,需要用到 idf.py 命令,但我本地一开始并没有这个命令。
查了一下,idf.py 并不是项目自带的工具,而是 ESP-IDF 开发环境的一部分。
ESP-IDF 是乐鑫官方提供的 ESP32 开发框架,负责项目配置、编译、烧录、串口监控等操作。
本文记录一下 macOS 上安装 ESP-IDF 的过程。
一、安装方式选择
乐鑫官方文档里推荐使用 Espressif Installation Manager,也就是 EIM 来安装 ESP-IDF。
EIM 的好处是:
- 自动安装 ESP-IDF
- 自动安装编译工具链
- 自动配置 Python 依赖
- 可以选择安装不同版本的 ESP-IDF
- 比纯手动安装更适合新手
官方文档地址:
我的项目 README 里要求 ESP-IDF 5.4 or above,所以这里我选择安装 v5.4.2。
二、安装前置依赖
macOS 上建议先安装 Homebrew。
如果已经安装过 Homebrew,可以直接执行:
bash
brew --version
能看到版本号就说明已经装好了。
然后安装 ESP-IDF 需要的一些依赖:
bash
brew install libgcrypt glib pixman sdl2 libslirp dfu-util cmake python
官方文档里提到,ESP-IDF 需要 Python 3.10 或以上版本。
检查 Python 版本:
bash
python3 --version
三、安装 EIM 工具
先添加 EIM 的 Homebrew 仓库:
bash
brew tap espressif/eim
如果想用图形界面安装,可以执行:
bash
brew install --cask eim-gui
如果想用命令行安装,可以执行:
bash
brew install eim
我个人更推荐新手使用图形界面,也就是 eim-gui,比较直观。

四、使用图形界面安装 ESP-IDF
安装完成后,打开 ESP-IDF Installation Manager 应用。

大致流程是:
- 点击
New Installation - 点击
Start Installation - 选择
Easy Installation或Custom Installation - 如果要指定版本,比如
v5.4.2,建议使用Custom Installation - 等待安装完成

安装过程中 EIM 会自动下载 ESP-IDF、工具链、Python 依赖等内容。
如果安装失败,可以点击界面里的 Logs 查看错误原因。
以下是关键步骤的选择


五、使用命令行安装指定版本
如果不想用图形界面,也可以直接用命令行安装。
安装最新版稳定版:
bash
eim install
安装指定版本,例如 v5.4.2:
bash
eim install -i v5.4.2
如果想进入交互式安装向导:
bash
eim wizard
安装完成后,终端里会提示 ESP-IDF 已经安装成功。
六、确认 idf.py 是否可用
安装完成后,新开一个终端,执行:
bash
idf.py --version
如果能看到类似下面的输出,说明安装成功:
bash
ESP-IDF v5.4.2
如果提示:
bash
idf.py: command not found
说明当前终端还没有加载 ESP-IDF 环境变量。
可以找到 ESP-IDF 的安装目录,然后执行:
bash
. ~/esp/esp-idf/export.sh
注意前面是一个点和空格:
bash
. ~/esp/esp-idf/export.sh
如果你是通过 EIM 安装的,ESP-IDF 路径可能不一定是 ~/esp/esp-idf,需要以你实际安装路径为准。
七、编译 ESP32-S3 项目
进入项目目录:
bash
cd /Users/chenxiangwen/Desktop/esp/my-esp32
我的开发板是 ESP32-S3,所以设置 target:
bash
idf.py set-target esp32s3
打开配置界面:
bash
idf.py menuconfig
在菜单里选择开发板类型:
text
Xiaozhi Assistant
-> Board Type
-> Bread Compact WiFi + LCD
保存并退出。
然后开始编译:
bash
idf.py build
第一次编译会比较慢,后面会快一些。
八、查看 Mac 是否识别到开发板
把 ESP32 开发板用 Type-C 数据线连接到 Mac。
注意:一定要用支持数据传输的数据线,不要用纯充电线。
查看串口:
bash
ls /dev/cu.*
正常情况下,插上开发板后会多出一个类似这样的设备:
bash
/dev/cu.usbmodem1101
/dev/cu.wchusbserialxxx
/dev/cu.SLAB_USBtoUART
这个就是烧录用的串口。
九、烧录固件
假设串口是:
bash
/dev/cu.usbmodem1101
执行:
bash
idf.py -p /dev/cu.usbmodem1101 flash monitor
这个命令会做两件事:
flash:烧录固件monitor:烧录完成后自动打开串口日志
如果烧录失败,提示连接不上,可以尝试:
- 按住开发板上的
BOOT键 - 执行烧录命令
- 看到开始写入后松开
BOOT键
十、常见问题
1. idf.py: command not found
说明 ESP-IDF 环境没有加载。
执行:
bash
. ~/esp/esp-idf/export.sh
如果路径不对,需要换成你实际的 ESP-IDF 安装路径。
2. 找不到串口
先执行:
bash
ls /dev/cu.*
如果只看到:
bash
/dev/cu.Bluetooth-Incoming-Port
说明 Mac 没识别到开发板。
可能原因:
- 数据线是纯充电线
- 板子没有插好
- USB 转串口驱动没装
- 板子没有进入下载模式
3. 烧录时一直连接失败
可以尝试按住 BOOT 键再烧录。
有些 ESP32-S3 开发板需要手动进入下载模式。
4. 项目板型选错
如果我的板子是 Bread Compact WiFi + LCD,就要在 menuconfig 里选择这个板型。
如果选错,可能会出现:
- 屏幕不亮
- 按键不对
- 麦克风没声音
- 喇叭没声音
- 程序启动异常
十一、总结
ESP32 开发环境的核心是 ESP-IDF,而 idf.py 是 ESP-IDF 提供的命令行工具。
安装流程可以简单理解为:
text
安装 Homebrew
-> 安装 EIM
-> 用 EIM 安装 ESP-IDF
-> 确认 idf.py 可用
-> 设置芯片 target
-> menuconfig 选择板型
-> build 编译
-> flash 烧录
-> monitor 查看日志
对我的 Bread Compact WiFi + LCD 开发板来说,关键命令是:
bash
cd /Users/chenxiangwen/Desktop/esp/my-esp32
idf.py set-target esp32s3
idf.py menuconfig
idf.py build
idf.py -p /dev/cu.xxx flash monitor
其中 /dev/cu.xxx 要换成自己电脑识别到的真实串口。