Question 1

ESP32 连不上芯片：esptool 在等一个永远不来的回应 是什么意思，怎么解决？

Accepted Answer

电脑能看见串口，但芯片当时没处在「下载模式」，所以烧录软件敲门没人应。这是 ESP32 排名第一的报错，九成不是芯片坏了。 点上传，看到日志里出现 Connecting... 的那一刻按住 BOOT 不放，等进度条开始跳百分比再松开。 把 USB 线插手机上试：如果不弹出「文件传输」提示，这根线就是纯充电线，换一根。 关掉所有串口监视器和多余的 IDE 窗口，串口只能被一个程序占用。 换机箱后置 USB 口（不要用前置面板或没供电的 HUB），或降到 115200 波特率。 把板子上的外设、扩展板全部拆掉，只留最小系统再试一次。

Question 2

ESP32 芯片启动模式不对（Wrong boot mode） 是什么意思，怎么解决？

Accepted Answer

芯片上电时被采样到的 strapping 电平组合不是下载模式。本质是 GPIO0 在复位瞬间没有被稳定拉低。 标准手动流程：按住 BOOT（GPIO0 接地）→ 点一下 EN（复位）→ 松开 EN → 再松开 BOOT。 用万用表量 GPIO0 对地电压，进入下载模式时应该接近 0 V。 拆掉 GPIO0 上所有外接的东西（LED、继电器模块、传感器）再试。 如果用的是 ESP32 经典款，顺手确认 GPIO2 在上电时是低电平。

Question 3

ESP32 端口打不开：找不到、被占用、或没权限 是什么意思，怎么解决？

Accepted Answer

操作系统层面就没连上，跟芯片无关。Windows 通常是驱动/占用，Linux 是权限，macOS 是驱动冲突。 Windows：设备管理器 → 端口(COM 和 LPT)，看有没有黄色感叹号。CH340 装 WCH 官方驱动，CP210x 装 Silicon Labs 官方驱动，别两个都装。 把所有串口监视器、IDE 窗口关掉，只留一个。 Linux：执行 sudo usermod -aG dialout $USER，注销重登后生效。 拔掉重插，观察设备管理器里的 COM 号有没有变化；如果在乱跳，多半是供电不足或接触不良。

Question 4

ESP32 写到一半失败：能连上但烧不进 是什么意思，怎么解决？

Accepted Answer

握手成功了，但真正写 Flash 时断掉。写 Flash 瞬间电流最大，几乎都是供电或线材扛不住。 把波特率降到 115200 再烧，先求稳不求快。 换成短而粗的线，插机箱后置口；或用带独立供电的 HUB。 在 3V3 与 GND 之间并一个 10–100 µF 电解电容，吸收电流尖峰。 如果是自焊的模组，补焊 Flash 周边引脚，重点看虚焊。

Question 5

ESP32 校验失败：烧进去的和文件对不上 是什么意思，怎么解决？

Accepted Answer

写完后回读比对，内容不一致。说明写入过程受到了干扰，或者 Flash 地址/模式不对。 先降波特率到 115200 重试一次。 确认 flash 模式：多数模组是 DIO，ESP32-WROVER 系列常见 QIO。不确定就用 DIO，它最保守。 核对每个 bin 的烧录地址：bootloader 0x1000、分区表 0x8000、app 0x10000（经典 ESP32）。 如果反复失败且地址、模式都正确，flash 芯片大概率坏了。

Question 6

ESP32 固件太大，Flash / 分区装不下 是什么意思，怎么解决？

Accepted Answer

编译出来的体积超过了分区表给 app 留的空间。开 OTA 时尤其常见——两个 app 槽位会把可用空间砍掉近一半。 Arduino IDE：工具 → Partition Scheme 换成容量更大的方案（比如 "16M with spiffs" 或 "Minimal SPIFFS"）。 关掉 OTA（工具 → Partition Scheme 选不含 OTA 的方案）能立刻多出近一倍空间。 把日志级别降到 Warning / Error，能省几十 KB。 ESP-IDF：idf.py size-files 看是哪个组件占了大头。

Question 7

ESP32 掉电检测触发（Brownout） 是什么意思，怎么解决？

Accepted Answer

芯片检测到自己的电压掉到阈值以下，为了不出乱子直接把自个儿复位了。Wi-Fi 发射瞬间电流最大，最容易踩到。这不是代码的问题。 换外接 5 V 电源（≥1 A），不要靠电脑 USB 口，尤其别用前置面板和无源 HUB。 在 3V3 与 GND 之间并 100 µF 电解 + 0.1 µF 陶瓷电容，位置尽量靠近模组。 程序里先把 Wi-Fi 发射功率降下来试试：WiFi.setTxPower(WIFI_POWER_8_5dBm)。 如果是临时的权宜之计，可以在 menuconfig 里关掉或调低 brownout 阈值，但这只是掩盖问题，电源该改还得改。

Question 8

ESP32 看门狗复位：rst:0x10 / 0x7 / 0x8 是什么意思，怎么解决？

Accepted Answer

芯片认为程序「卡死了」，于是自己重启。0x10 是开机阶段就卡住（bootloader 级），0x7/0x8 是某个任务长时间没喂狗（FreeRTOS 任务看门狗）。 看日志里 Task watchdog got triggered 后面括号中的任务名，那就是卡住的任务。 所有循环里必须加 vTaskDelay() 或 delay()，哪怕是 1 ms，给调度器留出空间。 检查有没有在循环里无延时地 printf/Serial.println——串口是行缓冲，会拖死系统。 如果是 rst:0x10，先确认 PSRAM 与 Flash 模式的配置，再查 app_main 之前的初始化代码。

Question 9

ESP32 串口一堆乱码：多半只是波特率不对 是什么意思，怎么解决？

Accepted Answer

ESP32 开机时 bootloader 会以 74880 波特率打一行信息，如果你的监视器设成 9600 或 115200，看到的就会是乱码——这是正常的，不是板子坏了。 把串口监视器波特率设成 115200（这是绝大多数固件的默认值）。 想看开机那行 bootloader 信息就设成 74880。 Arduino 用户注意代码里 Serial.begin(115200) 的数值必须和监视器一致。

Question 10

ESP32 LoadProhibited：读了不该读的内存 是什么意思，怎么解决？

Accepted Answer

程序去读了一块无效地址。最常见的是空指针、野指针、或者对象已经被释放还在用。看 EXCVADDR：如果是 0x00000000，基本就是解引用了 NULL。 看 EXCVADDR：等于 0 说明是 NULL 指针；接近 0 是结构体成员访问；像乱码一样说明指针未初始化。 用 addr2line -e build/xxx.elf 0x400dxxxx 把 Backtrace 里的地址换成代码行号。 ESP-IDF 用户直接看 idf.py monitor，它会自动把 backtrace 解成人能读的函数名和行号。 所有可能返回 NULL 的调用都要判空：malloc、calloc、容器的查找、硬件初始化。

Question 11

ESP32 StoreProhibited：写了不该写的内存 是什么意思，怎么解决？

Accepted Answer

往一个无效地址写数据。典型是往只读区域写、往 NULL 指针指向的成员写、或者数组越界写。 看 EXCVADDR 定位被写的地址，再对照 backtrace 找到那行代码。 把所有 strcpy 换成 strncpy 或 snprintf，字符串一定要限长。 检查数组下标的最大值，尤其是用变量当索引的地方。 确认目标缓冲区在写入期间仍然有效（不是局部变量出了作用域）。

Question 12

ESP32 IllegalInstruction：CPU 执行了一条不是指令的东西 是什么意思，怎么解决？

Accepted Answer

程序计数器跳到了不该执行的地方。常见原因是函数指针坏了、栈被踩坏、或者把 Flash 引脚当成 GPIO 用了导致读不出指令。 检查代码里有没有用到 GPIO6–11（ESP32 经典款），这些脚连着 Flash，绝对不能当普通 IO。 把 Flash 占用的引脚释放掉，恢复默认功能。 检查所有函数指针是否初始化过再调用。 打开编译警告，把没有 return 的非 void 函数全部补上。

Question 13

ESP32 InstrFetchProhibited：取指令失败 是什么意思，怎么解决？

Accepted Answer

CPU 想执行某个地址的指令，但那个地址不在有效的代码区里。PC 寄存器如果是 0 或一堆乱码，说明函数指针坏了。 看 PC 寄存器的值：不是 0x4xxxxxxx 开头就说明跳转目标非法。 检查所有回调注册是否成功，失败时不要继续调用。 增大可疑任务的栈空间再试，排除栈溢出。

Question 14

ESP32 栈溢出：任务栈不够用了 是什么意思，怎么解决？

Accepted Answer

这个任务用的栈超过了分配给它的大小，越界写把「金丝雀」踩了，系统立刻报出来。比起莫名其妙的崩溃，这其实是个好消息——它直接告诉你是哪个任务。 按日志里的任务名，把创建任务时的栈大小调大一档（2048 → 4096 → 8192）。 把大数组改成 static 或改用 malloc 放到堆上。 用 uxTaskGetStackHighWaterMark() 看这个任务实际用了多少栈，按需调整。 printf 系列很吃栈，打印 JSON 或长字符串时尤其明显，能省则省。

Question 15

ESP32 任务看门狗：某个任务卡住不喂狗 是什么意思，怎么解决？

Accepted Answer

空闲任务长时间没得到 CPU，说明有任务占着不放。日志会直接点名是哪个任务。 找到日志里点名的任务，在它的循环体里加 vTaskDelay(1) 或 delay(1)。 中断服务程序里只做标记（置标志位 / 发队列），实际处理放到任务里。 检查互斥锁的加锁顺序，避免互相等待。 如果确实是长时间计算，把任务绑到另一个核，或者周期性调用 vTaskDelay 让出 CPU。

Question 16

ESP32 abort / assert failed：代码主动调用异常中止 是什么意思，怎么解决？

Accepted Answer

不是硬件问题，是代码或库主动抛出的中止。assert 后面那一行会写明文件名、行号和判断条件，这是最好查的一类崩溃。 把 assert 那一行的文件名和行号抄下来，直接去那一行看条件表达式。 往上翻日志，找到 abort 之前打印的最后一条 E (...) 错误，那通常是真正的根因。 确认相关外设已经 begin() / init() 成功再使用。 如果指向库内部，多半是版本不匹配——升级或回退库版本。

Question 17

ESP32 Cache disabled：在 Flash 操作期间访问了需要缓存的代码 是什么意思，怎么解决？

Accepted Answer

擦写 Flash 或操作 SPI 时，Cache 会被临时关掉，这时候调用存放在 Flash 里的函数或中断就会崩。ESP-IDF 用 IRAM_ATTR 解决。 给中断服务程序加上 IRAM_ATTR，并把它用到的常量也标上 DRAM_ATTR。 在擦写 Flash 前先禁用相关中断，或者用 spi_flash_disable_interrupts_caches_and_other_cpu()。 多任务访问 NVS 时加互斥锁。

Question 18

ESP32 内存不足：分配失败 是什么意思，怎么解决？

Accepted Answer

堆不够了。经典 ESP32 只有约 300 KB 可用 DRAM，开 Wi-Fi + TLS + 摄像头很容易见底。 用 esp_get_free_heap_size() 定期打印剩余堆，确认是缓慢泄漏还是一次性不够。 ESP32-S3 / WROVER 用户：在 menuconfig 里打开 PSRAM，并把大缓冲指定为 MALLOC_CAP_SPIRAM。 cJSON 解析完必须 cJSON_Delete()；摄像头取帧后必须 esp_camera_fb_return()。 减少并发的 TLS 连接和大字符串拼接，改用流式或分块处理。

Question 19

ESP32 PSRAM 初始化失败 是什么意思，怎么解决？

Accepted Answer

芯片没找到外挂的 PSRAM。可能是模组本来就没有 PSRAM，也可能是配置开了但硬件不支持，或者引脚被占用。 先确认模组型号：ESP32-WROOM 没有 PSRAM，ESP32-WROVER 才有。看模组丝印。 Arduino：工具 → PSRAM 设为 Disabled，或换成 OPI PSRAM（S3）。 ESP-IDF：menuconfig → Component config → ESP PSRAM，关掉或选对类型。 如果模组确实有 PSRAM 但读不到 ID，检查 GPIO16/17（经典 ESP32）是否被占用。

Question 20

ESP32 DRAM 溢出：全局变量/static 太多 是什么意思，怎么解决？

Accepted Answer

链接阶段就失败了，说明全局变量和 static 变量加起来超过了可用 DRAM。这类错误在编译时就暴露，比运行时崩溃好处理。 把大数组改成 malloc 动态分配，或加 EXT_RAM_BSS_ATTR 放到 PSRAM。 ESP-IDF：idf.py size-components 看 DRAM 被谁占了。 降低日志等级、关掉不必要的调试选项。

Question 21

ESP32 搜不到热点 / 连不上 Wi-Fi 是什么意思，怎么解决？

Accepted Answer

ESP32 只支持 2.4 GHz，不支持 5 GHz。如果路由器开了「双频合一」，或者你用的是手机 5G 热点，它根本看不见这个网络。 确认路由器广播的是 2.4 GHz。手机热点要在设置里明确选 2.4 GHz。 关掉路由器的「双频合一 / 智能连接」，让 2.4 G 和 5 G 分开显示。 把 SSID 和密码重新手打一遍，注意大小写和空格。 先写一段最小代码只做 WiFi.begin() 并打印 WiFi.status()，排除其他代码干扰。

Question 22

ESP32 Wi-Fi 密码对了但认证失败 是什么意思，怎么解决？

Accepted Answer

密码正确但握手没过。常见于 WPA2/WPA3 混合模式、加密方式不兼容，或者信号质量差导致握手超时。 把路由器加密方式临时改成纯 WPA2-PSK（AES）试一次。 把设备搬到离路由器 2 米内测试，排除信号问题。 密码里如果有 \ 或引号，C/C++ 字符串里要做转义。 升级 ESP-IDF 或 Arduino-ESP32 core 到较新版本以获得 WPA3 支持。

Question 23

ESP32 MQTT 连不上 / 反复重连 是什么意思，怎么解决？

Accepted Answer

网络通了但 MQTT 握手没过。看返回码：rc=-2 是超时（网络层），rc=4/5 是用户名密码错，rc=2 是 client id 被拒。 给每个设备生成唯一 client id（用 MAC 地址后几位）。 先用电脑上的 MQTT 客户端（如 MQTTX）用同样参数连一次，确认服务端没问题。 把 keepalive 调到 60 秒以内。 如果用 TLS，确认根证书正确、系统时间已同步（NTP），时间不对会导致证书校验失败。

Question 24

ESP32 TLS / HTTPS 握手失败 是什么意思，怎么解决？

Accepted Answer

HTTPS 连接建立不起来。最常见的原因是设备系统时间不对导致证书「尚未生效」，其次是根证书缺失或过期。 先连 NTP 同步时间，成功后再发起 HTTPS 请求。 确认固件里烧了正确的根证书 PEM。 设置 SNI（ESP-IDF 里 esp_http_client_config_t 的 hostname 字段）。 打印 esp_get_free_heap_size()，TLS 握手至少需要 40 KB 以上的连续空间。

Question 25

ESP32 摄像头初始化失败（Camera probe failed） 是什么意思，怎么解决？

Accepted Answer

ESP32 通过 SCCB（类 I2C）跟摄像头握手，没握上。排第一的原因永远是排线没插好，第二是代码里选错了板子型号。 拔下排线重新插到底，确认锁扣扣紧，金手指完全没入。这一步能解决一半的问题。 代码里确认只保留一个 #define CAMERA_MODEL_AI_THINKER，其余全部注释掉。 换成 5 V / 2 A 独立供电，不要用电脑 USB 口，更不要接 3.3 V 引脚。 先跑官方 CameraWebServer 示例，确认硬件没问题再改自己的代码。

Question 26

ESP32 取帧失败 / 画面花屏绿屏 是什么意思，怎么解决？

Accepted Answer

帧缓冲分配不出来，或者 DMA 搬运跟不上导致数据错位。花屏绿屏基本就是 PSRAM 没开或分辨率设太高。 Arduino：工具 → PSRAM 设为 Enabled；分区方案选带 Wrover 的。 确认 psramFound() 返回 true，不是 true 就说明没生效。 把分辨率降到 QVGA (320×240) 或 VGA 先跑通，再逐步提高。 每次 esp_camera_fb_get() 之后一定要 esp_camera_fb_return(fb)。

Question 27

ESP32 OTA 升级失败或回滚 是什么意思，怎么解决？

Accepted Answer

新固件写进去了但校验没过、或启动后没有确认「我活了」，芯片就会回滚到旧版本。这是设计上的保护机制，不是 bug。 确认分区表有两个 app 分区（ota_0 / ota_1）。 核对固件大小不超过单个 app 分区。 新固件启动并自检通过（比如成功连上 MQTT）之后，立刻调用 esp_ota_mark_app_valid_cancel_rollback()。 下载时校验 MD5/SHA，网络不稳时加重试和断点续传。

Question 28

ESP32 ADC2 与 Wi-Fi 冲突：读数全是错的 是什么意思，怎么解决？

Accepted Answer

ESP32 经典款的 ADC2 通道被 Wi-Fi 驱动占用，Wi-Fi 一开 ADC2 就读不准。这不是代码 bug，是硬件架构决定的。 换到 ADC1：GPIO32–39（ESP32 经典款），这是唯一稳妥的选择。 如果必须用 ADC2，就在 Wi-Fi 关闭的时间窗口里读，读完再开 Wi-Fi。 电池电压检测一定要用 ADC1，并且加 100 nF 旁路电容和多次平均。

Question 29

ESP32 I²C 通信失败：设备不应答 是什么意思，怎么解决？

Accepted Answer

主机发了地址但从机没拉低 SDA 应答。多半是地址不对、没接上拉电阻、或者设备根本没上电。 SDA/SCL 各接一个 4.7 kΩ 上拉到 3.3 V（线长或设备多时改 2.2 kΩ）。 跑一段 I²C 扫描程序，打印实际扫到的地址，别猜。 确认从设备供电正常且与 ESP32 共地。 不要用 GPIO34–39（仅输入、无内部上拉）做 I²C。

Question 30

ESP32 Strapping 脚电平不对：板子起不来或反复重启 是什么意思，怎么解决？

Accepted Answer

上电瞬间被采样的那几个脚（GPIO0/2/5/12/15）决定了芯片怎么启动。外接电路如果把它们拉成了错误电平，板子就会表现出各种诡异症状——最典型的是 GPIO12 被拉高导致 Flash 供 1.8 V，整块板「变砖」。 用万用表量每个 strapping 脚在上电瞬间的电压，对照 datasheet 的要求电平。 GPIO12：上电时必须为低（或悬空靠内部下拉）。千万不要接默认输出高电平的器件（比如某些按键模块、上拉的传感器输出）。 GPIO0：接 10 kΩ 上拉 + 对地按键，不要直接接会拉低它的电路。 GPIO15：接 10 kΩ 下拉，不要让它悬空或被拉高。

Question 31

ESP32 深度睡眠叫不醒 / 立刻醒来 是什么意思，怎么解决？

Accepted Answer

进深睡后要么醒不来，要么刚睡就醒。前者通常是唤醒源没配对，后者通常是唤醒引脚当前就处在触发电平上。 确认唤醒脚是 RTC GPIO（ESP32 是 GPIO0/2/4/12–15/25–27/32–39 中的 RTC 子集）。 给唤醒脚配好外部上下拉，让它处于「非触发」的默认电平。 ext0 只能单个脚；ext1 可以多个脚，但要明确指定唤醒条件是「任一」还是「全部」。 唤醒后所有外设（Wire、SPI、串口、Wi-Fi）都要重新初始化。

Question 32

ESP32 头文件找不到：库没装或路径不对 是什么意思，怎么解决？

Accepted Answer

编译器找不到 #include 的那个头文件。Arduino 里是库没装，ESP-IDF 里是组件没加进 CMakeLists。 Arduino：项目 → 加载库 → 管理库，搜库名安装。装完重启 IDE。 装库时注意版本：很多示例都写明了「需要 x.y.z 版本」，别装最新版。 ESP-IDF：在 CMakeLists.txt 里加上 set(EXTRA_COMPONENT_DIRS ...)。 手动放库到 ~/Arduino/libraries/ 时，目录名必须和 .h 文件名一致。

Question 33

ESP32 API 变了：示例代码和新版库对不上 是什么意思，怎么解决？

Accepted Answer

这是「网上抄的代码跑不起来」最常见的原因。ESP32 Arduino core 从 2.x 升到 3.x 时改了不少 API，旧示例直接编译不过。 确认示例要求的 core 版本：Arduino IDE 开发板管理器里把 esp32 包降到对应版本（如 2.0.17 或 3.x）。 看报错里提到的那个函数名，去库的 examples 目录里找同名的最新示例对照。 ESP8266 的代码不能直接用在 ESP32 上，Wi-Fi 和文件系统部分差别尤其大。 实在不行就用 PlatformIO，在 platformio.ini 里把版本号写死，环境可复现。

Question 34

ESP32 ESP-IDF 工具链没配好 是什么意思，怎么解决？

Accepted Answer

环境变量和 Python 虚拟环境没生效，命令行找不到 idf.py / cmake / python。 每个新终端都要先执行 . $IDF_PATH/export.sh（Windows 是 export.bat）。 Windows 用户强烈建议用官方 ESP-IDF 安装器，它会自动处理路径和依赖。 工程路径不要有中文和空格，放在纯英文短路径下。 重新跑一次 install.sh 修复缺失的 Python 包。

ESP32 报错急救箱

为什么要做这个

错误速查表

⬇ 烧录 / 下载

⚡ 供电 / 复位

💥 运行崩溃

📶 Wi-Fi / 联网

📷 摄像头

🧠 内存 / PSRAM

🔄 OTA 升级

🔌 硬件 / 外设

🛠 编译 / 环境

连不上芯片：esptool 在等一个永远不来的回应	电脑能看见串口，但芯片当时没处在「下载模式」，所以烧录软件敲门没人应。这是 ESP32 排名第一的报错，九成不是芯片坏了。…
芯片启动模式不对（Wrong boot mode）	芯片上电时被采样到的 strapping 电平组合不是下载模式。本质是 GPIO0 在复位瞬间没有被稳定拉低。…
端口打不开：找不到、被占用、或没权限	操作系统层面就没连上，跟芯片无关。Windows 通常是驱动/占用，Linux 是权限，macOS 是驱动冲突。…
写到一半失败：能连上但烧不进	握手成功了，但真正写 Flash 时断掉。写 Flash 瞬间电流最大，几乎都是供电或线材扛不住。…
校验失败：烧进去的和文件对不上	写完后回读比对，内容不一致。说明写入过程受到了干扰，或者 Flash 地址/模式不对。…
固件太大，Flash / 分区装不下	编译出来的体积超过了分区表给 app 留的空间。开 OTA 时尤其常见——两个 app 槽位会把可用空间砍掉近一半。…

掉电检测触发（Brownout）	芯片检测到自己的电压掉到阈值以下，为了不出乱子直接把自个儿复位了。Wi-Fi 发射瞬间电流最大，最容易踩到。这不是代码的问题。…
看门狗复位：rst:0x10 / 0x7 / 0x8	芯片认为程序「卡死了」，于是自己重启。0x10 是开机阶段就卡住（bootloader 级），0x7/0x8 是某个任务长时间没喂狗（FreeRTOS 任务看门狗）。…
串口一堆乱码：多半只是波特率不对	ESP32 开机时 bootloader 会以 74880 波特率打一行信息，如果你的监视器设成 9600 或 115200，看到的就会是乱码——这是正常的，不是板子坏了。…

LoadProhibited：读了不该读的内存	程序去读了一块无效地址。最常见的是空指针、野指针、或者对象已经被释放还在用。看 EXCVADDR：如果是 0x00000000，基本就是解引用了 NULL。…
StoreProhibited：写了不该写的内存	往一个无效地址写数据。典型是往只读区域写、往 NULL 指针指向的成员写、或者数组越界写。…
IllegalInstruction：CPU 执行了一条不是指令的东西	程序计数器跳到了不该执行的地方。常见原因是函数指针坏了、栈被踩坏、或者把 Flash 引脚当成 GPIO 用了导致读不出指令。…
InstrFetchProhibited：取指令失败	CPU 想执行某个地址的指令，但那个地址不在有效的代码区里。PC 寄存器如果是 0 或一堆乱码，说明函数指针坏了。…
栈溢出：任务栈不够用了	这个任务用的栈超过了分配给它的大小，越界写把「金丝雀」踩了，系统立刻报出来。比起莫名其妙的崩溃，这其实是个好消息——它直接告诉你是哪个任务。…
任务看门狗：某个任务卡住不喂狗	空闲任务长时间没得到 CPU，说明有任务占着不放。日志会直接点名是哪个任务。…
abort / assert failed：代码主动调用异常中止	不是硬件问题，是代码或库主动抛出的中止。assert 后面那一行会写明文件名、行号和判断条件，这是最好查的一类崩溃。…
Cache disabled：在 Flash 操作期间访问了需要缓存的代码	擦写 Flash 或操作 SPI 时，Cache 会被临时关掉，这时候调用存放在 Flash 里的函数或中断就会崩。ESP-IDF 用 IRAM_ATTR 解决。…

搜不到热点 / 连不上 Wi-Fi	ESP32 只支持 2.4 GHz，不支持 5 GHz。如果路由器开了「双频合一」，或者你用的是手机 5G 热点，它根本看不见这个网络。…
Wi-Fi 密码对了但认证失败	密码正确但握手没过。常见于 WPA2/WPA3 混合模式、加密方式不兼容，或者信号质量差导致握手超时。…
MQTT 连不上 / 反复重连	网络通了但 MQTT 握手没过。看返回码：rc=-2 是超时（网络层），rc=4/5 是用户名密码错，rc=2 是 client id 被拒。…
TLS / HTTPS 握手失败	HTTPS 连接建立不起来。最常见的原因是设备系统时间不对导致证书「尚未生效」，其次是根证书缺失或过期。…

摄像头初始化失败（Camera probe failed）	ESP32 通过 SCCB（类 I2C）跟摄像头握手，没握上。排第一的原因永远是排线没插好，第二是代码里选错了板子型号。…
取帧失败 / 画面花屏绿屏	帧缓冲分配不出来，或者 DMA 搬运跟不上导致数据错位。花屏绿屏基本就是 PSRAM 没开或分辨率设太高。…

内存不足：分配失败	堆不够了。经典 ESP32 只有约 300 KB 可用 DRAM，开 Wi-Fi + TLS + 摄像头很容易见底。…
PSRAM 初始化失败	芯片没找到外挂的 PSRAM。可能是模组本来就没有 PSRAM，也可能是配置开了但硬件不支持，或者引脚被占用。…
DRAM 溢出：全局变量/static 太多	链接阶段就失败了，说明全局变量和 static 变量加起来超过了可用 DRAM。这类错误在编译时就暴露，比运行时崩溃好处理。…

ADC2 与 Wi-Fi 冲突：读数全是错的	ESP32 经典款的 ADC2 通道被 Wi-Fi 驱动占用，Wi-Fi 一开 ADC2 就读不准。这不是代码 bug，是硬件架构决定的。…
I²C 通信失败：设备不应答	主机发了地址但从机没拉低 SDA 应答。多半是地址不对、没接上拉电阻、或者设备根本没上电。…
Strapping 脚电平不对：板子起不来或反复重启	上电瞬间被采样的那几个脚（GPIO0/2/5/12/15）决定了芯片怎么启动。外接电路如果把它们拉成了错误电平，板子就会表现出各种诡异症状——最典型的是 GPIO12 被拉高导…
深度睡眠叫不醒 / 立刻醒来	进深睡后要么醒不来，要么刚睡就醒。前者通常是唤醒源没配对，后者通常是唤醒引脚当前就处在触发电平上。…

头文件找不到：库没装或路径不对	编译器找不到 #include 的那个头文件。Arduino 里是库没装，ESP-IDF 里是组件没加进 CMakeLists。…
API 变了：示例代码和新版库对不上	这是「网上抄的代码跑不起来」最常见的原因。ESP32 Arduino core 从 2.x 升到 3.x 时改了不少 API，旧示例直接编译不过。…
ESP-IDF 工具链没配好	环境变量和 Python 虚拟环境没生效，命令行找不到 idf.py / cmake / python。…