串口与端口问题
症状：设备管理器里找不到串口
- 换一根能传数据的 USB 线（很多线是纯充电线），这是新手第一大坑
- 换 USB 口，优先用主板后置 USB 口，避开 USB 集线器
- 缺少 CP210x 或 CH340 驱动：设备管理器里看到带黄色叹号的未知设备就是这个原因，到硅实验室或沁恒官网装对应驱动
- 数据线接的是开发板上的 USB 转串口芯片，若板上有两个 USB 口（如 ESP32-S3 板），程序口和 OTG 口要分清
症状：串口出现但烧录时连不上（A fatal error occurred: Failed to connect to ESP32）
ESP32 下载需要芯片进入下载模式。多数板子会自动完成，但部分板子或某些电脑需要手动：
- 按住 BOOT 键不放
- 点烧录，等日志出现
Connecting...后松开 - 烧录完成后按一下 RST（复位）键运行新程序
仍失败就把烧录波特率从 921600 降到 115200，老芯片或劣质线在高波特率下容易丢包。
烧录与运行问题
症状：烧录成功但程序不运行
- 烧完没复位：按一下 RST 键
- 串口监视器打开了正在占用串口，关掉再烧录
- 选错了 Flash 大小或分区方案：Tools 菜单里 Flash Size 与板子实际不符会启动失败，不确定就选 4MB
症状：串口疯狂输出乱码或反复重启
- 乱码：波特率不对，ESP32 程序默认 115200，监视器选成 9600 就是一屏乱码
- 反复重启并打印
boot:0x13 (SPI_FAST_FLASH_BOOT)之类循环日志：多半是 GPIO 0、2、12、15 上外接了影响启动电平的电路，断开外设再试 - 打印
Guru Meditation Error后重启：程序崩溃，记下Backtrace地址，用addr2line或 Exception Decoder 插件定位代码行，常见原因是空指针、数组越界、把仅输入引脚当输出用
症状：提示 Brownout detector triggered
电源电压不足被芯片主动复位。ESP32 在 WiFi 发射瞬间电流可达 300 mA 以上，供电不足的常见来源：劣质 USB 线（压降大）、电脑 USB 口供电弱、面包电源带不动。换粗短线或用 5V/2A 独立供电。
WiFi 问题
症状：一直连不上 WiFi
- 确认是 2.4 GHz 网络，ESP32 不支持 5 GHz；手机热点记得在热点设置里选 2.4 GHz 频段
- SSID 与密码区分大小写；密码里的空格肉眼难辨，建议先连手机验证
- 路由器开了 AP 隔离或 MAC 过滤，把设备加入白名单
- 公司、校园等 Portal 认证网络无法直接使用，需先在别的设备完成认证流程
症状：能连上但 HTTP 请求失败
- URL 用了 https：直接
http.begin()访问 https 站点会失败，需改用WiFiClientSecure并处理证书，或测试阶段先访问 http 站点 - 域名解析失败：热点共享的网络有时 DNS 异常，可
WiFi.config()手动指定 DNS 为 8.8.8.8
开发环境问题
症状：Arduino IDE 下载开发板包极慢
在 File → Preferences 的 Additional Boards Manager URLs 换用乐鑫官方国内镜像源（jihulab.com），详见「Arduino IDE 安装」页。
症状：编译报 ledcSetup was not declared
教程用的 2.x 旧 PWM API，3.x 已改用 ledcAttach() / ledcWrite()，详见「基础外设」页。
症状：ESP-IDF 终端里 idf.py 不是内部或外部命令
没有进入 IDF 环境。Windows 用开始菜单里的 ESP-IDF PowerShell/CMD 快捷方式，或在 EIM 安装的容器化环境里执行命令，详见「ESP-IDF 安装」页。
通用排查心法
- 先看串口日志：ESP32 的启动与崩溃信息几乎都在串口里，养成接上监视器再排查的习惯
- 断开外设最小化复现：裸板烧官方 Blink 例程，能跑通说明问题在你的接线或代码
- 一次只改一个变量：换线、换口、改波特率逐项确认，避免不知道哪个起了作用
- 善用官方例程：File → Examples → WiFi/BLE 里的官方例程是可信基线，先跑通例程再叠加自己的代码