硬件教程Mac

在 macOS 上装 ESP-IDF v6.0.2:从 `brew install` 报错到 VSCode 认到 setup

命令行装 ESP-IDF 一切正常,VSCode 扩展却死活报 setup not found?这篇照着真实踩坑过程原样记录:从 Homebrew 装 eim、用 EIM 装 ESP-IDF v6.0.2、清理 Windows 搬来的工程残留,一路挖到 VSCode 扩展「找不到 setup」的真正根因——配置项作用域写错了地方。命令和报错都是实跑出来的,遇到同样报错可以直接复制去搜。

在 macOS 上装 ESP-IDF v6.0.2:从 `brew install` 报错到 VSCode 认到 setup

在 macOS 上装 ESP-IDF v6.0.2:从 brew install 报错到 VSCode 认到 setup

之前手动装过两次 ESP-IDF,两次都在某个环节卡住,最后干脆把整个过程重新走了一遍,把每个报错的根因都挖出来了。走完才发现,坑其实不在“装 ESP-IDF”这件事本身,而是分散在五个互不相关的地方:Homebrew 装工具、EIM 的网络访问、VSCode 里装对插件、项目里从 Windows 带过来的几个文件、VSCode 扩展读配置的方式。命令行装好之后一切正常,但 VSCode 扩展死活报 “setup not found”,这个问题排查起来最费时间,也是这篇文章的重点。

这篇是照着自己踩过的坑原样记录的,命令、报错信息都是实际跑出来的,遇到同样报错的话可以直接复制去搜索,或者把这篇文章连同你自己的报错一起丢给 AI,让它按这个思路帮你定位。

在开始之前,先核对一下版本号。 ESP-IDF 从 v5.x 到 v6.0.2,安装方式从传统的 install.sh 换成了 EIM;VSCode 扩展从 1.x 到 2.x,找 setup 的逻辑整个重写过。版本不一样,尤其是第 4 步关于扩展配置的部分,很可能完全不适用。

环境版本

项目 版本
系统 macOS,Apple Silicon(M 系列芯片)
ESP-IDF v6.0.2
安装工具 EIM 0.17.1
VSCode 扩展 espressif.esp-idf-extension 2.1.0
目标芯片 ESP32-S3

文中路径按我本机的用户名 shawn 写的,照抄命令时记得换成你自己的用户名(终端里输入 whoami 就能看到)。另外我本地开着 Clash 代理,走的是 127.0.0.1:7890,如果你不需要代理,把命令里带 PROXY 字样的环境变量和 --mirror 参数去掉就行,不影响主流程。

整体路线

五步走,越往后越隐蔽:

步骤 要做的事 常见状况
0 用 Homebrew 装 eim 这个工具本身 一个信任提示,容易被当成报错
1 用 eim 装 ESP-IDF v6.0.2 网络和版本号两个坑
2 在 VSCode 里装 ESP-IDF 扩展 插件同名的太多,很容易装错
3 清理项目里的 Windows 遗留文件 只有从 Windows 搬来的工程才会遇到
4 让 VSCode 扩展认到装好的 setup 全文最隐蔽的坑,卡人最久

第 0 步:先把 eim 这个工具装上

eim 全称 ESP-IDF Manager,是 Espressif 官方出的安装管理工具,比老的 install.sh 方便的地方在于可以装多个 ESP-IDF 版本,互不冲突。装它本身要先加一个 Homebrew 的 tap(第三方软件源),再装:

EIM官方安装指南: https://dl.espressif.com/dl/eim/index.html

brew tap espressif/eim
brew install eim

第一次跑 brew install eim 的时候,我遇到了这个提示:

Error: Refusing to load formula espressif/eim/eim from untrusted tap espressif/eim.
Run `brew trust --formula espressif/eim/eim` or `brew trust espressif/eim` to trust it.

这不是安装失败,是 Homebrew 的一道安全确认。 较新版本的 Homebrew 对第三方 tap(也就是不在官方仓库里的软件源)默认不直接信任,第一次用某个第三方 tap 里的东西,都会先弹这么一句,让你自己确认要不要信任它。espressif 这个 tap 是官方的,放心信任即可:

brew trust espressif/eim

跑完这句之后再执行一次 brew install eim 就能正常装上了。如果你在 brew install 之前先看到一大堆跟 eim 毫不相关的软件名单(比如什么菜单栏小工具、AI 改名工具之类的),那是 Homebrew 在列出“你现在有多少过期的包”之类的无关信息,不用管,往下翻到真正的报错行就行。

装完验证一下:

eim --version

能正常输出版本号就说明这一步过了,可以进入下一步正式装 ESP-IDF。


第 1 步:用 EIM 装 ESP-IDF v6.0.2

工具装好之后,一条命令装 ESP-IDF:

HTTPS_PROXY=http://127.0.0.1:7890 \
HTTP_PROXY=http://127.0.0.1:7890 \
ALL_PROXY=socks5://127.0.0.1:7890 \
eim install -i v6.0.2 -t esp32s3 -n true \
  --idf-mirror https://git.espressif.com.cn \
  --pypi-mirror https://pypi.mirrors.ustc.edu.cn/simple

各参数含义:

  • -i v6.0.2:要装的版本号,必须带 v 前缀,原因下面细说;
  • -t esp32s3:目标芯片;
  • -n true:非交互模式,不然会卡在终端问答里等你按回车;
  • --idf-mirror / --pypi-mirror:国内镜像,源码走 Espressif 官方的中国镜像,Python 包走中科大源,不需要可以去掉;
  • 三个 PROXY 环境变量:给 EIM 内部访问 git 用的,原因也是下面细说的坑 1。

这条命令看着简单,第一次跑的时候我踩了两个坑,都是那种“表面在正常安装,其实内部悄悄走了弯路”的类型。

坑 1:代理配在 git 里没用,EIM 不认

EIM 内部是用 Rust 的 gix 库去拉取 IDF 源码的,这个库不认 git config --global http.proxy 这种传统配置方式,只看 HTTPS_PROXY、HTTP_PROXY、ALL_PROXY 这几个系统环境变量。如果你的代理只配在 git 的配置文件里,没有对应的环境变量,gix 会尝试直连,拉取过程中反复失败,日志里会刷这种东西:

WARN - Attempt N failed: "Failed to fetch: Failed to consume the pack sent by the remote"

失败三次之后 gix 会自动退回去用系统自带的 git(系统 git 认 git config,能正常走代理),所以最后大概率还是能装上,但白白多等几分钟,而且这种“回退”出来的 clone 状态不算太干净。省事的办法就是一开始就把代理变量直接放进命令里,让 gix 一次走通,不用等它失败三次再回退。

坑 2:版本号不带 v 会报错

Espressif 官方仓库的 release tag 全都是 v6.0.2 这种带 v 的格式,EIM 的 -i 参数是直接拿去当 git tag 名用的。如果写成 -i 6.0.2(不带 v),会报:

fatal: Remote branch 6.0.2 not found in upstream origin

这个报错其实也是 gix 失败之后,系统 git 接手 fallback 时报的——git 在远端找不到一个叫 6.0.2(没有 v)的分支。写成 -i v6.0.2 就没问题了。如果不确定某个版本的 tag 到底怎么写,可以先查一下远端有哪些:

git ls-remote --tags https://git.espressif.com.cn/espressif/esp-idf.git 'v6.0*'

装完怎么验证

eim list
# 应该能看到 v6.0.2 (selected)

source ~/.espressif/tools/activate_idf_v6.0.2.sh
idf.py --version
# 输出 ESP-IDF v6.0.2 说明装好了

装完之后东西都在哪

EIM 装出来的目录结构和传统方式不太一样,后面所有配置都要引用这几个路径,先心里有个数:

IDF 源码       ~/.espressif/v6.0.2/esp-idf
工具链         ~/.espressif/tools/
Python venv    ~/.espressif/tools/python/v6.0.2/venv
激活脚本       ~/.espressif/tools/activate_idf_v6.0.2.sh
EIM 安装清单   ~/.espressif/tools/eim_idf.json

要特别提一下 Python 虚拟环境的位置,它藏在 tools/python/v6.0.2/venv 里,不是老版本里常见的项目根目录下的 python_env/,第一次找的时候很容易懵。


第 2 步:在 VSCode 里装 ESP-IDF 扩展

命令行这边装好之后,回到 VSCode,打开扩展面板(Cmd+Shift+X),搜索 “ESP-IDF”。

这一步很多人会装错,务必核对清楚发布者。 搜索结果里会出现好几个名字相似、图标也差不多的插件,光看名字很容易点错。核对下面这几个信息,确认是同一个再点安装:

字段 内容
插件名称 ESP-IDF
发布者 Espressif Systems
发布者主页 espressif.com
安装量 1,582,039
评分 145 条评价
简介 Develop and debug applications for Espressif chips with ESP-IDF

认插件认发布者,不要只认名字。 发布者一栏必须是 Espressif Systems,域名是 espressif.com,安装量在百万级别——这几个是这款官方插件比较明显的特征。装错插件的话,后面第 4 步讲的那些配置项(idf.eimIdfJsonPath、idf.currentSetup 等)可能根本不存在,或者行为完全对不上,排查起来会很莫名其妙,本质原因其实是一开始就装错了插件。

装好之后,重启一下 VSCode(或者 Cmd+Shift+P → Reload Window),让插件生效,再往下走。


第 3 步:项目是从 Windows 搬过来的,先清三个文件

如果你的项目是全新建的,这一步可以直接跳过。 但如果是从 Windows 电脑拷过来的工程,几乎一定会踩这一节的坑——有三个文件里藏着 Windows 专属的路径,拷到 macOS 上直接失效。

① .vscode/settings.json

把里面 C:\... 这种 Windows 路径、串口名(比如 COM22)、旧版本号,全部换成 macOS 这边的实际值:

{
  "idf.espIdfPath": "/Users/shawn/.espressif/v6.0.2/esp-idf",
  "idf.toolsPath":  "/Users/shawn/.espressif",
  "idf.pythonInstallPath": "/Users/shawn/.espressif/tools/python/v6.0.2/venv/bin/python",
  "idf.port": "/dev/cu.usbmodemXXXXXXXXXXX",
  "idf.customExtraVars": { "IDF_TARGET": "esp32s3" },
  "idf.flashType": "UART"
}

自己的串口设备名用这条命令查:

ls /dev/cu.usb*

② .vscode/c_cpp_properties.json

compilerPath 里原来指向的是 Windows 版的 xtensa-esp32s3-elf-gcc.exe,而且工具链版本号大概率也是旧的,要换成 Mac 上实际装的那个版本。建议别把路径写死,跟着 toolsPath 这个变量走,以后升级也不用改:

"compilerPath": "${config:idf.toolsPath}/tools/xtensa-esp-elf/esp-15.2.0_20251204/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gcc"

esp-15.2.0_20251204 这段版本号不是随便抄的,要去 ~/.espressif/tools/xtensa-esp-elf/ 目录下看看实际装的是哪个文件夹,照实际的填。

③ dependencies.lock —— 最容易漏掉的一个

这是 idf-component-manager(组件管理器)生成的锁文件,Windows 上生成的是旧的 v2.0.0 格式,里面会把本地 component 的绝对路径也记进去,比如原作者电脑上的目录:

espressif/esp_lcd_touch:
  source:
    path: C:\Users\PC\Desktop\...\espressif__esp_lcd_touch
    type: local

到 mac 上跑 reconfigure 的时候这个路径当然不存在,会报:

CMake Error: The "path" field in the manifest file ... does not point to a directory.

这个文件本质是自动生成的缓存文件,删掉让它自己重建最省事:

rm dependencies.lock
rm -rf build
source ~/.espressif/tools/activate_idf_v6.0.2.sh
idf.py reconfigure

重新生成后会变成 v3.0.0 格式,路径变成本地化的,registry 里的组件会重新下载到 managed_components/ 目录下。

到这一步,命令行的 idf.py build 应该已经能正常跑起来了。 如果还跑不过,说明问题不在这几个文件里,得往别的地方查。


第 4 步:VSCode 扩展说 “setup not found”(真正卡人的地方)

命令行一切正常之后,我以为大功告成,结果打开 VSCode,状态栏一直显示这句话:

Current ESP-IDF setup is not found.

Reload 了两次窗口,改了几个看起来相关的配置项,都没用。后来把扩展的源码文件(dist/extension.js)翻出来看了一下,才搞明白它找 setup 的完整逻辑:

  1. 从 idf.eimIdfJsonPath 指向的 eim_idf.json 文件里,读出一份已安装的 setup 列表;
  2. 拿 idf.currentSetup 的值去这份列表里按路径匹配;
  3. 匹配不到就把列表挨个遍历一遍,看有没有能验证通过的;
  4. 全部失败,才报那句 “not found”。

这套逻辑能成立的前提是第 1 步那份列表得先加载出来。我走了两条弯路才找到根因,第一条其实是白折腾、不用照做,第二条才是真正要动手改的地方,先说明白,免得跟着文章操作的时候拿不准该不该动:

  • 弯路一:不需要操作,看看原理就好,跳过即可;
  • 弯路二:需要操作,这才是真正的修复步骤。

弯路一(不用管,了解一下即可):idf.currentSetup 到底该填什么

这个配置项官方描述写的是“Current ESP-IDF setup id in eim_idf.json path”,字面上看像是要填一个 ID(编号)。但翻源码,扩展自己选中某个 setup 之后,实际写进去的其实是这样:

await _o("idf.currentSetup", c.idfPath, ConfigurationTarget.WorkspaceFolder, e)

写进去的是 idfPath,也就是一段路径,不是编号。所以如果这一项自己出现在工作区配置里,应该长这样:

"idf.currentSetup": "/Users/shawn/.espressif/v6.0.2/esp-idf"

但这一项不需要你手动去改——它不是根因。只要下面弯路二那份 setup 列表能正常加载出来,扩展会自己遍历找到唯一装着的 v6.0.2,然后把路径自动回写进 currentSetup,这一步是扩展自己完成的。这里放出来纯粹是解释原理,方便你看到这个字段时知道它是干什么用的,不用因为它“看起来不对”就去手动修改。真正要动手修的是下面这条。

弯路二(真正要操作的地方):idf.eimIdfJsonPath 的作用域不对

VSCode 的配置项分好几种作用域(scope),idf.eimIdfJsonPath 这一项的作用域是 application——意味着它只在全局的 User settings.json 里生效,写在项目自己的 .vscode/settings.json 里是完全不会被读取的,写了也是白写。

我之前一直把 eimIdfJsonPath 写在项目的工作区配置里,导致扩展根本加载不到 eim_idf.json 这个文件,第 1 步说的那份 setup 列表永远是空的——空列表意味着不管 currentSetup 怎么填都匹配不上,这才是前两次 Reload 都不见效的真正原因。

修复方法:把 idf.eimIdfJsonPath 挪到全局配置文件里。

macOS 上 VSCode 的全局配置文件路径是:

~/Library/Application Support/Code/User/settings.json

用编辑器打开这个文件,加入这一行:

"idf.eimIdfJsonPath": "/Users/shawn/.espressif/tools/eim_idf.json"

工作区的 .vscode/settings.json 里只留 idf.currentSetup(填成 idf 的路径),千万别把 eimIdfJsonPath 也放在工作区里——放了也不生效,白白让人误以为已经配置对了。

改完之后,Cmd+Shift+P 打开命令面板,选 Reload Window。重新加载完,状态栏能正常显示 ESP-IDF 版本号和目标芯片,就说明扩展终于认到了。

如果 Reload 之后还有问题,可以看扩展自己的实时日志:Cmd+Shift+P → Output,在输出面板右上角的下拉菜单里选 ESP-IDF 这个通道,报错信息会比状态栏那一句话详细得多。

不确定某个配置项的作用域?直接查,不用猜

VSCode 扩展的作用域信息都写在它自己的 package.json 里,与其猜,不如写几行脚本直接查:

python3 -c "
import json
p = json.load(open('/Users/shawn/.vscode/extensions/espressif.esp-idf-extension-2.1.0/package.json'))
cfg = p['contributes']['configuration']
props = {}
if isinstance(cfg, list):
    for c in cfg:
        props.update(c.get('properties', {}))
else:
    props = cfg.get('properties', {})
for k in ['idf.eimIdfJsonPath', 'idf.currentSetup', 'idf.espIdfPath']:
    print(k, '->', props.get(k, {}).get('scope', 'window(默认)'))
"

速查表

配置项该写在哪

配置项 作用域(scope) 该写在哪
idf.eimIdfJsonPath application 全局 User settings
idf.currentSetup resource 工作区 .vscode/settings.json
idf.espIdfPath / idf.toolsPath / idf.pythonInstallPath window 工作区或全局都可以

关键路径

IDF 源码       ~/.espressif/v6.0.2/esp-idf
工具链         ~/.espressif/tools/
xtensa gcc     ~/.espressif/tools/xtensa-esp-elf/esp-15.2.0_20251204/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gcc
Python venv    ~/.espressif/tools/python/v6.0.2/venv/bin/python
激活脚本       source ~/.espressif/tools/activate_idf_v6.0.2.sh
EIM 安装清单   ~/.espressif/tools/eim_idf.json
全局 settings  ~/Library/Application Support/Code/User/settings.json

常用命令

brew tap espressif/eim                              # 添加官方 tap
brew trust espressif/eim                             # 首次使用第三方 tap 需要信任
brew install eim                                     # 安装 eim 本身

eim list                                              # 查看已装版本
eim install -i v6.0.2 -t esp32s3 -n true ...          # 安装 ESP-IDF(参数见第 1 步)

source ~/.espressif/tools/activate_idf_v6.0.2.sh      # 激活当前 shell 的 ESP-IDF 环境
idf.py set-target esp32s3                             # 设定目标芯片
idf.py reconfigure                                    # 只跑 cmake 配置,生成 compile_commands.json
idf.py build                                          # 编译
idf.py -p /dev/cu.usbmodemXXXX flash monitor          # 烧录并打开串口监视

排查顺序:卡住了先按这个缩小范围

不知道从哪下手的话,按这个顺序一层层排除,比瞎试快得多:

  1. brew install eim 能不能装上? 装不上,看提示是不是要求 brew trust —— 是的话直接信任即可,见第 0 步;
  2. idf.py --version 能不能跑? 跑不了 → 问题在安装或激活这一层,见第 1 步;
  3. VSCode 扩展面板里搜出来的东西对不对? 装完发现配置项对不上、或者插件功能跟这篇文章描述的完全不一样 → 先确认发布者是不是 Espressif Systems,很可能一开始就装错了插件,见第 2 步;
  4. idf.py reconfigure 能不能跑通? 跑不通 → 问题在项目文件,重点查 dependencies.lock,见第 3 步;
  5. 命令行都正常,VSCode 却报 setup not found? → 问题在扩展配置,重点查 eimIdfJsonPath 的作用域,见第 4 步。

两个容易走偏的方向提前说一下,省得白折腾:

  • v6.0.2 这个 tag 本身就没有附带 version.txt 文件,这不是 clone 漏了文件,扩展本来也不读这个文件,看到缺失不用慌;
  • idf.currentSetup 的值基本不是 setup not found 的根因,遇到这个报错先别急着改它,优先确认 eimIdfJsonPath 是不是写在了全局 settings 而不是工作区配置里。

如果照着走完还是卡住,八成是版本对不上——ESP-IDF 的安装方式、VSCode 扩展找 setup 的逻辑,这几年变了不止一轮,老教程未必适用于新版本。建议把你本地实际的 ESP-IDF 版本、EIM 版本、扩展版本,连同具体的报错信息,一起丢给 AI,对照这篇文章“装工具 → 装 IDF → 清项目文件 → 配扩展”这四步的思路去排查,通常比直接搜报错关键词更快定位到底是哪一层出的问题。