YAML基础：理解ESPHome的配置文件结构、缩进规则、常用数据类型

好，咱们进入第三课。说实话，YAML 这东西，我第一次接触时也觉得有点别扭——不就是个配置文件吗，怎么还搞出这么多规矩？但用久了你会发现，它其实是最适合做硬件配置的语言之一。今天我就带你把它彻底搞明白。

YAML 到底是什么？

YAML 的全称是 "YAML Ain't Markup Language"，翻译过来就是「YAML 不是标记语言」。嗯，这名字挺绕的。你只要记住：它是一种人类可读的数据序列化格式。说白了，就是让你用纯文本写配置，机器能读懂，人也能一眼看懂。

ESPHome 的整个灵魂，就装在一个 .yaml 文件里。你写的每一行缩进、每一个冒号，都在告诉 ESP32：「嘿，你该这么干活了」。

配置文件的结构：树状思维

我个人习惯把 YAML 想象成一棵树。根节点是设备，下面分叉出传感器、开关、灯光等分支，每个分支再长出叶子——也就是具体的配置项。

来看一个最简单的例子：

sensor:
  - platform: dht
    pin: GPIO4
    temperature:
      name: "客厅温度"
    humidity:
      name: "客厅湿度"
    update_interval: 60s

你看，sensor 下面有一个列表（因为有 -），列表里是一个 DHT 传感器配置。它又嵌套了 temperature 和 humidity 两个子节点。这种结构，你读起来是不是很自然？

缩进规则：两个空格，别多别少

这是新手最容易翻车的地方。YAML 用缩进来表示层级，不能用 Tab，只能用空格。而且，同一层级的缩进必须对齐。

我的建议是：

• 用 VS Code 或任何支持 YAML 的编辑器，开启「显示空格」功能
• 统一用 2 个空格 作为一级缩进
• 嵌套一层，就多加 2 个空格

正确的缩进示例：

# 正确示范
esp32:
  board: nodemcu-32s
  framework:
    type: arduino

# 错误示范（缩进不一致）
esp32:
  board: nodemcu-32s
   framework:    # 这里多了一个空格
    type: arduino

嗯，第二个例子编译时一定会报错。你想想看，机器读到这里就懵了：「这个 framework 到底属于谁？」

常用数据类型：就这四种

YAML 的数据类型其实很少，你掌握下面四种就够了：

类型	写法	示例	说明
字符串	不加引号或加双引号	name: "客厅温度"	大部分配置项都是字符串
数字	直接写	pin: GPIO4	整数、浮点数都支持
布尔值	true/false	internal: true	注意全小写，大小写敏感
时间间隔	数字+单位	60s, 5min	ESPHome 特有的语法糖

避坑指南：我踩过的三个坑

1. 注释别乱放：YAML 的注释用 #，但 # 不能出现在值的中间。比如 pin: GPIO4 # 这是引脚号 没问题，但 name: "客厅#温度" 就会出问题。

2. 列表缩进要对齐：列表项 - 后面的内容，要么跟 - 在同一行，要么换行后缩进对齐。我曾经写错过：

   # 错误
   sensor:
     - platform: dht
       pin: GPIO4
     - platform: bme280
         pin: GPIO5    # 多缩进了，导致解析错误

3. 别用引号包数字：update_interval: "60s" 虽然能运行，但 ESPHome 会把它当字符串处理，可能引发类型转换问题。直接写 60s 就好。

知识体系总览

下面这张图，帮你把今天讲的内容串起来：

动手试试：写一个完整的配置

光看不练可不行。我建议你现在就打开编辑器，照着下面这个模板写一个：

esphome:
  name: my_sensor
  platform: ESP32
  board: nodemcu-32s

wifi:
  ssid: "MyWiFi"
  password: "password123"

sensor:
  - platform: dht
    pin: GPIO4
    temperature:
      name: "室内温度"
    humidity:
      name: "室内湿度"
    update_interval: 30s

output:
  - platform: gpio
    pin: GPIO2
    id: led_green

light:
  - platform: binary
    name: "绿色指示灯"
    output: led_green

写完之后，用 esphome config my_sensor.yaml 命令检查一下语法。如果没报错，恭喜你，你已经掌握了 YAML 的核心用法。