Home Assistant 配置完全指南：YAML 文件编写与 UI 界面设置

Home Assistant 配置完全指南YAML 文件编写与 UI 界面设置【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.ioHome Assistant 配置分两条路一部分在浏览器界面里点点就能完成另一部分必须手写configuration.yaml这类 YAML 文件。这篇教程带你把两条路都走通——先找到主配置文件并写出一段能跑的最小配置再讲清 YAML 最容易翻车的几个坑然后用两个实战场景练手最后教你用 UI 完成集成、自动化和仪表盘设置以及如何验证和排查配置问题。第一步找到 configuration.yaml 并写出最小配置结论先行你 90% 的设置不用碰 YAML但少数功能自定义传感器、传感器拆分、部分通知通道必须写入主配置文件configuration.yaml。这个文件的位置取决于安装方式Home Assistant Operating System在/config目录下Home Assistant Container在你启动容器时挂载的 config 文件夹里不确定路径时到设置 系统 系统信息里找 Configuration directory 一项它显示的地址就是配置目录。一个现代安装里configuration.yaml往往只有一行default_config:它自动加载了大量常用功能再往下就是需要你动手写的部分。下面这段是最小可用的追加示例定义了一个来自 MQTT 的温度传感器sensor: - platform: mqtt name: 客厅温度 state_topic: sensor/living_room/temp unit_of_measurement: °CYAML 靠缩进表达层级缩进在谁下面就是谁的属性。写之前记住两条铁律每层缩进固定用 2 个空格冒号后面必须跟一个空格。四个最容易翻车的 YAML 规则下面每条都按你会写出什么 → 系统怎么报错 → 该怎么写三步讲遇到报错先对号入座。1. 用 Tab 键缩进错误写法编辑器自动补 Tab肉眼看不出区别报错现象found character \t that cannot start any token正确写法全选文件把 Tab 替换为 2 个空格。建议在编辑器里直接开启Tab 转空格2. 状态值没加引号YAML 会把on、off、Y、yes、No这些词直接解析成布尔值true/false。错误写法state: on被当成true报错现象not a valid value for dictionary value或状态值莫名其妙变成布尔正确写法state: on单引号包住3. 实体 ID 大小写写错实体 IDentity ID永远是小写状态值则区分大小写on和On不是同一个值。错误写法entity_id: binary_sensor.Front_Door报错现象调用无反应日志提示实体不存在正确写法entity_id: binary_sensor.front_door。拿不准时到设置 工具 状态里查系统实际记录的值4. 重复的顶级键名同一个文件里出现两个sensor:后者会整体覆盖前者且没有报错。需要多个平台时用列表写法把它们挂在同一个键下见上文 MQTT 示例的-列表形式。实战两个常用配置场景把配置拆分成多个文件主文件写久了会失控。用!include把某个域整个外包出去light: !include lights.yaml注意lights.yaml里不要再写light:这个键直接写列表内容- platform: mqtt name: 门厅灯 state_topic: light/entry/state更多拆分方式!include_dir_list、!include_dir_named等见 拆分配置文档。把密码藏进 secrets.yamlAPI 密钥、账号密码不要直接写在配置里。在配置目录新建secrets.yaml存放明文引用时用!secret# secrets.yaml mqtt_api_key: o.1234abcd # configuration.yaml notify: platform: pushbullet api_key: !secret mqtt_api_key name: pushbullet在 Core 安装中还可以用!env_var PASSWORD default_password读系统环境变量并给默认值。现在能直接在 UI 完成的操作大部分日常工作已经不需要开文件了记住这几条菜单路径添加集成侧边栏设置 设备与服务点右下角添加集成搜索设备品牌如 Philips Hue、Sonos跟着向导走完即可。设备通常会自动被发现。创建自动化设置 自动化点新建自动化。可以选从零开始图形化编辑触发器、条件和动作也可以直接切到编辑 YAML手敲。YAML 配置的自动化会带特殊标记改它们仍要回文件里。改基本设置语言、时区、单位制、家庭名称和地理位置都在设置 概览里调整改完即时生效或快速重载。自定义仪表盘任意仪表盘页面右上角点编辑即可添加卡片、拖拽排序再点完成保存。YAML 和 UI 同时改同一个对象会互相覆盖原则是UI 能管的交给 UIUI 不管的比如上文的!include、secrets才碰文件。验证配置与常见错误对照改完文件别急着生效先做一次配置检查。UI 里在设置 系统下用快速重载Quick reload会自动触发校验命令行用户可以直接跑hass --script check_config重载没生效就完整重启设置右上角三点菜单 Restart Home Assistant。检查通过、设备却还不对去 日志 里按集成名过滤警告信息都会记在那里。对照清单报错或现象原因处理found character \t用了 Tab 缩进Tab 全部换成 2 空格not a valid value for dictionary valueon/off未加引号写成on、offutf-8 codec cant decode byte文件编码不是 UTF-8另存为 UTF-8 编码集成没出现、无报错缺必填项或键名重复查日志确认顶级键名唯一!include后配置失效子文件里重复写了域名键子文件只保留列表内容接下来配置文件的位置和检查方式已经明确文件在配置目录改完先验证再重载。继续深入的话建议读这两篇仓库文档YAML 语法详解 和 配置故障排除。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考