在 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:非互動模式,不然會卡在終端機問答裡等你按 Enter;--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 → 清專案檔案 → 設定擴充功能」這四步的思路去排查,通常比直接搜報錯關鍵字更快定位到底是哪一層出的問題。
