故障排除

本指南帮助您诊断和调试 ESPHome 设备问题，特别是崩溃和启动失败。无论您遇到随机重启、看门狗超时，还是需要分析堆栈跟踪，本指南都提供了捕获和理解崩溃数据的分步说明。

NOTE

本指南假设您已安装 ESPHome 并基本熟悉命令行。有关安装说明，请参阅安装 ESPHome。

从崩溃中获取堆栈跟踪

当您的 ESPHome 设备崩溃时，您可以获取解码的堆栈跟踪以帮助识别原因。这需要：

在本地编译固件（以拥有匹配的调试符号）
通过 USB 线缆连接设备以进行串行控制台访问
运行 logs 命令以捕获和解码崩溃

获取堆栈跟踪的步骤

本地编译：在本地机器上构建您的配置，以确保您拥有匹配的调试符号。

如果您使用 ESPHome Device Builder Web 界面：
- 点击设备旁边的溢出菜单（三个点）
- 选择 “Download YAML” 以获取您的配置文件
- 将其保存到本地目录
然后使用命令行界面（有关完整详情，请参阅 CLI 指南）：
Terminal window
```
esphome compile your-device.yaml
esphome upload your-device.yaml
```

NOTE

虽然您可以使用 OTA 进行上传，但下一步您仍需要 USB 连接来捕获崩溃输出，因此通过 USB 上传通常更方便。

通过 USB 连接：使用 USB 线缆将设备连接到计算机。设备必须通过串行控制台连接（而不是通过 WiFi/OTA）才能捕获崩溃输出。
监控日志：运行 logs 命令监控设备输出：
Terminal window
```
esphome logs your-device.yaml
```

等待崩溃：当设备崩溃时，ESPHome 将自动检测并解码堆栈跟踪。您将看到类似以下的输出：

[08:17:06]E (5906) task_wdt: Task watchdog got triggered. The following tasks/users did not reset the watchdog in time:
[08:17:06]E (5906) task_wdt:  - loopTask (CPU 0)
[08:17:06]E (5906) task_wdt: Tasks currently running:
[08:17:06]E (5906) task_wdt: CPU 0: esp_timer
[08:17:06]E (5906) task_wdt: CPU 1: IDLE1
[08:17:06]E (5906) task_wdt: Aborting.
[08:17:06]E (5906) task_wdt: Print CPU 0 (current core) backtrace

[08:17:06]Backtrace: 0x4013d30e:0x3ffbac20 0x4013d383:0x3ffbac40 0x4014b23e:0x3ffbac70
WARNING Found stack trace! Trying to decode it
WARNING Decoded 0x4013d30e: touch_ll_is_measure_done at /Users/bdraco/.platformio/packages/framework-espidf/components/hal/esp32/include/hal/touch_sensor_ll.h:505
      (inlined by) _touch_pad_read at /Users/bdraco/.platformio/packages/framework-espidf/components/driver/touch_sensor/esp32/touch_sensor.c:365
WARNING Decoded 0x4013d383: touch_pad_filter_cb at /Users/bdraco/.platformio/packages/framework-espidf/components/driver/touch_sensor/esp32/touch_sensor.c:108
      (inlined by) touch_pad_filter_cb at /Users/bdraco/.platformio/packages/framework-espidf/components/driver/touch_sensor/esp32/touch_sensor.c:98
WARNING Decoded 0x4014b23e: timer_process_alarm at /Users/bdraco/.platformio/packages/framework-espidf/components/esp_timer/src/esp_timer.c:456
      (inlined by) timer_task at /Users/bdraco/.platformio/packages/framework-espidf/components/esp_timer/src/esp_timer.c:482

解码的堆栈跟踪显示：

崩溃发生的具体函数名和源文件
源代码中的行号
导致崩溃的调用堆栈

NOTE

重要：您必须在捕获崩溃之前在本地编译并上传固件。调试符号必须与正在运行的固件匹配，堆栈跟踪才能正确解码。

常见问题

无解码输出：确保在捕获崩溃之前在本地编译并上传固件
无法连接：确保您使用的是 USB 数据线（而不是仅充电线）和正确的串行端口

替代方案：基于 Web 的堆栈跟踪解码器

如果您已有堆栈跟踪但需要解码，可以使用 ESP Stack Trace Decoder Web 工具：

下载 .elf 文件：从 ESPHome 仪表板，点击设备卡上的溢出菜单（三个点）并选择 “Download .elf file”

NOTE

.elf 文件必须来自生成当前设备上运行固件的同一编译。如果您在刷写后重新编译，调试符号将不匹配。
打开解码器：导航到 https://esphome.github.io/esp-stacktrace-decoder/
上传文件：
- 点击 “ELF File” 下的 “Choose File” 并选择您下载的 .elf 文件
- 将堆栈跟踪粘贴到文本区域
- 点击 “Decode Stack Trace”
查看结果：工具将解码地址并显示函数名、文件路径和行号

NOTE

此工具完全在您的浏览器中运行 - 不会向任何服务器发送数据，确保您的固件和调试信息保持私密。

调整日志级别进行调试

在排查 ESPHome 设备问题时，提高日志级别可以提供更详细的内部运行信息。这对于诊断特定组件问题或了解组件之间的数据流特别有用。

设置全局日志级别

要提高日志的全局详细程度，请在您的 Logger 配置中调整 level：

logger:
  level: VERBOSE  # 或 VERY_VERBOSE 获取最大详细信息

可用的日志级别从最低到最高详细程度：

NONE - 不记录任何消息
ERROR - 仅错误
WARN - 警告及以上
INFO - 信息消息及以上
DEBUG - 调试消息及以上（默认）
VERBOSE - 详细调试消息及以上
VERY_VERBOSE - 所有内部消息，包括数据总线流量

WARNING

使用 VERY_VERBOSE 可能会显著降低设备速度，并可能由于生成的日志消息量大而导致连接问题。仅用于短期调试会话。

ESP-IDF 框架日志级别

在 ESP32 上使用 ESP-IDF 框架时，您还可以调整框架的内部日志级别，以获取底层系统的更详细信息：

esp32:
  framework:
    type: esp-idf
    log_level: VERBOSE  # 框架日志级别

可用的 ESP-IDF 日志级别：NONE、ERROR（默认）、WARN、INFO、DEBUG、VERBOSE

特定组件日志级别

您还可以为特定组件配置日志级别，以减少噪音或获取单个组件的更多详情。请参阅 logger 手动标签特定日志级别文档了解详细信息和示例。

IMPORTANT

全局日志级别决定哪些消息被编译到二进制文件中。特定组件日志级别只能降低详细程度，不能提高到全局级别以上。例如，如果全局级别是 INFO，将组件设置为 DEBUG 将无效。

性能故障排除

如果您的设备遇到性能问题，例如：

响应时间慢
传感器读数丢失
连接问题
组件未按预期更新

Runtime Stats 组件可以帮助识别哪些组件消耗了最多的处理时间或阻塞了事件循环。请参阅 runtime_stats 文档了解详细的使用说明和示例。

另见

Logger 组件 - 配置日志级别和输出
Debug 组件 - 用于额外诊断的调试组件
运行时统计 - 性能分析和调试
安全模式 - 安全模式恢复指南
常见问题 - 常见问题解答