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

网罗开发

于 2025-04-04 22:01:55 发布

阅读量1.9k

点赞数 17

分类专栏：嵌入式文章标签： macos 物联网嵌入式硬件

本文链接：https://blog.youkuaiyun.com/qq_36478920/article/details/147003520

版权

嵌入式专栏收录该内容

6 篇文章

订阅专栏

在这里插入图片描述

网罗开发 （小红书、快手、视频号同名）

大家好，我是展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。

图书作者：《ESP32-C3 物联网工程开发实战》
图书作者：《SwiftUI 入门，进阶与实战》
超级个体：COC上海社区主理人
特约讲师：大学讲师，谷歌亚马逊分享嘉宾
科技博主：华为HDE/HDG

我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。

展菲：您的前沿技术领航员
👋 大家好，我是展菲！
📱 全网搜索“展菲”，即可纵览我在各大平台的知识足迹。
📣 公众号“Swift社区”，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。
💬 微信端添加好友“fzhanfei”，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。
📅 最新动态：2025 年 3 月 17 日
快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！

文章目录

前言

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

第一步：安装准备

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

macOS 用户准备工作

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

1. 安装 CMake 和 Ninja 编译工具

如果你已经安装了 Homebrew（Mac 的包管理工具），那就简单了，直接运行下面的命令：

brew install cmake ninja dfu-util

如果你使用的是 MacPorts，可以运行：

sudo port install cmake ninja dfu-util

如下图：

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

2. 安装 ccache

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

如果你用的是 Homebrew：

brew install ccache

或者用 MacPorts：

sudo port install ccache

如下图：

3. 安装 Xcode 命令行工具

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

xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun

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

xcode-select --install

4. Apple M1 芯片的特殊问题

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

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.

或者：

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，只需运行以下命令：

/usr/sbin/softwareupdate --install-rosetta --agree-to-license

第二步：获取 ESP-IDF

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

打开终端，切换到你希望保存 ESP-IDF 的文件夹。
使用 Git 克隆代码库：

git clone --recursive https://github.com/espressif/esp-idf.git ~/esp/esp-idf

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

第三步：安装工具

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

cd ~/esp/esp-idf

运行安装脚本来安装工具：

./install.sh all

如果你使用的是 Fish shell，命令稍有不同：

./install.fish all

如下图：

注意事项

如果你在运行过程中遇到以下错误：

<urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:xxx)

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

第四步：配置环境变量

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

source ~/esp/esp-idf/export.sh

如果是用 Fish shell，则需要用：

source ~/esp/esp-idf/export.fish

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

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

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

常见问题及解决方法

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

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

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 虚拟环境没有创建好。你可以通过以下命令重新安装依赖：

$HOME/esp/esp-idf/install.sh

然后重新配置环境变量：

source $HOME/esp/esp-idf/export.sh

问题 2：权限问题

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

zsh: permission denied: /Users/xxx/esp/esp-idf/export.sh

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

chmod +x $HOME/esp/esp-idf/export.sh

然后再运行：

source $HOME/esp/esp-idf/export.sh

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

source $HOME/esp/esp-idf/export.sh

问题 3：Python 版本兼容问题

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

brew install python@3.11

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

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 的安装脚本：

$HOME/esp/esp-idf/install.sh

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

rm -rf ~/.espressif/python_env/
$HOME/esp/esp-idf/install.sh

问题 4：环境变量未加载

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

source $HOME/esp/esp-idf/export.sh

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

idf.py --version

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

小结

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