Arduino IDE 的 ESP32 开发板总是装不上？用 Arduino CLI + 国内镜像一招解决（macOS 实战）

2025年11月20日 lingshun

大多情况下，MacOS 系统使用 Arduino IDE 安装ESP32 开发板库的时候，可能都会遇到一下这个情况：

Downloading packages 
arduino:dfu-util@0.11.0-arduino5 
esp32:esp-rv32@2507 
Failed to install platform: 'esp32:esp32:3.3.2'. 
Error: 2 UNKNOWN: stream error: stream ID 1; PROTOCOL_ERROR; received from peer

应该是网络原因，外网的访问可能收到限制。

之后，我尝试使用乐鑫的文档的说 https://docs.espressif.com/projects/arduino-esp32/en/latest/installing.html

在Arduino IDE 添加了国内镜像的地址：

<https://jihulab.com/esp-mirror/espressif/arduino-esp32.git>

但最后还是，收到类似的错误信息：

Downloading packages
arduino:dfu-util@0.11.0-arduino5
esp32:esp-rv32@2507
Failed to install platform: 'esp32:esp32:3.3.2'.
Error: 4 DEADLINE_EXCEEDED: Get "<https://github.com/espressif/crosstool-NG/releases/download/esp-14.2.0_20250730/riscv32-esp-elf-14.2.0_20250730-aarch64-apple-darwin.tar.gz>": dial tcp 20.205.243.166:443: i/o timeout

看样子还是未能解决外网访问问题。

之后，我的解决办法是

使用用 Arduino CLI 进行ESP32开发板的安装

在MacOS打开终端（terminal），依次输入命令

1，MacOS安装Arduino CLI

brew install arduino-cli

使用Homebrew进行安装的，如果你的MacOS还未安装，则可以访问以下网址进行安装：

https://brew.sh/

2，初始化 Arduino CLI 的配置文件。

arduino-cli config init

这命令将会在你的用户目录下新建（或补全）~/.arduinoIDE/arduino-cli.yaml，并写入默认目录设置（例如数据目录对应 ~/Library/Arduino15 等）。这一步相当于“把 CLI 准备好”。

3，板管理器的额外索引地址（additional_urls）设置为乐鑫在 Jihulab 的中国镜像索引

arduino-cli config set board_manager.additional_urls \\
  <https://jihulab.com/esp-mirror/espressif/arduino-esp32/-/raw/gh-pages/package_esp32_index_cn.json>

Arduino CLI/IDE 安装“核心（core）/工具链”时，会去读这些 JSON 索引文件；换成这条 URL，就让 esp32 的所有依赖包尽量从国内镜像下载，避免 GitHub 超时。

4，更新索引

arduino-cli core update-index

从官方默认索引 + 你在 additional_urls 里配置的镜像索引。让 CLI 知道有哪些可安装的核心版本（比如 esp32:esp32@3.3.2-cn），以及它们的依赖包下载地址。改了镜像之后必须跑一次这步，后面的安装才能按新索引生效。

5，安装 ESP32 的核心（core)

arduino-cli core install esp32:esp32@3.3.2-cn

CLI 会按刚更新的索引解析依赖，下载并解压所需工具链，@3.3.2-cn 指定安装 带 -cn 后缀的镜像版核心（它的依赖也指向国内镜像）。

提示：如果不写 @版本，会装索引中标记的“最新稳定版”；这里强调 cn 是为了确保走国内镜像、提高成功率。

下图是运行以上命令，终端大概的样子：

执行完以上操作，并且没有报错的时候，则可以打开Arduino IDE ，这时候可以看到已经是安装了ESP32核心板

常见问题

Arduino-CLI 配置代理

有时候仍然是网络有问题，非常慢，而你又有代理可以使用，那么这个时候就可以进行arduino-cli的代理配置，命令如下：

arduino-cli config set network.proxy http://127.0.0.1:7890 #请根据你的代理服务进行修改端口

这样相信能提升不少速度，再也不怕遇到github的依赖包了。

列出当前 CLI 已知的所有开发板

arduino-cli board listall 这个命令可以用来列出当前 CLI 已知的所有开发板，含每块板对应的 FQBN（Fully Qualified Board Name，编译/上传时用的“板子 ID”）以及所属核心（如 rp2040:rp2040、esp32:esp32）。这些“已知板子”来自你已安装的核心和已加载的 Boards Manager 索引（取决于你有没有跑过 core update-index 以及是否添加了 additional_urls）。