ARTICLE · 1149728

Arduino 装 ESP32 老是下载失败?乐鑫官方给过一份国内源

发布时间：2026-10-10 10:09:00 最近访问：2026-10-10 10:09:00

新电脑装好 Arduino IDE，在开发板管理器里搜 esp32 点安装。进度条走着走着停在半路，过一阵提示下载失败；点重试，换了个包接着失败。

想拿它给 ESP32 验证个想法，第一步就卡在这根进度条上。

开发板管理器里那个 esp32，背后是乐鑫官方的开源仓库 arduino-esp32，最新稳定版 3.3.12。为什么老装不上、官方国内源怎么用、2.x 升 3.x 哪些代码会报错、什么时候别用它，这篇按顺序讲。

装不上的根：点一次安装要拉 1.9 GB

开发板管理器照着一份索引文件办事。首选项里填的那个地址指向 package_esp32_index.json，里面列着每个版本的核心包和它依赖的工具，照单逐个下载。

3.3.12 这一版列了 18 个工具依赖：Xtensa 和 RISC-V 两个编译器、两个 GDB、OpenOCD、esptool、mkspiffs、mklittlefs、dfu-util，再加 9 个按芯片分的库包。64 位 Windows 上，核心包加其中 17 个一共 18 个文件，约 1.9 GB；dfu-util 走 Arduino 官方的索引，没算在内。

最大的两个是编译器，Xtensa 约 395 MB，RISC-V 约 673 MB，核心包本身只有约 49 MB。默认索引里 1,215 个工具地址，有 1,195 个在 github.com。9 个库包都写在依赖清单里，手上只有一块 ESP32-C3，另外 8 个也照下，每个 44 到 97 MB。

官方国内源：换一份带 _cn 的索引

乐鑫的安装文档里有一段是写给中国用户的：用上面的链接可能遇到连接和速度问题，请改用 Jihulab 镜像。这份带 _cn 的索引，把 1,215 个工具地址和 52 个核心包地址全换到了 dl.espressif.cn，版本号后面多了 -cn。文档还提了两条：必须选带 -cn 后缀的版本；自动更新不支持，它会去找不带 -cn 的默认包，更新要手动做。

https://jihulab.com/esp-mirror/espressif/arduino-esp32/-/raw/gh-pages/package_esp32_index_cn.json

2026 年 10 月 8 日把这几处逐个请求了一遍。Jihulab 上的 _cn 索引停在 3.3.10-cn，镜像仓库最后一次提交是 2026-06-21。GitHub Pages 上还有一份同名的索引（https://espressif.github.io/arduino-esp32/package_esp32_index_cn.json），列到了 3.3.12-cn。可按索引里的地址去 dl.espressif.cn 取文件，3.3.11 和 3.3.10 的核心包、库包都在，3.3.12 的返回 404，编译器的包能取到。

所以选 3.3.12-cn 装不上时，退到 3.3.11-cn 或 3.3.10-cn。这是当天请求到的结果，以后可能变。

项目台账：乐鑫官方仓库，稳定支持八个系列

仓库 github.com/espressif/arduino-esp32，在乐鑫的 GitHub 组织下，文档写明由 Espressif Systems 和社区共同支持。
2016-10-06 建仓，贡献者约 444 人，17,492 个 Star，许可证 LGPL-2.1。
最新稳定版 3.3.12，2026-09-18 发布，基于 ESP-IDF v5.5.5；预发布版 4.0.0-RC1，2026-09-23 发布，基于 ESP-IDF v6.1。
稳定支持 ESP32、C3、C5、C6、H2、P4、S2、S3 共 8 个系列。
3.3.12 的 boards.txt 里有 409 个板卡条目，自带 44 个库。（2026-10 核验）

上手：三步装好，再跑个呼吸灯

Arduino IDE 要 1.8 或更新。打开首选项，把索引地址填进「附加开发板管理器网址」，多个地址用逗号隔开。
开发板管理器里搜 esp32 并安装，用国内源就选带 -cn 的版本。
装完在工具 > 开发板里选自己的板子，重启 IDE。上传时有的板子要按住 BOOT 键。

constint LED = 2;                // LED 接在哪个脚就改哪个voidsetup(){   ledcAttach(LED, 5000, 8);       // 引脚, 5 kHz, 8 位分辨率 }  voidloop(){   for (int d = 0; d <= 255; d++) { ledcWrite(LED, d); delay(5); }   for (int d = 255; d >= 0; d--) { ledcWrite(LED, d); delay(5); } }

这是 3.x 的写法，ledcAttach 是 3.0 新加的函数。

老代码编译不过：底层换到了 IDF 5.1

3.0.0 是 2024-05-27 发布的。官方迁移指南开头就交代：2.x 基于 ESP-IDF 4.4，3.0 基于 ESP-IDF 5.1，API 和构建系统里有一批破坏性变更，3.0.0 之前的老示例在新版上不兼容。

先看 LEDC。ledcSetup 和 ledcAttachPin 删了，合并成一个 ledcAttach；所有函数里的通道号参数换成引脚号，通道由库自己分配。

// 2.x：先配通道，再把引脚挂到通道上ledcSetup(0, 5000, 8); ledcAttachPin(LED, 0); ledcWrite(0, duty);  // 3.x：一步到位，参数从通道号换成引脚号ledcAttach(LED, 5000, 8); ledcWrite(LED, duty);

定时器也一样：timerBegin 只剩频率一个参数，分频由库自己算；timerAttachInterrupt 去掉了 edge 参数；timerAlarmDisable 等一批函数被删。

// 2.x timer = timerBegin(0, 80, true); timerAttachInterrupt(timer, &onTimer, true); timerAlarmWrite(timer, 1000000, true); timerAlarmEnable(timer);  // 3.x：timerBegin 直接给频率，写入和使能合成 timerAlarm timer = timerBegin(1000000); timerAttachInterrupt(timer, &onTimer); timerAlarm(timer, 1000000, true, 0);

其余的改动里，霍尔传感器不再支持，hallRead 被删；I2S 驱动整个重写；WiFiClient 和 WiFiUDP 的 flush() 不再清接收缓冲区，要清得用新加的 clear()。

还有一处不会报编译错误：UART 的默认引脚变了。ESP32 的 UART1 改成 RX=GPIO26、TX=GPIO27，UART2 改成 RX=GPIO4、TX=GPIO25；ESP32-S2 的 UART1 改成 RX=GPIO4、TX=GPIO5。

和 ESP-IDF 比：它是包在外面的一层

arduino-esp32 就是包在 ESP-IDF 外面的一层 Arduino API。装开发板包时下的那 9 个芯片库包，是预编译好的 ESP-IDF 静态库。所以 Arduino IDE 里没有 menuconfig；官方 FAQ 还提醒，直接去改目录里的 sdkconfig 或 sdkconfig.h 也不会生效。

要动这些配置，文档给进阶用户推荐的路是把 Arduino 当成 ESP-IDF 的一个组件，组件名 espressif/arduino-esp32。这样 menuconfig 能用，setup() 和 loop() 照写，也可以自己写 app_main() 再调 initArduino()。另一条路是用 Lib Builder 重编静态库，它只支持 macOS 和 Linux。

再往下就是直接写 ESP-IDF，没有 Arduino 这一层，配置全归自己。只做快速验证和搭原型，在 Arduino IDE 里装开发板包就够了。

什么时候别用：这四种情况别硬撑

项目要改 sdkconfig。理由上一节说了。
用的是 ESP32-C2 或 ESP32-C61。开发板包不带它们，只能走 ESP-IDF 组件或者重编静态库。
要用 Motor PWM（MCPWM）、脉冲计数、SDIO、TWAI/CAN-FD。官方的库支持表里这四样都标着不支持，仍可以通过 ESP-IDF 的 API 用，但可能要重编静态库。
想把 ESP8266 的代码整个搬过来。文档明说这个核心只在 ESP32 系列上测试，不保证和 ESP8266 互通。

另外，许可证是 LGPL-2.1，做闭源量产的，自己把条款过一遍。

上手前最常被问的：老库、重启、串口、连不上

Q：老库里的 ledcSetup 编译不过，库又没人更新了怎么办？

A：两条路。照迁移指南自己改成 ledcAttach；或者在开发板管理器里把 esp32 平台装回 2.0.17，它是 2.x 的最后一版。

Q：ESP32-S3 烧个空程序也一直重启？

A：有些 S3 模组带 QSPI 或 OPI 的 PSRAM，按默认设置烧就会不停重启。看模组屏蔽罩上的型号码，在工具 > PSRAM 里选：N4R2、N8R2、N16R2 选 QSPI PSRAM；N4R8、N8R8、N16R8 选 OPI PSRAM；WROOM-2 一律 OPI；型号里没有 R 的不用改。

Q：程序烧进去了，串口监视器没输出？

A：较新的芯片，板子上可能有 USB 和 UART 两个口。插的是 UART 口，就在工具菜单里关掉「USB CDC On Boot」；插的是 USB 口，就把它打开，USB Mode 选「Hardware CDC and JTAG」。原版 ESP32 只有 UART。

Q：上传时报 Failed to connect to ESP32: Timed out waiting for packet header？

A：串口上传要芯片先进下载模式，也就是复位那一刻 GPIO0 是低电平。先试上传时按住 BOOT 键；再查 USB 线是不是只能充电、有没有走 Hub，标着 TX、RX 的脚上有没有接东西。文档还给了一招：在 RST 和 GND 之间并一个 10 µF 电容。