Mac 安装 ESP-IDF 开发环境,并使用 idf.py 烧录 ESP32 项目

2026-07-11嵌入式4 分钟121 次阅读
AI 摘要salmon-ai

本文详细解析了在 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 应用。

大致流程是:

  1. 点击 New Installation
  2. 点击 Start Installation
  3. 选择 Easy Installation 或 Custom Installation
  4. 如果要指定版本,比如 v5.4.2,建议使用 Custom Installation
  5. 等待安装完成

安装过程中 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:烧录完成后自动打开串口日志

如果烧录失败,提示连接不上,可以尝试:

  1. 按住开发板上的 BOOT 键
  2. 执行烧录命令
  3. 看到开始写入后松开 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 要换成自己电脑识别到的真实串口。

觉得有用就点个赞,不用登录也能读

评论

0 条
登录 之后才能评论
—
还没有评论,来说第一句