Logger 组件

logger 组件会自动将所有日志消息通过串口以及 MQTT 主题（如果配置中有 MQTT 客户端）输出。默认情况下，会显示所有严重级别为 DEBUG 或更高的日志。提高日志级别（例如改为 INFO 或 WARN）有助于提升应用程序的性能并减小内存占用。

NOTE

日志消息的”严重级别”表示消息的重要性，即它有多关键。严重级别在日志级别一节中定义。

# 示例配置条目
logger:
  level: DEBUG

配置变量

baud_rate (可选, int): 用于串行 UART 端口的波特率。默认为 115200。设置为 0 可禁用通过 UART 记录日志。
level (可选, string): 全局日志级别。任何严重级别更低的日志消息都不会显示。默认为 DEBUG。
initial_level (可选, string): 初始日志级别，可在运行时更改。默认为与 level 相同的值。
logs (可选, mapping): 手动设置某个特定组件或标签的日志级别。参见手动日志级别了解更多信息。
runtime_tag_levels (可选, boolean): 启用运行时按标签更改日志级别。当配置了 logs 或在 logger.set_level 中使用 tag 参数时，此选项会自动启用。仅当从 lambda 或外部组件中调用 set_log_level() 时才需要手动启用。默认为 false（按需自动启用）。
id (可选, ID): 手动指定用于代码生成的 ID。

高级设置：

tx_buffer_size (可选, int): 用于日志消息的缓冲区大小。如果遇到内存问题，可减小此值。默认为 512。
task_log_buffer_size (可选, int): 仅限 ESP32、LibreTiny 和 nRF52：任务日志消息的内部线程安全环形缓冲区大小。这可以防止多个线程同时尝试记录日志时发生 API 断开连接。设置为 0 可禁用日志缓冲区。默认为 768B。
hardware_uart (可选, string): 用于记录日志的硬件 UART。默认值因所使用的具体处理器/芯片和框架而异。参见下表。
esp8266_store_log_strings_in_flash (可选, boolean): 仅限 ESP8266。 决定日志格式字符串存放位置的编译时设置。当为 true（默认）时，它们通过 PROGMEM 存放在闪存中；当为 false 时，它们会被复制到 RAM 中，这将显著消耗 ESP8266 有限的 RAM。这不影响运行时日志输出或日志级别，也没有闪存磨损的顾虑（程序闪存只在 OTA 期间写入）。除非你有特定的理由，否则请保持默认设置。
on_message (可选, Automation): 当有消息要记录时执行的操作。变量 int level、const char* tag 和 const char* message 可供 lambda 处理。
deassert_rts_dtr (可选, boolean): 使 ESPHome 在打开串行日志连接后，依次将 DTR 和 RTS 置为无效（低电平）。默认为 false。许多 ESP 开发板使用这些信号来复位芯片或进入引导加载程序模式，设置此选项的效果将是在打开串口后将芯片复位到应用程序模式，从而确保捕获引导过程中的所有日志消息。注意：由于 RTS/DTR 通常是低电平有效信号，取消断言（Deassert）通常指 TTL 高电平。
wait_for_cdc (可选, boolean): 在开始设置前等待 CDC 端口（10 秒超时）。仅适用于 nRF52。
early_message (可选, boolean): 显示早期调试信息，例如启动原因。仅适用于 nRF52。

硬件 UART

logger 组件使用特定于平台的硬件 UART 进行串行日志记录。例如，ESP32 有三个硬件 UART，全部可用于发送和接收。ESP8266 只有两个硬件 UART，其中一个仅用于发送。ESP8266 的 UART0 也可以在需要将 GPIO1 和 GPIO3 用于其他用途时， “交换”到 CTS/RTS 引脚上的 TX/RX。

请注意，许多常见开发板的 USB 转串口适配器固定使用 UART0 所用的默认 GPIO，因此如果你使用任何其他配置，将无法通过板载 USB 获取日志消息。

默认 UART GPIO 引脚

变体	`UART0`	`UART0_SWAP`	`UART1`	`UART2`	`USB_CDC`	`USB_SERIAL_JTAG`
ESP8266	TX: 1, RX: 3	TX: 15, RX: 13	TX: 2, RX: N/A	N/A	N/A	N/A
ESP32	TX: 1, RX: 3	N/A	TX: 10, RX: 9	TX: 17, RX: 16	N/A	N/A
ESP32-C3	TX: 21, RX: 20	N/A	Undefined	N/A	N/A	18/19
ESP32-C5	TX: 10, RX: 11	N/A	Undefined	N/A	N/A	13/14
ESP32-C6	TX: 16, RX: 17	N/A	Undefined	N/A	N/A	12/13
ESP32-C61	TX: 5, RX: 4	N/A	Undefined	N/A	N/A	12/13
ESP32-P4	TX: 37, RX: 38	N/A	TX: 10, RX: 11	N/A	N/A	24/25
ESP32-S2	TX: 43, RX: 44	N/A	TX: 17, RX: 18	N/A	19/20	N/A
ESP32-S3	TX: 43, RX: 44	N/A	TX: 17, RX: 18	Undefined	19/20	19/20
NRF52	pins varies by board	N/A	pins varies by board	Undefined	D+/D-	N/A

Undefined（未定义）表示 logger 组件目前无法使用此硬件 UART。

默认硬件接口

由于可用的开发板和处理器/芯片种类繁多，我们为日志记录选择了多种不同的默认硬件接口。许多基于 ESP32 变体（如 C3、S2 和 S3）的新开发板使用 ESP 的板载 USB 硬件外设，而基于较旧处理器（如原始 ESP32 或 ESP8266）的开发板则继续使用 USB 转串口桥接 IC 进行通信。

变体	Interface（接口）
ESP8266	`UART0`
ESP32	`UART0`
ESP32-C3	`USB_SERIAL_JTAG`
ESP32-C5	`USB_SERIAL_JTAG`
ESP32-C6	`USB_SERIAL_JTAG`
ESP32-C61	`USB_SERIAL_JTAG`
ESP32-P4	`USB_SERIAL_JTAG`
ESP32-S2	`USB_CDC`
ESP32-S3	`USB_SERIAL_JTAG`
RP2040	`USB_CDC`
NRF52	`USB_CDC`

日志级别

可能的日志级别（按严重程度排序）：

级别	颜色	描述
`NONE`		不记录任何消息。
`ERROR`	红色	只记录错误。错误会妨碍 ESP 正常工作。
`WARN`	黄色	记录警告和错误。警告是可恢复的问题，如无效的传感器读数。
`INFO`	绿色	记录错误、警告和信息消息。
`DEBUG`（默认）	青色	记录直到调试级别的所有内容。包括初始化细节和一般状态消息。
`VERBOSE`	灰色	类似于 debug，但还包括传感器状态变化和其他频繁消息。
`VERY_VERBOSE`	白色	所有内部消息，包括通过 I²C、SPI 和 UART 总线流动的数据。

对性能的影响

你选择的日志级别直接影响设备性能。打印出的每条日志消息都需要 CPU 时间进行格式化并通过串口和/或网络传输，这会占用处理其他任务的时间，例如读取传感器、处理网络通信和运行自动化。

DEBUG（默认）： 适合生产使用。自 ESPHome 2026.4.0 起，状态变化消息（传感器读数、二进制传感器更新等）已从 DEBUG 移至 VERBOSE，从而显著降低了默认级别下的日志开销。在 2026.4.0 之前，DEBUG 会产生多得多的输出，并对性能有明显影响，因此较旧的指南可能推荐使用 INFO——对于当前版本来说，这通常已不再必要。
INFO / WARN： 推荐用于对性能敏感或对时序要求严格的设备（例如使用精确 PWM 调光、红外通信或高频传感器轮询的设备）。减少日志输出可以为对时间敏感的操作释放 CPU 资源。
VERBOSE / VERY_VERBOSE： 仅供短期调试会话使用。这些级别会产生大量输出，会拖慢设备速度、导致网络超时并引发连接不稳定。不要长期让设备以这些级别运行。当这些级别处于活动状态时，ESPHome 会在启动时记录一条警告作为提醒。

WARNING

VERBOSE 和 VERY_VERBOSE 不适合长期使用。它们用于在调试会话期间诊断特定问题。让设备持续以这些级别运行会降低性能并可能引起不稳定。问题解决后请切换回 DEBUG 或更低的级别。

手动设置特定标签的日志级别

如果某个组件刷屏了大量的日志，而你想调整它的日志级别，你可以通过识别其标签（tag）在配置中设置它的级别。

示例：全局使用 verbose，但减少 MQTT 的噪音：

logger:
  level: VERBOSE
  logs:
    mqtt.component: DEBUG
    mqtt.client: ERROR

NOTE

使用 logs 时，会自动启用运行时按标签设置日志级别的支持。当此功能被禁用（未配置 logs 时的默认情况）时，logger 会被优化以获得更好的性能并减少内存占用。

level 选项控制日志语句中哪些会被编译进固件。你不能将某个标签设置为比全局级别更详细的级别，因为严重级别低于该级别的日志语句不会被编译进来。不过，你可以使用 initial_level 抑制它们，并为特定标签启用：

logger:
  level: VERBOSE
  initial_level: ERROR
  logs:
    wifi: VERBOSE

在这里，VERBOSE 日志会被编译进来，但不会显示（因为 initial_level: ERROR）。但是，wifi 标签已启用 VERBOSE 级别，并会显示。

`logger.log` 操作

向日志中打印一条格式化消息。

在 format 选项中，你可以使用 printf 风格的格式化（参见格式化文本）。

on_...:
  then:
    - logger.log: "Hello World"

    # 格式化：
    - logger.log:
        format: "The temperature sensor reports value %.1f and humidity %.1f"
        args: [ 'id(temperature_sensor).state', 'id(humidity_sensor).state' ]

配置选项：

format (必选, string): 使用 printf 风格的消息格式。
args (可选, list of lambda): 格式化消息的可选参数。
level (可选, string): 打印消息时使用的日志级别。默认为 DEBUG。
tag (可选, string): 打印消息时使用的标签（在日志中显示在消息前面）。默认为 main。

`logger.set_level` 操作

在运行时设置日志级别。只能将日志级别设置为不比全局日志级别更高的级别（即不能比全局级别更不严重）。

level (必选, string): 要设置的新日志级别。
tag (可选, string): 要为其设置日志级别的标签。如果未设置，则设置全局日志级别。

on_...:
  then:
    - logger.set_level: INFO

    - logger.set_level:
        level: DEBUG
        tag: mqtt.client

NOTE

在 logger.set_level 中使用 tag 参数时，会自动启用运行时按标签设置日志级别的支持。如果你需要直接从 lambda 或外部组件调用 set_log_level()，则必须在 logger 配置中手动启用 runtime_tag_levels: true。

Logger 自动化

`on_message`

当向日志添加新消息时触发此自动化。在 lambdas 中，你可以通过 message（const char *）、level（int）和 tag（const char *）从触发器获取消息、日志级别和标签。

logger:
  # ...
  on_message:
    level: ERROR
    then:
      - mqtt.publish:
          topic: some/topic
          payload: !lambda |-
            return "Triggered on_message with level " + to_string(level) + ", tag " + tag + " and message " + message;

NOTE

在 on_message 触发器中无法进行日志记录。你不能在此自动化中使用 logger.log 操作和 ESP_LOGx 日志宏。

另请参阅

UART 总线
Logger 选择器
故障排查 - 用于调试崩溃和启动失败的故障排查指南
API 参考：logger.h

Logger 组件

配置变量

硬件 UART

默认 UART GPIO 引脚

默认硬件接口

日志级别

对性能的影响

手动设置特定标签的日志级别

logger.log 操作

logger.set_level 操作

Logger 自动化

on_message

另请参阅

`logger.log` 操作

`logger.set_level` 操作

`on_message`