ESPHome配置文件完全指南：从基础语法到高级技巧

2026-02-05 05:51:45作者：余洋婵Anita

ESPHome is a system to control your ESP8266/ESP32 by simple yet powerful configuration files and control them remotely through Home Automation systems.

项目地址：https://gitcode.com/GitHub_Trending/es/esphome

引言：为什么ESPHome配置文件如此重要

你是否曾为物联网设备配置而烦恼？是否觉得传统固件开发门槛太高？ESPHome通过简单而强大的配置文件解决了这些痛点，让你无需深入C++编程就能轻松控制ESP8266/ESP32设备。本文将带你从基础语法到高级技巧，全面掌握ESPHome配置文件的精髓，让你能够快速构建稳定、高效的物联网设备。

读完本文后，你将能够：

理解ESPHome配置文件的核心结构和语法规则
掌握常用组件的配置方法和最佳实践
运用高级技巧如变量、模板和条件逻辑优化配置
解决常见的配置问题和调试技巧
通过实际案例构建复杂的物联网应用

配置文件基础：构建你的第一个ESPHome设备

文件结构与命名规范

ESPHome配置文件采用YAML（Yet Another Markup Language）格式，具有简洁易读的特点。典型的项目结构如下：

project/
├── device1.yaml    # 设备1配置文件
├── device2.yaml    # 设备2配置文件
└── packages/       # 可复用配置包
    ├── common.yaml
    └── sensor.yaml

配置文件命名建议使用小写字母、数字和连字符，例如 living-room-sensor.yaml。ESPHome核心配置逻辑在 esphome/config.py 中定义，负责解析和验证这些配置文件。

基础语法与数据类型

基本结构

一个完整的ESPHome配置文件包含以下核心部分：

esphome:
  name: mydevice
  platform: ESP8266
  board: d1_mini

wifi:
  ssid: "MyWiFi"
  password: "MyPassword"

sensor:
  - platform: dht
    pin: D2
    temperature:
      name: "Room Temperature"
    humidity:
      name: "Room Humidity"
    update_interval: 60s

logger:
api:
ota:

这个配置定义了一个基于ESP8266的DHT温湿度传感器，连接到WiFi并通过API提供数据。

数据类型

ESPHome配置支持多种数据类型，由 esphome/config_validation.py 负责验证：

类型	描述	示例
字符串	文本数据，通常不需要引号	`name: My Sensor`
整数	整数数值	`update_interval: 60`
浮点数	带小数点的数值	`offset: 0.5`
布尔值	`true` 或 `false`	`enabled: true`
列表	有序项目集合	`- platform: dht`
映射	键值对集合	`wifi: {ssid: "MyWiFi"}`
时间周期	带单位的时间值	`update_interval: 5min`
引脚	设备引脚标识	`pin: D2` 或 `pin: GPIO4`

时间周期支持的单位包括：ns（纳秒）、us（微秒）、ms（毫秒）、s（秒）、min（分钟）、h（小时）、d（天）。

注释

YAML使用 # 符号表示注释：

# 这是一行注释
sensor:
  - platform: dht  # 这是行内注释
    pin: D2

核心配置块解析

esphome块

esphome 块是配置文件的根节点，定义设备基本信息：

esphome:
  name: bedroom_sensor  # 设备名称，用于生成唯一标识符
  friendly_name: Bedroom Sensor  # 友好名称，用于显示
  platform: ESP32  # 平台类型，ESP8266或ESP32
  board: nodemcu-32s  # 开发板型号
  comment: "Temperature and humidity sensor for bedroom"  # 设备描述
  min_version: 2023.12.0  # 最低ESPHome版本要求
  on_boot:  # 启动时执行的操作
    priority: 600
    then:
      - logger.log: "Device started!"
  on_shutdown:  # 关闭时执行的操作
    then:
      - switch.turn_off: relay

平台和开发板的验证逻辑在 esphome/config_validation.py 中实现，确保选择的组合有效。

WiFi配置

WiFi配置负责连接到无线网络：

wifi:
  ssid: !secret wifi_ssid  # 通过secret获取SSID
  password: !secret wifi_password  # 通过secret获取密码
  manual_ip:  # 手动指定IP地址
    static_ip: 192.168.1.100
    gateway: 192.168.1.1
    subnet: 255.255.255.0
    dns1: 192.168.1.1
  reboot_timeout: 5min  # 连接失败后重启超时
  power_save_mode: LIGHT  # 省电模式
  fast_connect: true  # 快速连接到第一个匹配的SSID
  ap:  # 当主WiFi不可用时创建接入点
    ssid: "Bedroom Sensor Fallback"
    password: "fallbackpassword"

WiFi组件的实现位于 esphome/components/wifi 目录。

网络服务配置

ESPHome提供多种网络服务组件：

# 日志服务
logger:
  level: DEBUG  # 日志级别：DEBUG, INFO, WARNING, ERROR
  baud_rate: 0  # 禁用UART日志
  logs:
    sensor: INFO  # 传感器组件日志级别
    light: DEBUG  # 灯光组件日志级别

# API服务，用于与Home Assistant通信
api:
  encryption:
    key: "your-encryption-key"  # API加密密钥
  port: 6053  # API端口
  reboot_timeout: 15min  # API连接失败重启超时

# OTA更新
ota:
  password: "your-ota-password"  # OTA更新密码
  safe_mode: true  # 启用安全模式

# Web服务器
web_server:
  port: 80  # Web服务器端口
  auth:
    username: admin  # Web认证用户名
    password: admin  # Web认证密码

这些服务组件的实现可以在 esphome/components 目录中找到，如 logger、api 和 ota。

组件配置详解：打造你的智能设备

常用组件配置方法

ESPHome拥有丰富的组件生态系统，几乎涵盖了所有常见的物联网功能。这些组件的定义位于 esphome/components 目录中。

传感器组件

传感器组件用于读取物理世界的数据：

sensor:
  # DHT温湿度传感器
  - platform: dht
    pin: D2
    temperature:
      name: "Room Temperature"
      unit_of_measurement: "°C"
      accuracy_decimals: 1
      filters:
        - offset: 0.5  # 温度补偿
        - sliding_window_moving_average:
            window_size: 5
            send_every: 5
    humidity:
      name: "Room Humidity"
      unit_of_measurement: "%"
      accuracy_decimals: 0
    update_interval: 60s  # 读取间隔
    model: DHT22  # 传感器型号

  # BME280环境传感器
  - platform: bme280
    i2c_id: bus_a
    address: 0x76  # I2C地址
    temperature:
      name: "Outdoor Temperature"
      oversampling: 16x
    pressure:
      name: "Atmospheric Pressure"
    humidity:
      name: "Outdoor Humidity"
    update_interval: 30s

传感器数据处理使用过滤器（filters）进行预处理，如偏移校正、平滑处理等。

开关组件

开关组件用于控制设备开关状态：

switch:
  # GPIO开关
  - platform: gpio
    name: "Desk Lamp"
    pin: D1
    id: desk_lamp
    restore_mode: RESTORE_DEFAULT_ON  # 重启后状态
    interlock: [other_switch]  # 互锁开关组
    on_turn_on:
      - logger.log: "Desk lamp turned on"
    on_turn_off:
      - logger.log: "Desk lamp turned off"

  # 模板开关
  - platform: template
    name: "All Lights"
    turn_on_action:
      - switch.turn_on: desk_lamp
      - switch.turn_on: floor_lamp
    turn_off_action:
      - switch.turn_off: desk_lamp
      - switch.turn_off: floor_lamp
    lambda: |-
      return id(desk_lamp).state && id(floor_lamp).state;

灯光组件

灯光组件支持多种LED控制方式：

# PWM调光
light:
  - platform: monochromatic
    name: "Bedside Lamp"
    output: pwm_output
    default_transition_length: 1s  # 默认过渡时间
    gamma_correct: 1.8  # 伽马校正
    restore_mode: ALWAYS_ON  # 重启后状态

output:
  - platform: esp8266_pwm
    id: pwm_output
    pin: D5
    frequency: 1000Hz  # PWM频率

组件依赖关系

许多组件之间存在依赖关系，需要正确配置才能工作。例如，I2C传感器需要先配置I2C总线：

# 先配置I2C总线
i2c:
  - id: bus_a
    sda: D2
    scl: D1
    scan: true  # 自动扫描I2C设备
    frequency: 400kHz  # 总线频率

# 然后使用I2C传感器
sensor:
  - platform: bme280
    i2c_id: bus_a  # 引用I2C总线
    address: 0x76
    # ...其他配置

组件依赖检查在 esphome/config.py 中实现，确保在使用组件前满足所有依赖条件。

配置示例与最佳实践

使用`!secret`保护敏感信息

创建 secrets.yaml 文件存储敏感信息：

# secrets.yaml
wifi_ssid: "MyWiFiNetwork"
wifi_password: "MySecretPassword"
api_encryption_key: "LongRandomStringForEncryption"
ota_password: "OTAUpdatePassword"

在主配置文件中引用：

# device.yaml
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
  encryption:
    key: !secret api_encryption_key

ota:
  password: !secret ota_password

使用包（Packages）复用配置

创建可复用的配置包：

# packages/common.yaml
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  reboot_timeout: 5min

logger:
api:
  encryption:
    key: !secret api_encryption_key
ota:
  password: !secret ota_password

在设备配置中引用：

# bedroom-sensor.yaml
esphome:
  name: bedroom-sensor
  platform: ESP8266
  board: d1_mini

packages:
  common: !include packages/common.yaml  # 包含通用配置

sensor:
  - platform: dht
    # ...传感器配置

高级配置技巧：优化你的ESPHome设备

变量与模板使用

substitutions变量

使用 substitutions定义可重用变量：

substitutions:
  device_name: "living-room-sensor"
  friendly_name: "Living Room Sensor"
  update_interval: "60s"  # 默认更新间隔
  
esphome:
  name: ${device_name}
  friendly_name: ${friendly_name}
  
sensor:
  - platform: dht
    # ...
    update_interval: ${update_interval}

变量还支持条件赋值和命令行重写，极大提高了配置的灵活性。

模板表达式

ESPHome支持使用C++风格的lambda表达式创建动态行为：

sensor:
  - platform: template
    name: "Adjusted Temperature"
    lambda: |-
      // 从其他传感器获取值并计算
      return id(room_temperature).state + id(temperature_offset).state;
    update_interval: ${update_interval}

number:
  - platform: template
    name: "Temperature Offset"
    id: temperature_offset
    min_value: -5
    max_value: 5
    step: 0.1
    unit_of_measurement: "°C"
    optimistic: true

模板系统的实现位于 esphome/core/ 和 esphome/cpp_generator.py 中，负责将lambda表达式转换为C++代码。

条件配置与逻辑控制

条件配置

根据不同平台或环境应用不同配置：

# 条件包含配置
{% if esphome.platform == 'ESP32' %}
i2c:
  - id: bus_a
    sda: 21
    scl: 22
{% else %}
i2c:
  - id: bus_a
    sda: D2
    scl: D1
{% endif %}

# 条件值设置
sensor:
  - platform: bme280
    i2c_id: bus_a
    {% if esphome.board == 'nodemcu-32s' %}
    address: 0x77
    {% else %}
    address: 0x76
    {% endif %}
    # ...其他配置

自动化规则

配置基于事件触发的自动化：

automation:
  # 温度过高时触发
  - trigger:
      platform: sensor
      entity_id: sensor.room_temperature
      above: 30
    action:
      - switch.turn_on: exhaust_fan
      - delay: 5min
      - switch.turn_off: exhaust_fan
    id: high_temperature_alert

  # 按钮按下触发
  - trigger:
      platform: binary_sensor
      entity_id: binary_sensor.button
      to: "ON"
    action:
      - light.toggle: room_light

自动化系统的核心逻辑在 esphome/automation.py 中实现。

自定义组件开发

对于ESPHome未内置的功能，可以开发自定义组件：

// components/my_sensor/my_sensor.h
#pragma once

#include "esphome.h"

class MySensor : public PollingComponent, public Sensor {
 public:
  // 构造函数
  MySensor() : PollingComponent(60000) {}

  void setup() override {
    // 初始化代码
    pinMode(5, INPUT);
  }

  void update() override {
    // 读取传感器值
    int value = analogRead(5);
    // 发布传感器值
    publish_state(value);
  }
};

在YAML中使用自定义组件：

external_components:
  - source: components/my_sensor  # 自定义组件路径

sensor:
  - platform: my_sensor
    name: "My Custom Sensor"

自定义组件的开发指南可以在 CONTRIBUTING.md 中找到，详细说明了如何为ESPHome贡献新组件。

配置验证与调试：解决常见问题

配置验证工具使用

ESPHome提供多种工具验证配置的正确性：

命令行验证

esphome config device.yaml

此命令会检查配置文件的语法错误和逻辑问题，验证逻辑在 esphome/config_validation.py 中实现。

可视化配置编辑器

ESPHome Dashboard提供了图形化配置编辑器，可通过以下命令启动：

esphome dashboard .

然后在浏览器中访问 http://localhost:6052，即可使用可视化界面编辑和验证配置。

常见错误与解决方法

语法错误

错误表现：配置验证失败，显示YAML语法错误。

解决方法：

使用YAML验证工具检查语法
确保缩进一致（使用空格而非制表符）
检查括号和引号是否配对

# 错误示例：缩进不一致
sensor:
  - platform: dht
    pin: D2
  temperature:  # 此处缩进应为4个空格
    name: "Temperature"

组件依赖错误

错误表现：提示缺少依赖组件或驱动。

解决方法：

确保所有依赖组件已正确配置
检查组件间的依赖关系

# 错误示例：未配置I2C却使用I2C传感器
sensor:
  - platform: bme280  # 需要I2C总线
  
# 正确示例：先配置I2C
i2c:
  sda: D2
  scl: D1
  
sensor:
  - platform: bme280

引脚冲突

错误表现：设备无法启动或功能异常。

解决方法：

查阅开发板引脚图，确保引脚功能兼容
使用 logger: baud_rate: 0 禁用UART日志释放GPIO1和GPIO3

调试技巧与日志分析

日志级别控制

通过调整日志级别获取更多调试信息：

logger:
  level: DEBUG  # 全局日志级别
  logs:
    sensor: VERBOSE  # 传感器组件详细日志
    i2c: DEBUG       # I2C总线调试日志
    wifi: INFO       # WiFi组件仅信息日志

日志系统的实现位于 esphome/log.py 中。

调试输出

在模板中添加调试输出：

sensor:
  - platform: template
    name: "Debug Sensor"
    lambda: |-
      ESP_LOGD("debug", "Current temperature: %.1f", id(temp_sensor).state);
      return id(temp_sensor).state;

使用调试工具

ESPHome提供了多种调试工具：

esphome logs device.yaml - 实时查看设备日志
esphome run device.yaml --upload-port COM3 - 上传并监控设备
esphome clean device.yaml - 清理构建文件解决编译问题

实战案例：构建复杂物联网应用

智能家居传感器节点

下面是一个综合环境监测节点的完整配置，集成了多种传感器和功能：

esphome:
  name: environment-monitor
  platform: ESP32
  board: nodemcu-32s
  comment: "Indoor environment monitoring station"
  
  # 启动时执行
  on_boot:
    priority: 600
    then:
      - logger.log_message:
          level: INFO
          message: "Environment monitor started"

# 变量定义
substitutions:
  device_name: "environment-monitor"
  friendly_name: "Environment Monitor"
  update_interval: 30s
  temperature_offset: "0.0"

# WiFi配置
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  fast_connect: true
  
  # WiFi连接状态LED
  ap:
    ssid: "${device_name} Fallback"
    password: "fallbackpassword"

# 状态LED
status_led:
  pin: GPIO2
  inverted: true

# I2C总线配置
i2c:
  - id: bus_a
    sda: GPIO21
    scl: GPIO22
    scan: true
    frequency: 400kHz

# 传感器配置
sensor:
  # BME280温湿度气压传感器
  - platform: bme280
    i2c_id: bus_a
    address: 0x76
    temperature:
      name: "Temperature"
      id: temperature
      unit_of_measurement: "°C"
      accuracy_decimals: 1
      filters:
        - offset: ${temperature_offset}
        - sliding_window_moving_average:
            window_size: 10
            send_every: 10
    pressure:
      name: "Pressure"
      unit_of_measurement: "hPa"
      accuracy_decimals: 1
    humidity:
      name: "Humidity"
      unit_of_measurement: "%"
      accuracy_decimals: 0
    update_interval: ${update_interval}

  # BH1750光照传感器
  - platform: bh1750
    i2c_id: bus_a
    address: 0x23
    name: "Illuminance"
    unit_of_measurement: "lx"
    accuracy_decimals: 0
    update_interval: ${update_interval}

  # 空气质量传感器
  - platform: pmsx003
    type: PMS5003T
    uart_id: uart_bus
    pm_2_5:
      name: "PM 2.5"
      id: pm25
    pm_10_0:
      name: "PM 10.0"
    update_interval: 5min
    
  # 电池电压监测
  - platform: adc
    pin: GPIO34
    name: "Battery Voltage"
    id: battery_voltage
    unit_of_measurement: "V"
    accuracy_decimals: 2
    update_interval: 5min
    attenuation: 11db
    filters:
      - multiply: 2.0  # 电压分压器系数

# UART配置
uart:
  - id: uart_bus
    tx_pin: GPIO17
    rx_pin: GPIO16
    baud_rate: 9600
    parity: NONE
    stop_bits: 1

# 二进制传感器
binary_sensor:
  # 运动检测
  - platform: gpio
    pin:
      number: GPIO14
      mode: INPUT_PULLUP
      inverted: true
    name: "Motion"
    device_class: motion
    id: motion_sensor
    on_press:
      - light.turn_on:
          id: status_led
          brightness: 100%
          transition_length: 0.2s
    on_release:
      - light.turn_off:
          id: status_led
          transition_length: 1s

# 灯光控制
light:
  - platform: monochromatic
    id: status_led
    output: led_output
    internal: true

output:
  - platform: ledc
    id: led_output
    pin: GPIO13
    frequency: 1kHz

# 自动化规则
automation:
  # 空气质量警报
  - trigger:
      platform: sensor
      entity_id: sensor.pm_2_5
      above: 75
      for: 5min
    action:
      - logger.log: "High PM2.5 level detected"
      - light.turn_on:
          id: status_led
          brightness: 100%
      - delay: 10s
      - light.turn_off: status_led
      - delay: 2s
      - light.turn_on:
          id: status_led
          brightness: 100%
      - delay: 10s
      - light.turn_off: status_led

# 日志配置
logger:
  level: INFO
  logs:
    sensor: INFO
    pmsx003: WARN
    i2c: ERROR

# API配置
api:
  encryption:
    key: !secret api_encryption_key
  reboot_timeout: 15min

# OTA更新
ota:
  password: !secret ota_password

# Web服务器
web_server:
  port: 80
  auth:
    username: admin
    password: !secret web_password

这个配置实现了一个功能完善的环境监测站，包括：

温湿度、气压监测（BME280）
光照强度监测（BH1750）
空气质量监测（PMS5003T）
电池电压监测
运动检测
状态指示LED
本地Web服务器
远程API和OTA更新
自动化警报功能

配置优化与性能调优

对于资源受限的ESP8266设备，可以通过以下方式优化配置：

减少日志输出：降低日志级别，减少串口流量
增加传感器读取间隔：减少CPU占用和功耗
禁用未使用的功能：如Web服务器、蓝牙等
使用深度睡眠：对于电池供电设备
优化WiFi连接：减少重连频率和扫描时间

# 低功耗优化示例
esphome:
  name: battery-sensor
  platform: ESP8266
  board: d1_mini

deep_sleep:
  run_duration: 30s  # 唤醒运行时间
  sleep_duration: 5min  # 睡眠时间
  wakeup_pin: D0  # 外部唤醒引脚
  wakeup_pin_mode: INVERT_WAKEUP

sensor:
  - platform: dht
    pin: D2
    temperature:
      name: "Temperature"
    humidity:
      name: "Humidity"
    update_interval: 15s  # 短间隔，因为很快会进入睡眠

# 禁用不必要的功能
logger:
  level: ERROR  # 仅记录错误
  baud_rate: 0  # 禁用串口日志

# 轻量级API配置
api:
  reboot_timeout: 0s  # 禁用API超时重启