企业官网建设流程全解析

如何写好 Home Assistant YAML 配置：3 条规则、1 张决策表和一套排错路径

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

刚把 Home Assistant 跑起来，打开 configuration.yaml，满屏的冒号和缩进，不知道从哪下手，也不敢乱存。其实写 YAML 配置的核心知识没那么多：3 条规则能避开九成报错，再分清什么时候该切到 UI 界面。下面四部分，一个下午能看完。

你真正需要知道的 YAML 规则

忘掉完整的 YAML 语法教程吧。写 Home Assistant 配置时，你真正会踩的就三个坑。记住这 3 条就不会报错：

1. 缩进必须 2 个空格，严禁 Tab

每一层缩进固定 2 个空格，用 Tab 必炸：

sensor: - platform: mqtt # 每层缩进 2 个空格 name: "Temperature"

2. 冒号后面必须留空格

key: value这个格式里，冒号和值之间空格不能省：

name: "客厅灯" # ✅ 冒号后有空格 # name:"客厅灯" # ❌ 少个空格，直接解析失败

3. on / off 要加引号

YAML 会把没加引号的on、ON、off当成布尔值 true/false，想把状态写成字符串时：

state: 'on' # 必须加引号，否则被解析成 true

完整的 Home Assistant YAML 语法细节，可以翻 YAML 语法文档，但日常够用的就上面这几条。

跟着敲一遍：从零配置你的第一个设备

以 MQTT 温度传感器为例，整套 configuration.yaml 写法流程就四步：复制 → 粘贴 → 检查 → 重启。

第一步，打开 configuration.yaml。Core 安装可以直接在 设置 > 文件编辑器 里改，更推荐用带 YAML 高亮的代码编辑器，缩进问题一眼就能看出来：

第二步，把这段配置追加到文件末尾。每行都写了注释，边看边改：

# 追加到 configuration.yaml 末尾 sensor: # 顶层键，对应所有传感器 - platform: mqtt # 数据源：MQTT broker name: "客厅温度" state_topic: "sensor/living/temp" # 订阅的主题 unit_of_measurement: "°C"

第三步，先别急着重启。去 设置 > 工具 > YAML 页点检查配置，语法问题会直接列出来，比翻日志快得多：

第四步，检查通过就点 Restart。起来之后在实体列表里看到"客厅温度"并且数值在刷新，你的第一个 YAML 设备就活了 ✅

UI 还是 YAML？一张决策表讲清楚

新手最常问：界面都能做的事，为什么还要学 YAML？答案是看场景：

Home Assistant UI 设置只需要记住三条路径：

• 设置 > 设备与服务：所有集成的入口，点右下角添加集成，跟着向导走
• 设置 > 自动化与场景：创建和管理自动化，编辑器里可以切到"编辑 YAML"模式
• 仪表盘右上角 > 编辑仪表盘：拖卡片改布局

⚠️ 注意一点：在 configuration.yaml 里定义过的项，UI 里会带 (YAML) 标识且不让改。动手编辑前先确认这项归谁管，两边同时改必出冲突。

配置报错？90% 是这几个原因

遇到 Home Assistant 配置报错别慌着重启，九成是下面这四个：

1. Tab 缩进报错

• 报错：found character '\t' that cannot start any token
• 根因：某行缩进用了 Tab 而不是空格
• 修复：编辑器里开启"显示空白字符"，找到 Tab 换成 2 个空格，保存后重新检查

2. 布尔值没加引号

• 报错：not a valid value for dictionary value @ data
• 根因：on/off被解析成布尔值，但那个位置要的是字符串
• 修复：加单引号，state: 'on'，这类报错一次修复终身免疫

3. UI 与 YAML 冲突

• 现象：UI 里想改的设置是灰的，或实体名后挂着 (YAML)
• 根因：该项在 configuration.yaml 里已有定义，YAML 优先
• 修复：选一个地方管。想让 UI 接管，就把 YAML 里对应条目删掉再重启

4. secrets 不生效

• 现象：写了!secret，集成拿不到密码，日志里报凭据缺失
• 根因：名字和 secrets.yaml 里的键对不上，或文件放错了目录
• 修复：在 secrets.yaml 里加一行logger: debug，日志会打印 secret 到底从哪个文件加载的

收尾

上手之后值得深入的两件事：用!include把配置按领域拆成多个文件，用!env_var把密码挪进环境变量。这两招会让你的 configuration.yaml 保持整洁很多年，进阶可以看 拆分配置文档。

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io