常见故障排查指南
按「现象 → 原因 → 处理」组织，覆盖烧录、网络、OTA、Web、外设初始化等高频问题。
1. 烧录与启动
1.1 ESP32-C3 烧录后卡在 boot:0x4/0x5 DOWNLOAD
- 原因：USB CDC 版 C3 复位时序问题（DTR/RTS 脉冲让芯片停留在下载模式），或串口复位电路强制进入下载模式。
- 处理：
- 复位时保持
DTR=False再脉冲 RTS（esptool--before default_reset --after hard_reset）； - 无效则物理重插 USB（最常见有效手段）；
- 设备完全不被 Windows 枚举（设备管理器出现幽灵设备）→ 换数据线/换 USB 口。
- 复位时保持
1.2 ESP32-C6 启动后串口完全静默
- 原因：外设配置占用了 GPIO16/17（C6 的 UART0 控制台 TX/RX）。
pinMode(16, OUTPUT)会切断串口 TX——日志全丢但设备其实仍在运行。 - 处理：检查
include/core/ChipConfig.h保留引脚列表，勿将 GPIO12-17/24-30 分配给外设。
1.3 ESP32-C6 外设初始化触发 panic
- 原因：C6 可用 GPIO 仅 0-23（
CHIP_MAX_GPIO=23），GPIO24-30 是封装内 Flash/PSRAM SPI，配置即 panic。 - 处理：确认外设引脚配置在 0-23 合法范围内。
1.4 COM 口被占用，烧录失败
- 原因：串口监视器、浏览器串口工具或其他 PlatformIO 进程占用。
- 处理：确认端口所属任务后协调退出；不要终止其它任务或删除构建锁。
1.5 烧录后页面错乱 / 登录后空白 / 登录异常
- 原因：只烧了固件或只烧了文件系统，新旧资源不匹配；或误用了被锁定的
data/www历史文件。 - 处理：核对固件与Web摘要和接口兼容，按范围选择应用或仅Web更新并保全非Web文件；不默认全量烧录；文件系统一律使用
.pio/fs-staging/run-*生成的干净 staging，不要直接用data/www。
2. 网络与访问
2.1 设备连了 WiFi 但找不到 IP
- 串口启动日志会打印分配的 IP；
- STA 模式可通过 mDNS 域名（如
fastbee.local）访问； - 也可查路由器 ARP/DHCP 客户端表。
2.2 WiFi 凭据正确，设备却只在 192.168.4.1（AP）可达
- 可能原因：STA连接失败后自动回退、实际加载的SSID为空，或网络JSON/备份加载失败后使用NVS旧值。当前实现优先成功加载的LittleFS配置，不能按“NVS优先”判断。
- 处理：
- 先读取已有启动/网络日志，区分JSON加载、NVS回退和STA连接失败；固件在WiFi方式且SSID非空时会把持久AP选择修正为STA，但后续连接仍可能失败。
- 保全身份和配置，通过已可用的管理入口核对SSID、认证与网络设置；不要为怀疑NVS旧值直接擦除整个NVS分区。
- 需要串口离线恢复时，先确认设备和分区并备份原镜像，再修复并核验LittleFS中的网络主文件/备份，见 网络模式切换机制。
连接设备AP可能改变运维电脑的默认路由，影响原有远程会话；选择本地管理或串口恢复前应确保仍能控制设备和保留原配置。
2.3 Web 访问超时或 ERR_CONNECTION_RESET
- 先看串口是否在重启循环；
- 若在重启：确认文件系统来自当前环境的干净 staging，且 Flash/PSRAM 与
-Env匹配；观察串口的Severe web memory pressure和堆趋势； - 若 heap 稳定：检查 TCP 连接数是否打满（默认连接预算有限，关闭多余的 SSE/长连接页面）。
3. OTA 升级
3.1 OTA begin 返回 501 "No OTA partition"
4MB正式环境关闭OTA，路由通常404；501说明编入路径但实际无升级槽。现有4MB分区不具备应用双槽OTA，不能为消除错误擅自改布局，见 分片表布局约束。
3.2 OTA begin 返回 503
内存门控拒绝（空闲 DRAM < 20KB），可重试：关闭其他占用页面/Web 连接后重试，响应带 Retry-After 头。
3.3 上传请求报 fetch failed / 连接中断
连接中断可能来自重启，也可能是实际写入失败。按OTA流程核对升级终态、设备身份、固件版本/摘要及重启原因；不能单凭恢复探活判定升级成功。
3.4 OTA 后所有 API 返回 401
重启会清空内存会话（AuthManager 为内存态），重新登录即可，属预期行为。
4. Web 界面
4.1 某些菜单项点不开 / 自动化测试报 "element is not visible"
发布镜像包含统一 Web 资源，菜单是否显示由 /api/system/capabilities 和 /api/system/status 的编译/运行时能力决定。先确认目标功能已编译、在“功能配置”中启用且没有被内存预算标记为 no-memory；自定义 Web 裁剪还需检查页面与 API 是否同步。
4.2 接口间歇性返回 503 "temporarily unavailable (memory pressure)"
设备处于 SEVERE 内存压力等级，重量级接口被门控熔断。减少并发请求/等待 Retry-After 后重试；长期出现请检查是否启用了过多高内存功能或存在内存泄漏（观察 [STATUS] 心跳的 heap 趋势）。
4.3 旧固件的WebGuard恢复死区（历史故障）
现象：高负载压测后
/api/*全部返回503 "Server low memory"，停止负载超过 1 小时仍不恢复；静态页面可访问、ping 正常。 以下为旧固件事故，不是当前候选实测。当前HealthMonitor已有针对中间死区的恢复路径，须核对部署版本及现场效果。历史原因：DRAM 卡在 WebMemoryGuard 恢复阈值（free8≥24KB）与 HealthMonitor CRITICAL 自愈重启阈值（无 PSRAM 机型 8KB）之间的死区，既不能自动解除熔断，也不触发 90s 安全重启；
/api/system/restart同样被熔断拦截，无远程恢复路径。处理：先保留当前状态、原始失败和配置；恢复/复位须在授权范围内，不能通过重启抹掉长稳失败。
断电前可先尝试串口 RTS 复位脉冲（pyserial 打开串口发 0.15s RTS 脉冲：
s.dtr=False; s.rts=True; sleep(0.15); s.rts=False）。预防：无 PSRAM 机型（如 F4R0/C3/C6）避免高频率长时间压测，soak 建议-DelayMs 1500起步。
5. 串口日志速查
| 日志片段 | 含义 |
|---|---|
[BOOT] Platform ready! | 启动完成，平台就绪 |
Mode: AP / Mode: STA | 当前网络模式 |
>>> AP fallback ... | STA 失败已回退 AP（自动探测恢复中） |
auto-correct AP->STA | 启动智能修正：AP 改回 STA |
ota_success + rst:0xc (SW_CPU) | OTA 成功并重启 |
[RESTART] Reason: ... | 计划内重启原因 |
Severe web memory pressure | Web 内存严重不足，警惕重启/WiFi 掉线 |