Arduino ESP32 开发板安装避坑手册：从自检清单到首次烧录
【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32
你刚把 ESP32 开发板插上电脑，想装好 Arduino 环境写个 WiFi 小项目，结果开发板管理器里搜不到 esp32，或者进度条转了半天直接报错。ESP32 安装失败大多不出在"装"这一步，而出在装之前没做对几件小事。这份手册按"先自检、再安装、后验证"的顺序，把每个环节该看什么、看到什么算通过一次讲清楚。
安装前自检清单
开始下载之前，先花两分钟确认以下几项。每项都给出判断标准，不符合就先处理，能避开后面 80% 的故障：
- IDE 版本：打开 Arduino IDE，通过"帮助 → 关于"查看版本。1.8 及以上算通过；低于 1.8 的 IDE 对 Boards Manager 的支持不完整，先升级再继续。
- 网络连通性：浏览器里直接访问下面这个地址，能正常加载 JSON 内容算通过：
https://espressif.github.io/arduino-esp32/package_esp32_index.json如果加载缓慢或超时，建议换到网络空闲时段再操作。 - 历史缓存残留：如果你之前装失败过，需要清理两处目录（先完全关闭 IDE）：
~/.arduino15/staging/packages~/.arduino15/packages/esp32两个文件夹不存在或已删除算通过。残留的半成品缓存是"进度条卡住"的高发原因。
- 磁盘空间：ESP32 工具链包含 xtensa 编译器，体积较大。安装目标盘剩余空间至少预留数 GB 算通过。
- 操作系统：Windows 用户注意，Arduino ESP32 v2.x 已不再支持 32 位系统（Win32）和 Windows 8 及以下版本。系统是 64 位且为 Windows 10/11 或更新版本算通过。
安装主流程
打开首选项窗口。菜单栏选择文件 → 首选项，在弹出的设置窗口中找到"附加开发板管理器网址"（Additional Board Manager URLs）输入框。
填入官方下载地址。把稳定版包地址填入该输入框（可填多个地址，用英文逗号分隔）：
https://espressif.github.io/arduino-esp32/package_esp32_index.json国内网络环境下如果官方地址加载不稳定，可以改用官方镜像地址https://jihulab.com/esp-mirror/espressif/arduino-esp32/-/raw/gh-pages/package_esp32_index_cn.json，并选择带-cn后缀的包版本。
完成上一步并保存首选项后，你会回到 IDE 主界面。接下来打开工具 → 开发板 → 开发板管理器，在搜索框输入esp32，列表里会出现由Espressif Systems发布的esp32平台包。
点击版本号旁边的"安装"，IDE 会依次下载平台包和 xtensa 编译器、esptool 等工具。这一步耗时取决于网速，进度条在"下载工具"阶段长时间缓慢属正常现象，不要中途关闭窗口。
安装结束、IDE 提示完成后，重启一次 Arduino IDE，让新平台被完整加载。
装完如何确认环境真的可用
装完不等于能用，做两个动作确认环境真的就绪。
动作一：检查开发板列表。打开工具 → 开发板，滚动查看菜单：
- 成功：能看到
ESP32 Dev Module、ESP32 Wrover Module、ESP32S3 Dev Module等型号条目。 - 失败：菜单里只有 AVR 系列开发板，没有 esp32 开头的内容——说明平台包没装上或 IDE 没重启，回到上一步检查安装日志。
动作二：编译一个最小示例。菜单选择文件 → 示例 → WiFi → WiFiScan（示例源文件位于仓库的 libraries/WiFi/examples/WiFiScan/ 目录），点击编译按钮：
- 成功：输出窗口滚动显示编译信息，最后出现类似
Sketch uses ... bytes的内存统计，无红色错误。 - 失败：出现
Failed to connect to ESP32: Timed out waiting for packet header或类似超时信息。若只是烧录失败而编译通过，多半是板子没进入下载模式：按住板上的BOOT按钮再松开，同时保持 USB 连接为电脑直连（不要经过 USB Hub，部分数据线只能充电不能传数据）。
故障速查表
| 症状 | 最可能原因 | 处置动作 |
|---|---|---|
| 安装进度条长时间卡住不动 | 下载中断后残留了半成品缓存 | 关闭 IDE，删除~/.arduino15/staging/packages和~/.arduino15/packages/esp32两个目录后重新安装 |
| 开发板列表里搜不到 esp32 | 首选项里的管理器地址没填或填错 | 回到文件 → 首选项核对"附加开发板管理器网址"是否为完整正确的 JSON 地址，保存后重启 IDE |
反复报Timed out waiting for packet header | 板子没进入下载模式，或 USB 线路/Hub 供电异常 | 烧录时按住 BOOT 键；更换带数据线的 USB 线，直连电脑 USB 口，绕开 Hub |
| 下载特别慢或中途断开 | 网络不稳定，或官方地址在当前网络下不可达 | 换网络空闲时段重试；国内环境改用官方-cn镜像地址与带-cn后缀的包版本 |
Linux 下编译报python: executable file not found in $PATH | 系统只有 python3 没有 python 软链接 | 安装python-is-python3包（sudo apt install python-is-python3）后重新编译 |
更完整的排错思路可以对照仓库自带的 docs/en/troubleshooting.rst 文档。
下一步
环境验证通过后，把板子插上串口、在工具 → 端口里选中对应 COM 口，直接编译上传刚才的 WiFiScan 示例，看到扫描到的 WiFi 列表就说明从安装到烧录整条链路都通了。
【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
