30 分钟从裸板到 Blink：ESP32 Arduino 环境搭建与第一个联网程序

【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32

刚拿到一块 DevKitC，点上传，进度条在 "Connecting..........." 卡了整整三分钟。十次有九次不是板子坏了，是环境或板卡型号选错了。arduino-esp32 仓库就是帮你把环境搭建做对、把第一个联网程序跑起来的工具链、板级定义和内置外设库合集。

动手前花 30 秒确认三件事

三件事每一件缺了，后面都会以"莫名其妙"的方式报错：

• Arduino IDE 版本 ≥ 1.6.4：再老的版本跑不了新核心的编译脚本，直接用官网 2.x 最稳。
• 开发板管理器索引地址填对："文件 → 首选项"里"附加开发板管理器网址"填https://espressif.github.io/arduino-esp32/package_esp32_index.json。这一步漏了，管理器里永远搜不到 "esp32 by Espressif Systems"。
• "工具 → 开发板"里型号与实物完全一致：选错型号，引脚编号、上传波特率、分区策略全跟着错，Blink 里的 GPIO2 都可能不是板子上的那颗灯。

官方 安装文档 里有 Windows 和 Linux 的手动安装分步说明，clone 下来放到hardware/espressif/esp32，再跑tools/get.py拉工具链即可：

git clone https://gitcode.com/GitHub_Trending/ar/arduino-esp32

把第一次编译和上传走一遍

装好之后别急着写代码，先走官方例子：文件 → 示例 → 01.Basics → Blink。第一次编译要下载编译产物，按网速花 1~3 分钟，别以为它死了；之后再编译就是十几秒的增量。

void setup() { pinMode(2, OUTPUT); // GPIO2 通常接板载 LED，免接线 } void loop() { digitalWrite(2, HIGH); // 亮 delay(500); digitalWrite(2, LOW); // 灭 delay(500); }

点上传。如果卡在 "Connecting..........."，说明芯片没进下载模式：按住板上的 BOOT 键再点上传，进度条动起来再松手。还卡就换数据线——大量杂牌线只能充电不能传数据。看到板载 LED 开始闪烁，环境就算立住了。完整的交互式教程（含无硬件在线仿真）在 docs/en/tutorials/blink.rst。

接线前先绕开这几条引脚红线

ESP32 的引脚不是"随便用"，有几组是硬约束，接错不会报错，只会以诡异的方式翻车：

• GPIO6、7、8 被 Flash 占用：经典款上这三脚连 SPI flash，当输出驱动会和 flash 抢总线，表现为板子启动失败或时好时坏——"没接东西前明明正常"的头号原因。
• GPIO34~39 只能输入：往它们上面写输出不会报错，也不会有任何电平，只能靠调试发现。这组适合接传感器信号、读按键状态。
• GPIO0 和 GPIO2 是启动模式脚：上电瞬间的电平决定芯片进哪种模式。GPIO2 在 DevKitC 上还兼做板载 LED，电路里别拿它当普通输出。
• ADC2 的脚会被 WiFi 干扰：GPIO25~32 这组 ADC2 引脚在射频开启时读数会漂。要联网的节点，把传感器挪到 ADC1（GPIO32~39）采样。

具体以板子丝印和官方文档为准，这张图能看到每个 GPIO 对应开发板上的哪个物理孔位：

直接抄走的三个代码骨架

PWM 输出：舵机、调光、风扇调速都靠它。ESP32 的 ledc 是专用硬件 PWM 控制器，频率和分辨率自己定，比传统 analogWrite 灵活：

// 8 位分辨率 → 占空比 0~255；5 kHz 是舵机常用频率 ledcAttach(13, 5000, 8); ledcWrite(13, 128); // 占空比约 50%

I2C 外设：温湿度计、OLED 几乎全走 I2C。Wire.begin之后同一根总线能挂多个器件，靠地址区分，省线也省引脚：

#include <Wire.h> void setup() { Wire.begin(21, 22); // SDA=21, SCL=22，DevKitC 默认 I2C 脚 } void loop() { Wire.beginTransmission(0x76); // SHT3x 地址，以器件手册为准 Wire.endTransmission(); }

主模式与从模式的接线差异，官方有对比图：

WiFi 连接：所有联网程序的起点。关键是连上之前不做别的逻辑，不然时序、读数全会不准：

#include <WiFi.h> void setup() { WiFi.mode(WIFI_STA); // 以客户端身份连路由器，不是开热点 WiFi.begin("SSID", "密码"); while (WiFi.status() != WL_CONNECTED) { delay(500); } Serial.println(WiFi.localIP()); }

更多能直接跑的例子在 libraries/WiFi/examples/ 本地目录，AP 模式、多路由器切换都有。

跑一个最小上报节点

把三个骨架串起来，就是一个最小物联网节点：每 10 秒采样一次、确认联网后从串口上报。把串口那行换成 HTTPClient 或 MQTT 上传，就是远程监测节点。

#include <WiFi.h> const char* ssid = "你的SSID"; const char* pass = "你的密码"; void setup() { Serial.begin(115200); analogReadResolution(12); // 12 位精度，读数 0~4095 WiFi.begin(ssid, pass); while (WiFi.status() != WL_CONNECTED) delay(500); } void loop() { int raw = analogRead(34); // ADC1 引脚，不受 WiFi 干扰 Serial.printf("已联网，温度传感器原始值: %d\n", raw); delay(10000); }

代码不用背，验证时看这三点：

• 串口监视器波特率必须是 115200，对不上就是一堆乱码，这是"没反应"的第一来源。
• 采样脚落在 ADC1 区间（GPIO32~39）。传感器接到 ADC2 上，WiFi 一连读数就漂，你会误判传感器坏了。
• 读数整体偏移时，先给传感器单独上电测一次空载值做基准——问题常在供电，不在代码。

翻车急救包

上传一直卡在 "Connecting..........."多是板卡型号选错或线只能充电；先按 BOOT 重传，再换线，最后才怀疑板子。

能编译能上传，串口却没有任何输出C3/S3 等板子分 USB 原生与 UART 两种串口；切"工具"菜单里的 USB CDC On Boot 再重传。

编译报 "too many arguments" 之类代码按 2.x 核心写的，现在装的是 3.x，API 变了；查 docs/en/migration_guides/ 对照改。

WiFi 连接总是超时ESP32 只支持 2.4 GHz；双频合一的路由器先在后台拆出一个独立 2.4G SSID。

启动失败、OTA 失败等系统级症状直接翻 docs/en/troubleshooting.rst，分区表和启动日志都在里面，比搜论坛快。

按你的下一步选路

• 如果想做近距离无线：libraries/BLE/目录里有几十个 GATT 服务端/客户端示例；不想组网、只让两块板互传数据的话，ESP_NOW 库更省事。
• 如果想在板子上挂网页：libraries/WebServer/起一个 HTTP 页面，再从tools/partitions/挑一张带文件系统区的分区表，网页资源就能直接烧进 Flash。
• 如果被功耗追着跑：DeepSleep 示例演示微安级睡眠唤醒，适合电池供电的传感器节点；各 SoC 到底支持哪些功能，docs/en/libraries.rst里的支持矩阵能帮你选对芯片。

【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32