安全模式

有时硬件和/或软件的行为不符合预期。ESPHome 支持”安全模式”来帮助从 重复的启动失败/重启循环中恢复。在指定次数（默认是十次）的启动失败后，可以 调用安全模式；在此模式下，除了串行日志、网络（Wi-Fi 或以太网）和 OTA 组件外，所有组件都会被禁用。在大多数情况下，这将暂时缓解问题，让你有机会纠正它，也许可以通过 上传一个新的二进制文件。

你还可以通过配置专用的 button 或 switch 组件，和/或通过连续按开发板上的复位按钮 num_attempts 次（参见下文）来强制调用安全模式。

# 示例配置条目
safe_mode:

配置变量

• disabled (可选, boolean): 设为 true 以禁用 safe_mode。Ota 会自动 设置安全模式；这允许在不需要时禁用它。

• boot_is_good_after (可选, Time): 在此时间之后启动被视为成功。 默认为 1min。

• num_attempts (可选, int): 在调用安全模式之前必须发生的启动尝试失败次数。 默认为 10。

• reboot_timeout (可选, Time): 在安全模式下等待多久后重启。 默认为 5min。

• storage (可选, string): 在哪里持久化启动尝试计数器。为以下之一：

  • flash：将计数器存储在闪存中。它可以在断电后幸存，但每次启动都会造成少量闪存磨损。
  • rtc：将计数器存储在 RTC 内存中。它可以在软件重启（重启、OTA 更新、崩溃）和深度睡眠后幸存， 但不能在断电后幸存，并且避免了闪存磨损。

  在 ESP32 上默认为 flash，在 ESP8266 上默认为 rtc。在没有 RTC 支持的存储的平台上 （RP2040 以及没有 RTC 内存的 ESP32-C2 和 C61 变体），只有 flash 可用，在这些平台上 rtc 会被拒绝。

  请注意，在原始 ESP32 上，按下硬件复位按钮（EN 引脚）也会清除 RTC 内存，因此它 算作断电而不是重启。在较新的变体（S3、C3、C6）上，RTC 内存在通过 USB 触发的芯片复位后可幸存。 安全模式本身不受影响：崩溃循环总是由软件复位组成，所有变体的 RTC 内存 都能在这些复位后幸存。

• on_safe_mode (可选, Automation): 调用安全模式时执行一次的操作。

WARNING

on_safe_mode 自动化旨在仅供恢复操作使用。

如上所述，在安全模式下，除了串行日志、网络（Wi-Fi 或以太网） 和 OTA 组件外，所有组件都会被禁用。

所有其他组件（例如显示屏和传感器）都会被禁用，无法使用。

safe_mode.mark_successful 操作

此操作将启动标记为成功，防止调用安全模式。这对于那些 读取传感器读数然后进入深度睡眠，而不是等待 boot_is_good_after 时间经过的设备很有用。

on_...:
  then:
    - safe_mode.mark_successful

在 ESP32 上重启到恢复应用

如果 safe_mode 检测到由于设备上的分区布局，OTA 更新不可能进行， 日志的配置部分将出现 OTA updates are impossible（OTA 更新不可能）消息，后面跟着建议的下一步操作。

如果找到了有效的恢复应用，但使用当前应用无法进行 OTA，则调用安全模式将自动重启到该应用。 根据恢复应用的功能，这可以允许你安装 OTA 更新并恢复被软砖化的设备。 恢复应用例如可以是 ESPHome 的旧版本或 Tasmota safeboot 应用。建议在 恢复你的设备的同时更新分区表， 以使未来的 OTA 更新成为可能。

另请参阅

• 安全模式按钮
• 安全模式开关
• 故障排查 - 用于调试崩溃和启动失败的故障排查指南
• API 参考：safe_mode.h