在 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
之前手动装过两次 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 的完整逻辑:
- 从
idf.eimIdfJsonPath指向的eim_idf.json文件里,读出一份已安装的 setup 列表; - 拿
idf.currentSetup的值去这份列表里按路径匹配; - 匹配不到就把列表挨个遍历一遍,看有没有能验证通过的;
- 全部失败,才报那句 “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 # 烧录并打开串口监视
排查顺序:卡住了先按这个缩小范围
不知道从哪下手的话,按这个顺序一层层排除,比瞎试快得多:
brew install eim能不能装上? 装不上,看提示是不是要求brew trust—— 是的话直接信任即可,见第 0 步;idf.py --version能不能跑? 跑不了 → 问题在安装或激活这一层,见第 1 步;- VSCode 扩展面板里搜出来的东西对不对? 装完发现配置项对不上、或者插件功能跟这篇文章描述的完全不一样 → 先确认发布者是不是 Espressif Systems,很可能一开始就装错了插件,见第 2 步;
idf.py reconfigure能不能跑通? 跑不通 → 问题在项目文件,重点查dependencies.lock,见第 3 步;- 命令行都正常,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 → 清项目文件 → 配扩展”这四步的思路去排查,通常比直接搜报错关键词更快定位到底是哪一层出的问题。
