01 · 编辑器与框架

本教程采用 VS Code 与 PlatformIO 管理工程、依赖和工具链，应用代码使用 Arduino 框架。

在 PlatformIO 中选择 Arduino 框架后，可使用相应的库和接口，并通过工程配置文件管理依赖。

提示

本教程的工具组合：VS Code + PlatformIO + Arduino 框架。

02 · 装 PlatformIO 插件

打开 VS Code，在左侧扩展面板搜PlatformIO IDE，安装。

提示

安装后通过活动栏进入 PIO Home。首次启动可能需要初始化 Python 环境。

03 · 新建项目

在 PIO Home 中选择 New Project 并填写工程参数：

Name     项目名（只用英文、数字、下划线）
Board    搜你的板子，最常见的是 Espressif ESP32 Dev Module
Framework  选 Arduino
Location   想自己选目录就取消勾选 Use default location

然后点Finish。

04 · 安装工具链

首次创建项目时，PlatformIO 会下载编译器、ESP32 框架与烧录工具。已缓存的依赖可供后续工程复用。

提示

下载失败时检查网络连接与日志，再重新安装缺失的依赖。

05 · 配置串口驱动

ESP32 开发板上负责 USB 转串口的芯片常见两种：CH340 和 CP2102。插上板子 → 打开设备管理器 → 看「端口 (COM 和 LPT)」这一项。

设备未识别或显示异常标记时，检查驱动、线缆与连接状态。安装对应驱动后确认 COM 端口可用。

提示

上传前确认串口设备已正确识别。

06 · LED 程序验证

打开工程里的src/main.cpp，把内容换成：

#include <Arduino.h>

void setup() {
  pinMode(2, OUTPUT);
}

void loop() {
  digitalWrite(2, HIGH);
  delay(500);
  digitalWrite(2, LOW);
  delay(500);
}

提示

多数 ESP32 开发板的板载 LED 接在GPIO2，但不同板子不一定一样。不确定就外接一颗 LED 到任意 GPIO，把代码里的 2 换成对应引脚号。

07 · 编译、上传、看串口

VS Code 底部状态栏有一排 PlatformIO 按钮，常用三个：

勾号图标  Build           只编译，不烧录
右箭头    Upload          编译并烧进板子
插头图标  Serial Monitor  打开串口监视器

点亮 LED 只需要点→。串口监视器的波特率可以在platformio.ini里固定下来，以统一串口连接参数：

monitor_speed = 115200

提示

上传失败时检查串口占用。关闭串口监视器后重试 Upload。

提示

如果提示连不上板子，按住板子上的BOOT键再点 Upload，进下载模式后松开。

TROUBLESHOOTING

常见问题与排查

下载失败时检查网络连接与日志，再重新安装缺失的依赖

下载失败时检查网络连接与日志，再重新安装缺失的依赖。

多数 ESP32 开发板的板载 LED 接在 GPIO2 ，但不同板子不一定一样

多数 ESP32 开发板的板载 LED 接在GPIO2，但不同板子不一定一样。不确定就外接一颗 LED 到任意 GPIO，把代码里的 2 换成对应引脚号。

上传失败时检查串口占用

上传失败时检查串口占用。关闭串口监视器后重试 Upload。

如果提示连不上板子，按住板子上的 BOOT 键再点 Upload，进下载模式后松开

如果提示连不上板子，按住板子上的BOOT键再点 Upload，进下载模式后松开。