轻松搞定!Mac 用户的 ESP-IDF 安装全攻略

前言

大家好,今天来聊聊如何在 Mac 上安装 ESP-IDF,特别是对于 M1 芯片的用户,安装过程可能会有一些小坑,但是跟着这个步骤来,问题应该不大。我们分成几个步骤,逐步来解决。

第一步:安装准备

首先,如果你要在 ESP32 上使用 ESP-IDF,得先准备一些软件包。根据你的操作系统不同,安装的方式也会有些差异。我们这里主要讲讲 Mac 的安装过程。

macOS 用户准备工作

ESP-IDF 会使用 macOS 默认的 Python 版本,所以不用额外安装 Python。但你需要确保几个编译工具已经安装了。

1. 安装 CMake 和 Ninja 编译工具

如果你已经安装了 Homebrew(Mac 的包管理工具),那就简单了,直接运行下面的命令:

bash 复制代码
brew install cmake ninja dfu-util

如果你使用的是 MacPorts,可以运行:

bash 复制代码
sudo port install cmake ninja dfu-util

如下图:

如果你没有这些工具,可以直接去官网手动下载和安装 CMake 和 Ninja。

2. 安装 ccache

为了加速编译过程,建议安装 ccache,它能缓存编译结果,避免每次都重新编译。你可以通过以下方式安装:

  • 如果你用的是 Homebrew
bash 复制代码
brew install ccache
  • 或者用 MacPorts
bash 复制代码
sudo port install ccache

如下图:

3. 安装 Xcode 命令行工具

有时候你可能会遇到这样的错误:

bash 复制代码
xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun

这个问题是因为 Xcode 的命令行工具没装好。只需要运行以下命令来安装:

bash 复制代码
xcode-select --install

4. Apple M1 芯片的特殊问题

如果你用的是 Apple M1 芯片,有时可能会遇到这个错误:

vbnet 复制代码
WARNING: directory for tool xtensa-esp32-elf version esp-2021r2-patch3-8.4.0 is present, but tool was not found
ERROR: tool xtensa-esp32-elf has no installed versions. Please run 'install.sh' to install it.

或者:

bash 复制代码
zsh: bad CPU type in executable: ~/.espressif/tools/xtensa-esp32-elf/esp-2021r2-patch3-8.4.0/xtensa-esp32-elf/bin/xtensa-esp32-elf-gcc

这时需要安装 Rosetta 2,只需运行以下命令:

bash 复制代码
/usr/sbin/softwareupdate --install-rosetta --agree-to-license

第二步:获取 ESP-IDF

ESP-IDF 是乐鑫提供的开发框架,你需要先获取它的代码库。

  1. 打开终端,切换到你希望保存 ESP-IDF 的文件夹。
  2. 使用 Git 克隆代码库:
bash 复制代码
git clone --recursive https://github.com/espressif/esp-idf.git ~/esp/esp-idf

这会把 ESP-IDF 下载到你的用户目录下的 ~/esp/esp-idf 文件夹。

第三步:安装工具

获取 ESP-IDF 后,还需要安装一些工具,比如编译器和调试工具。这一步可以一次性安装所有需要的工具。

  1. 切换到 ESP-IDF 目录:
bash 复制代码
cd ~/esp/esp-idf
  1. 运行安装脚本来安装工具:
bash 复制代码
./install.sh all

如果你使用的是 Fish shell,命令稍有不同:

bash 复制代码
./install.fish all

如下图:

注意事项

  • 如果你在运行过程中遇到以下错误:
bash 复制代码
<urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:xxx)

你需要在终端运行 Install Certificates.command 来安装缺失的证书。

第四步:配置环境变量

完成工具安装后,接下来要配置环境变量。通过运行以下命令:

bash 复制代码
source ~/esp/esp-idf/export.sh

如果是用 Fish shell,则需要用:

bash 复制代码
source ~/esp/esp-idf/export.fish

出现如下图就代表配置完成了

这一步完成后,你的开发环境就配置好了,接下来就可以开始使用 ESP-IDF 来开发应用了。

下面是我在配置过程中遇到的问题和解决方案。

常见问题及解决方法

问题 1:Python 虚拟环境找不到

如果你遇到类似这样的错误:

arduino 复制代码
ERROR: ESP-IDF Python virtual environment "/Users/xxx/.espressif/python_env/idf5.5_py3.13_env/bin/python" not found. Please run the install script to set it up before proceeding.

这表明 ESP-IDF 的 Python 虚拟环境没有创建好。你可以通过以下命令重新安装依赖:

bash 复制代码
$HOME/esp/esp-idf/install.sh

然后重新配置环境变量:

bash 复制代码
source $HOME/esp/esp-idf/export.sh

问题 2:权限问题

如果你遇到权限问题,比如运行 export.sh 时出现:

bash 复制代码
zsh: permission denied: /Users/xxx/esp/esp-idf/export.sh

你可以用以下命令给 export.sh 文件加上执行权限:

bash 复制代码
chmod +x $HOME/esp/esp-idf/export.sh

然后再运行:

bash 复制代码
source $HOME/esp/esp-idf/export.sh

或者,你也可以直接用 source 来执行这个脚本,这样就不需要修改权限了:

bash 复制代码
source $HOME/esp/esp-idf/export.sh

问题 3:Python 版本兼容问题

如果你使用的是 Python 3.13 以上的版本,ESP-IDF 可能会报错,因为当前版本可能不兼容。解决方法是降级 Python 版本,比如安装 Python 3.11:

bash 复制代码
brew install python@3.11

然后你需要指定 ESP-IDF 使用的 Python 版本。运行以下命令来切换到 Python 3.11:

bash 复制代码
export PATH="/opt/homebrew/opt/python@3.11/bin:$PATH"
python3 -m venv ~/esp/esp-idf-python-env
source ~/esp/esp-idf-python-env/bin/activate

重新运行 ESP-IDF 的安装脚本:

bash 复制代码
$HOME/esp/esp-idf/install.sh

如果问题仍然存在,可以删除原有的虚拟环境并重新安装依赖:

bash 复制代码
rm -rf ~/.espressif/python_env/
$HOME/esp/esp-idf/install.sh

问题 4:环境变量未加载

有时即使设置了环境变量,还是会出现类似 "command not found" 的问题。这时可以通过 source 再次加载 export.sh

bash 复制代码
source $HOME/esp/esp-idf/export.sh

如果一切正常,接下来可以通过以下命令确认 ESP-IDF 的版本:

bash 复制代码
idf.py --version

如果你能看到版本信息,说明 ESP-IDF 安装和配置成功,接下来就可以开始愉快的开发了。

小结

安装 ESP-IDF 在 macOS 上的过程其实并不复杂,但确实会遇到一些小问题,特别是在 M1 芯片和 Python 版本上。只要按照这个步骤逐步排查,相信你会顺利安装并开始开发。遇到问题时,记得检查一下工具和环境配置,特别是 Python 版本和虚拟环境的配置问题。希望这篇文章对你有帮助,祝你开发愉快!

相关推荐
蓝婷儿9 分钟前
Python 机器学习核心入门与实战进阶 Day 2 - KNN(K-近邻算法)分类实战与调参
python·机器学习·近邻算法
之歆1 小时前
Python-封装和解构-set及操作-字典及操作-解析式生成器-内建函数迭代器-学习笔记
笔记·python·学习
天天爱吃肉82182 小时前
ZigBee通信技术全解析:从协议栈到底层实现,全方位解读物联网核心无线技术
python·嵌入式硬件·物联网·servlet
Allen_LVyingbo2 小时前
Python常用医疗AI库以及案例解析(2025年版、上)
开发语言·人工智能·python·学习·健康医疗
智能砖头2 小时前
LangChain 与 LlamaIndex 深度对比与选型指南
人工智能·python
糖果罐子♡3 小时前
MQTT 入门指南(一)
物联网·mqtt·嵌入式·通信协议
风逸hhh4 小时前
python打卡day58@浙大疏锦行
开发语言·python
烛阴4 小时前
一文搞懂 Python 闭包:让你的代码瞬间“高级”起来!
前端·python
JosieBook5 小时前
【Java编程动手学】Java中的数组与集合
java·开发语言·python
Gyoku Mint6 小时前
深度学习×第4卷:Pytorch实战——她第一次用张量去拟合你的轨迹
人工智能·pytorch·python·深度学习·神经网络·算法·聚类