ESP32 Arduino Core 完整指南：10 分钟配好开发环境并跑通 Web 服务器
【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32
arduino-esp32 是 ESP32 系列芯片的官方 Arduino 核心：用你熟悉的 Arduino IDE 语法，就能给 ESP32、ESP32-S2/S3、ESP32-C3/C6 写代码、编译并上传固件，WiFi、BLE、I2C、SPI、文件系统这些驱动全部由板级包一次性装好。做 IoT 原型开发，这是绕不开的地基。
适合看这篇文章的人：
- 手头有 ESP32 板子，但 Arduino IDE 还没配好，或者配到一半报错的
- 想一次性从"找不到板子"走到"浏览器能打开板子页面"的
可以跳过的情况：
- 已经装好 ESP32 核心、只需要查某个 API 用法的，直接看文末的资源索引表
板级包到底装了什么东西
装包之前先把两个概念搞清楚，后面排错时才看得懂报错。
板级支持包：芯片的"系统 + 驱动"
生活类比：新手机连电脑，光有 ROM 不够，还得装厂商驱动包，电脑才认得它。板级包就是 ESP32 的驱动包。一句话定义：一套编译器工具链 + 核心代码 + 内置库，让 Arduino IDE 把你的 .ino 翻译成 ESP32 能烧写的固件。为什么重要：后面选板子、出串口、编译 WiFi 库，全靠它。源码本体在 cores/esp32/，随包附带的库在 libraries/。
variant：每块板的"引脚字典"
生活类比：同一个词在不同方言里写法不同，variant 文件就是每块板子的引脚方言字典。一句话定义：把LED_BUILTIN、SDA、SCL这类逻辑名映射成具体板子物理引脚号的一组定义。为什么重要：这是同一份 sketch 换块板子还能原样编译的原因。标准 Dev Module 的引脚定义在 variants/esp32/pins_arduino.h，整个 variants/ 目录有 300 多个子目录，对应各款开发板。
接硬件前对照官方引脚图看一遍：哪些脚能做 ADC、哪些只能输入、内置 LED 在哪根脚上，都标在图上。
从零到上传第一个程序的完整流程
贴地址，装包
打开文件 → 首选项（macOS 在顶部菜单 Arduino → 设置），找到最下方的Additional Boards Manager URLs，把下面这行粘进去，点 OK：
https://espressif.github.io/arduino-esp32/package_esp32_index.json
成功标志：重新打开首选项，地址仍然留在那个输入框里。
板管理器里装核心
进入工具 → 开发板 → 板管理器，搜索框输入esp32，找到 Espressif Systems 发布的esp32条目，点Install。
成功标志：进度条走完，按钮变成 "Installed"，没有红色报错。整包有好几百 MB，慢网可能要十几分钟，耐心等它跑完。
选板子、选端口、上传 Blink
用数据线把板子插到电脑。工具 → 开发板 → ESP32 Dev Module（按你的板子型号选对应的），工具 → 端口里选新出现的串口。
打开文件 → 示例 → 01.Basics → Blink，点上传。
成功标志：板载 LED 开始闪烁，串口监视器（波特率设 115200）里滚出几行字，最后带Hello world!。如果 LED 在闪但监视器一片空白，去避坑地图看第二条。
如果你的板子不在下拉列表里，先搜 variants/ 下的目录名——能对上说明官方支持，选引脚最接近的型号即可。
避坑地图：四种失败及修复动作
按出现频率从高到低排，出问题照这个顺序查。
端口列表里找不到板子，或上传必失败
- 症状：端口列表是空的，或一上传就报端口打不开、需要复位
- 根因：USB 线只支持充电不支持传数据，或板子没进下载模式
- 修复：换一根数据线；按一下BOOT键再按一下RESET键，同时松开后重新上传
串口监视器没有任何输出
- 症状：程序明显在跑（LED 在闪），监视器却一片空白
- 根因：监视器波特率和代码不一致，或代码里根本没初始化串口
- 修复：监视器选 115200；确认
setup()第一行有Serial.begin(115200);
板管理器搜不到 esp32
- 症状：搜索结果为空，或只出现第三方同名条目
- 根因：板管理器 URL 没添加，或地址打错了一个字符
- 修复：回首选项检查那个输入框；注意改完设置要重启 IDE 再搜
包下载中断，安装卡住
- 症状：安装进度条卡死或中途弹错
- 根因：下载被网络切断，staging 缓存里留了半截包
- 修复：关闭 IDE，清空 staging 缓存目录，重开再装。目录：Windows 是
C:\Users\<用户名>\AppData\Local\Arduino15\staging\packages，macOS 是~/Library/Arduino15/staging/packages，Linux 是~/.arduino15/staging/packages
一个能跑通的最小项目：手机能打开的 Web 服务器
只说做什么、结果是什么。
板子以 WiFi 站模式（STA，就是你手机连路由器那种模式）接入家里路由器，局域网内任何设备用浏览器直接通过 IP 访问它。
第一步，新建 sketch，先粘声明部分：
#include <WiFi.h> #include <WebServer.h> const char* ssid = "你的WiFi名"; const char* psk = "你的WiFi密码"; WebServer server(80);再粘主逻辑，setup()最后一行会把板子的 IP 打到串口监视器：
void setup() { Serial.begin(115200); WiFi.begin(ssid, psk); while (WiFi.status() != WL_CONNECTED) delay(500); server.on("/", [](){ server.send(200, "text/plain", "hello from esp32!"); }); server.begin(); Serial.println(WiFi.localIP()); }void loop() { server.handleClient(); }第二步，把开头的两个变量换成你路由器的 SSID 和密码，选对板子和端口，上传。
第三步，从串口监视器抄下 IP（形如192.168.x.x），在手机或电脑浏览器地址栏输入，回车。
结果：页面显示hello from esp32!，这串字就是代码里server.send(...)发出的响应。后面做控制面板、传感器页面、OTA 更新入口，都是在这个骨架上加东西，可对照 libraries/WebServer/examples/HelloServer/ 里的现成写法。
资源索引：下一步去哪找
| 你想做什么 | 去哪找 |
|---|---|
| 安装、更新核心，查支持哪些板 | docs/en/installing.rst、boards.txt |
| 点第一个 LED、串口基础 | docs/en/tutorials/blink.rst |
| 查某块板子的引脚定义 | variants/（一板一目录） |
| WiFi 连接、热点（AP）示例 | libraries/WiFi/examples/（WiFiClientBasic、WiFiAccessPoint） |
| Web 服务器、页面、文件上传 | libraries/WebServer/examples/ |
| BLE 通信与周边外设 | libraries/BLE/、docs/en/api/ble.rst |
| 本地文件系统（LittleFS / SPIFFS） | libraries/LittleFS/、libraries/SPIFFS/ |
| 无线固件更新 OTA | libraries/ArduinoOTA/ |
| 深睡、定时器、I2C/SPI/ADC 等 API | docs/en/api/（每类外设一篇） |
| 板子没反应、没输出、装不上 | docs/en/troubleshooting.rst |
| 看官方功能如何验证 | tests/validation/ |
到这里主线就走完了：环境装好、Blink 点亮、板子被浏览器访问到。接下来做什么项目，按上表挑库、照它的 examples 改，比翻理论文档快得多。
【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
