第4章配置基础

4、配置基础：configuration.yaml 文件结构，以及如何安全地编辑它。

好，咱们进入正题。这一章要聊的，是 Home Assistant 的「心脏」——configuration.yaml 文件。

说实话，我刚开始接触 HA 时，看到这个文件就头大。一堆缩进、冒号、横杠，稍不留神就报错。但用久了你会发现，它其实没那么可怕。说白了，它就是一份「告诉系统该做什么」的清单。

4.1 文件结构：YAML 的「规矩」

configuration.yaml 用的是 YAML 格式。YAML 的核心理念就一条：缩进决定层级，冒号分隔键值。

来看个最简单的例子：

# 这是我的第一个配置
sensor:
  - platform: mqtt
    name: "客厅温度"
    state_topic: "home/livingroom/temperature"
    unit_of_measurement: "°C"

这里 sensor 是顶层键，下面用两个空格缩进了一个列表项（横杠 - 表示列表）。列表项里又有 platform、name 等子键。

嗯，这里要注意：缩进必须一致。你可以用空格，也可以用 Tab，但千万别混用。我个人习惯用两个空格，清晰又省事。

4.2 核心结构：从「骨架」说起

一个典型的 configuration.yaml 文件，大概长这样：

# 基础配置
homeassistant:
  name: "我的家"
  latitude: 39.9042
  longitude: 116.4074
  elevation: 50
  unit_system: metric
  time_zone: "Asia/Shanghai"

# 前端界面
frontend:

# 自动化
automation: !include automations.yaml

# 场景
scene: !include scenes.yaml

# 自定义传感器
sensor:
  - platform: systemmonitor
    resources:
      - type: disk_use_percent
      - type: memory_use_percent

看到 !include 了吗？这是个好东西。它可以把配置拆到多个文件里，避免主文件变得又臭又长。我在项目中遇到过有人把所有自动化都塞进主文件，结果几千行代码，找一条规则得翻半天。后来我建议他拆开，世界清静了。

4.3 常见配置项一览

我把最常用的配置项整理成了表格，方便你对照：

配置项	作用	示例
`homeassistant`	系统基本信息（名称、位置、时区）	`name: "我的家"`
`frontend`	启用 Web 界面	`frontend:`
`automation`	自动化规则	`!include automations.yaml`
`sensor`	传感器实体	`- platform: mqtt`
`switch`	开关设备	`- platform: gpio`
`group`	实体分组	`living_room: ...`
`customize`	自定义实体属性	`sensor.temperature: ...`

你想想看，这些配置就像搭积木。你只需要告诉 HA：「我要一个传感器，它叫这个，数据从哪来」，剩下的系统会自己处理。

4.4 如何安全地编辑？—— 我的「三不」原则

编辑 configuration.yaml 最怕什么？怕改完系统崩了，连界面都进不去。我曾经有一次手滑，少写了一个冒号，结果 HA 直接罢工。从那以后，我给自己定了三条规矩：

⚠️ 安全编辑「三不」原则

不直接编辑生产环境——先在测试环境或虚拟机里试
不一次性改太多——每次只改一个模块，改完就验证
不忘记备份——改之前先复制一份，命名如 configuration.yaml.bak

具体操作步骤，我建议你这样来：

备份：把当前文件复制一份，放到安全位置
编辑：用 VS Code 或任何文本编辑器打开，注意缩进
验证：在 HA 的「开发者工具 → YAML 配置检查」里跑一遍
重启：确认无误后，重启 Home Assistant

💡 小技巧

我习惯在编辑前先运行 hass --script check_config 命令。它会帮你检查语法错误，比手动翻找快多了。如果你用的是 HA OS，也可以在「配置 → 系统 → 重新加载核心配置」里验证。

4.5 常见错误与避坑指南

说实话，YAML 的错误提示有时候挺「迷」的。我整理了几个我踩过的坑：

缩进不一致：这是头号杀手。用两个空格，别用 Tab，别混用。
冒号后面没空格：name:"客厅" 是错的，必须 name: "客厅"。
列表项没对齐：所有横杠 - 必须在同一列。
引号乱用：字符串里有特殊字符（如冒号、井号）时，记得加引号。

我曾经因为一个中文字符的冒号（全角 vs 半角）折腾了半小时。嗯，YAML 只认半角符号，这个千万记住。

4.6 进阶：使用 `!include` 拆分配置

当你的系统越来越复杂，主文件会变得臃肿。这时候 !include 就派上用场了：

# configuration.yaml
automation: !include automations.yaml
sensor: !include sensors.yaml
switch: !include switches.yaml

然后在同目录下创建对应的文件：

# sensors.yaml
- platform: mqtt
  name: "卧室温度"
  state_topic: "home/bedroom/temperature"

- platform: systemmonitor
  resources:
    - type: cpu_use

这样每个文件只管一件事，维护起来轻松多了。我个人习惯按功能模块拆分：传感器一个文件，自动化一个文件，场景一个文件。找问题的时候，直接定位到对应文件就行。

4.7 总结

configuration.yaml 是 HA 的「宪法」。你给它定规矩，它按规矩办事。记住三点：缩进要对、备份要勤、验证要跑。做到这三点，你基本不会翻车。