ESPHome 核心配置

在此您可以指定 ESPHome 创建固件所需的一些核心信息。最重要的是，这是配置中您指定节点名称的部分。

# 示例配置项
esphome:
    name: livingroom
    comment: 客厅 ESP32 控制器
    area: 客厅

配置变量

• name (Required, string): 节点的名称。它 在您的 ESPHome 网络中应该始终是唯一的。只能包含小写 字符、数字和连字符，默认长度最多为 24 个字符，如果 name_add_mac_suffix 为 false 则最多 31 个字符。 请参阅 更改 ESPHome 节点名称。

• friendly_name (Optional, string): 此名称会发送到前端，并被 Home Assistant 用作 集成和设备名称。需要时它还会作为实体名称的前缀。 虽然是可选的，但不设置它可能导致 Home Assistant 中的 名称不够直观，体验不够完善。设置 friendly_name 有助于保持清晰、 一致，并更易于管理。

• area (Optional, string 或 区域配置): 此设备的区域配置。这会发送到 Home Assistant 以指定设备属于哪个区域/位置。可以是简单的字符串（例如 "客厅"）或带有 id 和 name 的结构化格式。

高级选项：

• build_path (Optional, string): 自定义 ESPHome 存储 节点构建文件的路径。默认情况下，ESPHome 将其用于构建 固件的 PlatformIO 项目放在 .esphome/build/<NODE>（或如果指定了 ESPHOME_BUILD_PATH 环境变量，则放入该路径）目录， 但您可以使用此选项自定义此行为。官方 Docker 镜像会自动使用 /build 文件夹作为默认路径（如果挂载到该路径）。

• platformio_options (Optional, mapping): 传递给 PlatformIO 的 platformio.ini 文件的额外选项。请参阅 platformio_options。

• environment_variables (Optional, mapping): 构建过程中设置的环境变量。 请参阅 environment_variables。

• includes (Optional, list of files): 要包含在（自动生成的）main 文件中的 C/C++ 文件列表。 此列表中的路径相对于 YAML 配置文件所在的目录或 <...> 包含。 请参阅 includes。

• includes_c (Optional, list of files): 与 includes 相同，但用于需要 C 链接的文件。所有包含 都将被包装在 extern "C" {} 中。请参阅 includes。

• libraries (Optional, list of libraries): 要包含在项目中的库列表。请参阅 libraries。

• comment (Optional, string): 关于此节点的额外文本信息。仅在 UI 中显示。

• name_add_mac_suffix (Optional, boolean): 将设备 MAC 地址的最后 3 个字节以 <name>-aabbcc 的形式追加到名称后面。默认为 false。 请参阅 将 MAC 地址作为后缀添加到设备名称。

• project (Optional): ESPHome 创建者项目信息。请参阅 项目信息。

  • name (Required, string): 项目名称
  • version (Required, string): 项目版本
  • on_update (Optional, Automation): 当设备固件更新时要执行的自动化。 这会将上面的 version 字段与先前固件中的 version 进行比较， 只要 name 匹配。固件首次运行时，version 会存储在闪存中以供将来比较。

• min_version (Optional, string): 编译此配置所需的最低 ESPHome 版本。 请参阅 最低 ESPHome 版本。

• compile_process_limit (Optional, int): 同时运行的最大编译进程数。 默认为 CPU 核心数，这也是您可以设置的最大值。

• debug_scheduler (Optional, boolean): 如果设置，调度程序将在 DEBUG 日志级别打印有关计划任务的调试信息。

• areas (Optional, 区域配置 列表): 可被设备引用的额外区域。

• devices (Optional, 子设备 列表): 用于将实体分组的子设备。

自动化：

• on_boot (Optional, Automation): 节点启动时 要执行的自动化。请参阅 on_boot。

• on_shutdown (Optional, Automation): 节点关闭前 要执行的自动化。请参阅 on_shutdown。

• on_loop (Optional, Automation): 每次 loop() 迭代 要执行的自动化。请参阅 on_loop。

on_boot

此自动化将在 ESP 启动时触发。默认情况下，它在其他所有内容 都已设置完成后执行。但您可以使用 priority 参数更改此行为。

esphome:
  # ...
  on_boot:
    - priority: 600
      then:
        - switch.turn_off: switch_1

配置变量

• priority (Optional, float): 执行自定义初始化代码的优先级。较高的值 表示较高的优先级，因此您的代码会更早执行。请注意这是 ESPHome 内部 值，任何更改都不会被标记为破坏性更改。默认为 600。优先级（您也可以使用它们之间的任何值）：

  • 800.0: 这是执行所有关键组件硬件初始化的地方。例如将开关 设置为初始状态。

  • 600.0: 这是大多数传感器设置的地方。

  • 250.0: 在此优先级，WiFi 被初始化。

  • 200.0: 网络 connections 如 MQTT/原生 API 在此优先级设置。

  • -100.0: 在此优先级，几乎所有内容应该都已初始化。

• 请参阅 自动化。

on_shutdown

此自动化将在 ESP 即将关闭时触发。关闭通常由 过多的 WiFi/MQTT 连接尝试、应用空中下载更新或通过 深度睡眠 引起。

NOTE

不能保证在此自动化触发时所有组件都处于连接状态。例如， MQTT 客户端可能已经断开连接。对于需要特定关闭顺序的用例，请查看 priority 参数。

esphome:
  # ...
  on_shutdown:
    - priority: 700
      then:
        - switch.turn_off: switch_1

配置变量

• priority (Optional, float): 执行自定义关闭代码的优先级。较高的值 表示较高的优先级，对于关闭触发器，这意味着代码执行更晚。 优先级主要用于组件的初始化顺序。这些组件的关闭按相反顺序处理，使得例如传感器 (600) 在它们依赖的硬件组件 (800) 之前关闭。 请注意这是 ESPHome 内部值，任何更改都不会被标记为破坏性更改。 默认为 600。有关优先级值，请参阅 on_boot 部分中的列表。

• 请参阅 自动化。

on_loop

此自动化将在每次 loop() 迭代时触发（通常大约每 16 毫秒）。

esphome:
  # ...
  on_loop:
    then:
      # 做一些事情

platformio_options

PlatformIO 在其 platformio.ini 文件中支持许多选项。使用 platformio_options 参数，您可以告诉 ESPHome 将哪些选项传递到 PlatformIO 文件的 env 部分 （注意您也可以通过手动编辑 platformio.ini 文件来做到这一点）。

您可以在此处查看 PlatformIO 选项的完整列表：https://docs.platformio.org/en/latest/projectconf/section_env.html

# 示例配置项
esphome:
  # ...
  platformio_options:
    upload_speed: 115200
    board_build.f_flash: 80000000L

environment_variables

使用 environment_variables 选项，您可以设置在编译过程中可用的环境变量。当您需要将配置传递给构建脚本、自定义库 或 PlatformIO 构建环境时，这很有用。

# 示例配置项
esphome:
  # ...
  environment_variables:
    HTTP_PROXY: "http://user:pass@10.10.1.10:3128/"
    PLATFORMIO_SETTING_ENABLE_PROXY_STRICT_SSL: "false"

NOTE

此处设置的环境变量仅在构建过程中可用。它们不会影响 设备的运行时行为。

includes

使用 includes 您可以在生成的 PlatformIO 项目中包含源文件。 使用此选项声明的所有文件在每次编译时都会复制到项目中。

您可以随时查看生成的 PlatformIO 项目（.esphome/build/<NODE>）来了解 正在发生什么 - 如果您愿意，您甚至可以将包含文件直接复制到 src/ 文件夹。 includes 选项只是一个为您完成此操作的辅助选项。

# 示例配置项
esphome:
  # ...
  includes:
    - my_switch.h
    - <mylib.h>

此选项根据包含文件指向的内容而行为不同：

• 如果包含字符串写成 <mylib> 或 "<mylib>"，则将 #include <mylib> 添加到 main.cpp 文件的开头。

• 如果包含字符串指向目录，则整个目录树被复制到 src/ 文件夹。

• 如果包含字符串指向头文件（.h, .hpp, .tcc），它会被复制到 src/ 文件夹 并包含在 main.cpp 文件中。这样 lambda 代码可以访问它。

• 如果包含字符串指向常规源文件（.c, .cpp），它会被复制到 src/ 文件夹 并编译到二进制文件中。这样可以提供头文件中类和函数的实现。

libraries

libraries 选项允许您在 PlatformIO 项目中包含库。这些库随后将被 编译到生成的固件中，并可能被 lambda 使用。

# 示例配置项
esphome:
  # ...
  libraries:
    # 来自 PlatformIO 的库
    - espressif/esp32-camera

    # Arduino 附带的库
    - Wire

    # 使用组件使用的库的 git 版本
    - Improv=https://github.com/improv-wifi/sdk-cpp.git#v1.0.0

此选项最常见的用法是包含 PlatformIO 注册表 中可用的第三方库。它们可以通过在此选项下列出其名称来添加。也可以使用 特定版本，或从文件或 git 仓库获取库。ESPHome 接受与 lib_deps 选项相同的语法。

使用 <name>=<source> 语法，可以覆盖由 ESPHome 组件之一自动添加的库所使用的版本。这在开发过程中使 ESPHome 使用库的自定义分支时很有用。

默认情况下，ESPHome 不在项目中包含任何库。这意味着与 Arduino 捆绑的库， 如 Wire 或 EEPROM，不可用。如果您需要使用它们，应该在此选项下 手动列出它们。如果它们被其他库使用，它们应该在需要它们的库之前列出。

首选项组件

此组件用于在闪存中存储数据，这些数据在设备重启后会保留，例如 灯光的最新状态或设备消耗的累积能量。

# 示例配置项
preferences:
  flash_write_interval: 1min

配置变量

• flash_write_interval (Optional, Time): 自定义数据刷新到 闪存的频率。此设置有助于防止组件的快速变化被快速 写入闪存并使其磨损。默认为 1min。设置为 never 可禁用此功能。

由于所有设备的闪存写入周期数量有限，此设置有助于减少由于快速变化的组件而导致的闪存写入次数。过去，当 light、switch、fan 和 globals 等组件 发生变化时，状态会立即提交到闪存。这样做的结果是这些 组件的最后状态在断电时总是会恢复到最后状态，但这可能会在 这些组件快速变化时快速损坏闪存。

因此，实现了一个安全功能来减轻闪存写入周期数量有限导致的问题， 状态首先存储在内存中，然后在 flash_write_interval 过去后刷新到闪存。这 导致更少的闪存写入，保护闪存健康。

可以通过将 flash_write_interval 设置为 0s 来修改此行为，以尽快将更改提交到闪存， 但请注意，这可能导致闪存磨损增加并缩短设备寿命！

对于 ESP8266，还必须将 restore_from_flash 设置为 true 才能将状态写入闪存。

更改 ESPHome 节点名称

想要更改节点名称或其在网络中的地址？ 您可以使用 WiFi 配置 的 use_address 选项来实现。

将 YAML 中的设备名称或地址更改为新值，并另外 设置 use_address 指向旧地址，如下所示：

# 步骤 1. 将名称从 test8266 更改为 kitchen
esphome:
  name: kitchen
  # ...

wifi:
  # ...
  use_address: test8266.local

现在将更新的配置上传到设备。作为第二步，您现在需要从配置中删除 use_address 选项，以便后续上传能够再次工作 （否则它将尝试上传到旧地址）。

# 步骤 2
esphome:
  name: kitchen
  # ...

wifi:
  # ...
  # 删除或注释掉 use_address
  # use_address: test8266.local

同样的过程也可以用于更改设备的静态 IP。

将 MAC 地址作为后缀添加到设备名称

使用 name_add_mac_suffix 允许创建者在工厂使用单一固件配置多个设备，同时仍然 为客户安装提供唯一标识。

NOTE

如果终端用户将来想要 OTA 更新设备，他们将需要创建单独的 YAML 配置文件。创建者可以通过提供 dashboard_import URL 来促进此过程。这使他们能够在上游提供新功能时轻松更新设备。

项目信息

这允许创建者将项目名称和版本添加到编译代码中。目前仅 通过日志记录器、mDNS 和通过原生 API 的 device_info 响应公开。名称 格式应为 author_name.project_name。

# 示例配置
esphome:
  ...
  project:
    name: "jesse.leds_party"
    version: "1.0.0"

最低 ESPHome 版本

这允许 YAML 文件指定编译所需的最低 ESPHome 版本。 这对于发布包可能仅使用新版 ESPHome 中可用的功能的 包很有用。这允许显示更友好的错误消息。

# 示例配置
esphome:
  min_version: 2025.11.0

区域配置

区域帮助您按位置在 Home Assistant 中组织设备。ESPHome 支持两种区域配置格式：

简单字符串格式：

esphome:
  name: my-device
  area: "客厅"

结构化格式：

esphome:
  name: my-device
  area:
    id: living_room
    name: "客厅"

简单字符串格式便于基本用例，您只想将 ESP 设备分配到一个房间。 结构化格式在使用子设备时推荐使用，因为它允许您通过 ID 引用区域。

配置变量（结构化格式）：

• id (Required, string): 区域的唯一标识符。
• name (Required, string): 区域的显示名称。

子设备

ESPHome 支持在单个 ESP 控制器内创建子设备。这允许您将实体分组为 在 Home Assistant 中单独显示的逻辑设备。这在以下情况下特别有用：

• 一个 ESP 作为多个物理设备的集线器/网关（RF 网桥、Modbus 设备等）
• 单个 ESP 控制多个区域或房间
• 您希望在 Home Assistant 中更好地组织实体

配置变量

• id (Required, string): 设备的唯一标识符。
• name (Required, string): 设备的显示名称。
• area_id (Optional, string): 引用在 areas 中定义的区域 ID。

示例：RF 网桥网关

# ESP32 作为多个 433MHz 设备的 RF 网桥
esphome:
  name: rf-bridge
  area: "杂物间"  # ESP 设备区域的简单字符串格式

  devices:
    - id: front_door_device
      name: "前门传感器"
      area_id: entrance_area
    - id: kitchen_motion_device
      name: "厨房运动传感器"
      area_id: kitchen_area
    - id: garage_door_device
      name: "车库门"
      area_id: garage_area

  areas:
    - id: entrance_area
      name: "入口"
    - id: kitchen_area
      name: "厨房"
    - id: garage_area
      name: "车库"

# 每个 RF 设备在 HA 中显示为单独的设备
binary_sensor:
  - platform: remote_receiver
    name: "前门"
    device_id: front_door_device
    rc_switch_raw:
      code: '101010110101'

  - platform: remote_receiver
    name: "厨房运动"
    device_id: kitchen_motion_device
    rc_switch_raw:
      code: '110011001100'

示例：多区域控制器

esphome:
  name: multi-room-controller

  devices:
    - id: living_room_device
      name: "客厅控制器"
      area_id: living_area
    - id: kitchen_device
      name: "厨房控制器"
      area_id: kitchen_area

  areas:
    - id: living_area
      name: "客厅"
    - id: kitchen_area
      name: "厨房"

sensor:
  - platform: dht
    pin: GPIO5
    temperature:
      name: "温度"
      device_id: living_room_device
    humidity:
      name: "湿度"
      device_id: living_room_device