home-assistant-best-practices

Home Assistant 最佳实践

核心原则： 尽可能使用 Home Assistant 原生构造。模板会绕过验证，在运行时静默失败，并使调试变得不透明。

决策工作流

创建任何自动化时，请遵循以下顺序：

0. 关卡：是否修改现有配置？

如果您的更改影响实体ID或跨组件引用——重命名实体、用辅助元素替换模板传感器、转换设备触发器或重构自动化——请先阅读 references/safe-refactoring.md。该参考文档涵盖影响分析、设备兄弟发现和变更后验证。在继续之前完成其工作流。

以下步骤1-5适用于新配置或模式评估。

1. 检查是否存在特定用途的触发器/条件，然后是通用原生触发器/条件

自2026.7起，默认构建块是特定用途的触发器/条件——<domain>.<name> 键（检测到移动、电池电量低、门打开）带有区域/楼层/标签目标。首先检查是否有匹配意图的触发器/条件，然后是通用原生触发器/条件，最后才是模板。请参阅 references/automation-patterns.md#purpose-specific-triggers--conditions-default-since-20267。

常见替换：

• 触发器中的单个传感器实体列表 → 一个带有区域/楼层/标签 target: 的特定用途触发器
• {{ states('x') | float > 25 }} → numeric_state 条件，使用 above: 25
• {{ is_state('x', 'on') and is_state('y', 'on') }} → condition: and 与状态条件
• {{ now().hour >= 9 }} → condition: time 与 after: "09:00:00"
• wait_template: "{{ is_state(...) }}" → wait_for_trigger 与状态触发器（注意：当状态已为真时行为不同——请参阅 references/safe-refactoring.md#trigger-restructuring）

2. 检查内置辅助元素或模板辅助元素

在创建模板传感器之前，请检查 references/helper-selection.md。

常见替换：

• 多个传感器的总和/平均值 → min_max 集成
• 二进制任意开/全开逻辑 → group 辅助元素
• 变化率 → derivative 集成
• 跨阈值检测 → threshold 集成
• 消耗跟踪 → utility_meter 辅助元素

如果没有内置辅助元素适用，请使用模板辅助元素——而不是YAML。
通过HA配置流（MCP工具或API）或通过UI创建：
设置 → 设备与服务 → 辅助元素 → 创建辅助元素 → 模板。
仅当明确要求或两种路径都不可用时，才编写 template: YAML。

3. 选择正确的自动化模式

默认的 single 模式通常是错误的。请参阅 references/automation-patterns.md#automation-modes。

场景	模式
带超时的感应灯	restart
顺序处理（门锁）	queued
每个实体独立操作	parallel
一次性通知	single

4. 使用 entity_id 而非 device_id

device_id 在设备重新添加时会失效。请参阅 references/device-control.md。

例外： Zigbee2MQTT 自动发现的设备触发器是可接受的。

5. 对于 Zigbee 按钮/遥控器

• ZHA： 使用带有 device_ieee（持久）的 event 触发器
• Z2M： 使用 device 触发器（自动发现）或 mqtt 触发器

请参阅 references/device-control.md#zigbee-buttonremote-patterns。

---

关键反模式

反模式	改用	原因	参考
带有 float > 25 的 condition: template	condition: numeric_state	在加载时验证，而非运行时	references/automation-patterns.md#native-conditions
wait_template: "{{ is_state(...) }}"	带有状态触发器的 wait_for_trigger	事件驱动，非轮询；等待变化（语义差异见 references/safe-refactoring.md#trigger-restructuring）	references/automation-patterns.md#wait-actions
触发器中的 device_id	entity_id（或 ZHA 的 device_ieee）	device_id 在重新添加时失效	references/device-control.md#entity-id-vs-device-id
感应灯的 mode: single	mode: restart	重新触发必须重置计时器	references/automation-patterns.md#automation-modes
automations.yaml 中的顶层键 enabled: false	automation.turn_off（临时）或实体注册表禁用（永久）	不是有效的顶层键——在模式验证时被拒绝；自动化加载为 unavailable	references/automation-patterns.md#disabling-automations
用于总和/平均值的模板传感器	min_max 辅助元素	声明式，处理不可用状态	references/helper-selection.md#numeric-aggregation
带阈值的模板二进制传感器	threshold 辅助元素	内置迟滞支持	references/helper-selection.md#threshold
未进行影响分析就重命名实体ID	遵循 references/safe-refactoring.md 工作流	重命名会静默破坏仪表板、脚本、场景、配置条目数据和存储仪表板	references/safe-refactoring.md#entity-renames
重命名基于配置条目的组（UI组）的成员而不更新成员资格	在注册表重命名后通过选项流更新组成员资格	实体注册表重命名不会更新配置条目中的 options.entities——组静默失效	references/safe-refactoring.md#config-entry-groups
重命名配置条目集成（Better/Generic Thermostat、Min/Max、Threshold）使用的实体而不修补配置条目数据	扫描并修补 core.config_entries 的 data+options 字段	这些集成在配置条目中存储 entity_id——实体注册表重命名不会更新	references/safe-refactoring.md#config-entry-data--blind-spots-for-entity-registry-renames
YAML 中的 template: 传感器/二进制传感器	模板辅助元素（UI 或配置流 API）	需要文件编辑和配置重载；更难管理	references/template-guidelines.md
直接编辑 .storage/ 文件或其他 HA 内部状态	使用 HA REST/WebSocket API 管理状态和配置条目	.storage/ 文件是 HA 的内部状态数据库；直接编辑绕过验证，有损坏风险，并可能被 HA 静默覆盖	—
手动为仅 YAML 集成编写原始 YAML 到 configuration.yaml	使用带备份和验证的托管 YAML 配置编辑	非托管写入存在语法错误风险，没有备份，并跳过 check_config——托管编辑提供所有三项	references/yaml-only-integrations.md
为自动化/脚本/场景生成 YAML 片段	使用 HA 配置 API 以编程方式创建自动化/脚本	API 调用验证配置，避免语法错误，不需要手动文件编辑或重启	references/automation-patterns.md, references/examples.yaml
告诉用户编辑 configuration.yaml 以进行集成	引导用户到 HA UI 中的设置 > 设备与服务	大多数集成是 UI 配置的；YAML 集成配置很少且特定于集成	—
提及 HA "add-ons"	使用术语 "Apps"	HA 在 2026.2 中将 add-ons 重命名为 Apps——"Apps 是与 Home Assistant 一起运行的独立应用程序"	—
使用供应商房间 ID 的 vacuum.send_command	使用 HA area_id 的 vacuum.clean_area（如果已映射区域）	使用原生 HA 区域，跨集成工作——但需要先在实体设置中映射区域到区域	references/device-control.md#vacuum-control
在灯光服务调用中使用 color_temp（微倒度）	使用 color_temp_kelvin	color_temp 参数已在 2026.3 中移除；仅支持开尔文	references/device-control.md#lights
人员/设备跟踪器 entered_home/left_home 设备触发器或 is_home/is_not_home 条件	state 触发器 to: home / to: not_home，或 state 条件	这些已在 2026.5 中移除——状态触发器和条件是正确的替代品	references/automation-patterns.md#presence-and-person-triggers-and-conditions-removed-in-20265
触发器中的实体列表，而区域/楼层/标签目标更合适	带有 target: {area_id: ...} 的特定用途触发器	自动化跟随区域成员资格，设备变化时无需过时的实体列表	references/automation-patterns.md#purpose-specific-triggers--conditions-default-since-20267
旧的特定用途键（battery.low、vacuum.docked、timer.time_remaining...）或触发器 behavior: any/last	2026.7 重命名的键（battery.became_low...）和 behavior: each/all	旧键不再加载；旧 behavior 值引发修复问题并面临移除	references/automation-patterns.md#purpose-specific-triggers--conditions-default-since-20267
在 __init__() 中注册回调或调用 self.turn_on()/self.get_state()	在 initialize() 中注册所有内容	__init__ 期间插件连接未建立——调用静默失败	references/appdaemon.md#app-structure-and-lifecycle
在重复触发器上调用 run_in 而不取消之前的句柄	在每个新 run_in 之前 cancel_timer(self._off_handle)	每个触发器堆叠一个独立计时器——设备不可预测地切换	references/appdaemon.md#scheduling-and-timers
在实例变量中存储持久状态	使用 HA input_number、input_boolean 或 input_text 辅助元素	实例变量在应用重载或守护进程重启时重置	references/appdaemon.md#state-management-and-inter-app-communication
在类体内硬编码实体ID	通过 apps.yaml 中的 self.args 传递实体ID	硬编码ID阻止复用，每次安装都需要代码编辑	references/appdaemon.md#appsyaml-configuration
在 Blueprint 主体中硬编码实体ID	将它们暴露为带有选择器的 !input	硬编码违背了 blueprint 的目的——无法复用	references/blueprint-guide.md#inputs-and-selectors
Blueprint 中实体/设备的自由文本输入	类型化的 entity/target/device 选择器	文本允许拼写错误并静默失败；选择器验证选择	references/blueprint-guide.md#inputs-and-selectors
在模板中直接使用 !input	将其绑定到 variables: 条目，使用变量	!input 是 YAML 标签，不是模板值——模板会出错或忽略它	references/blueprint-guide.md#referencing-inputs-input-and-templating
发布没有 source_url 的 Blueprint	将 source_url 设置为文件的规范 URL	没有它，用户无法重新导入更新，共享也很麻烦	references/blueprint-guide.md#blueprint-metadata

---

参考文件

当您需要详细信息时，请阅读这些文件：

文件	何时阅读	关键章节
references/safe-refactoring.md	重命名实体、替换辅助元素、重构自动化或对现有配置进行任何修改	#universal-workflow, #entity-renames, #helper-replacements, #trigger-restructuring, #config-entry-data--blind-spots-for-entity-registry-renames, #storage-mode-dashboards-storagelovelace
references/automation-patterns.md	编写触发器、条件、等待、变量或选择自动化模式；捕获操作响应；记录/注释步骤；禁用自动化	#purpose-specific-triggers--conditions-default-since-20267, #native-conditions, #trigger-types, #wait-actions, #automation-modes, #continue-on-error, #stopping-a-sequence, #variables, #capturing-action-responses, #repeat-actions, #ifthen-vs-choose, #parallel-actions, #trigger-ids, #documenting-automations--scripts, #disabling-automations
references/helper-selection.md	决定使用内置辅助元素还是模板传感器	#how-helpers-are-created, #menu-based-helpers, #numeric-aggregation, #rate-and-change, #time-based-tracking, #counting-and-timing, #scheduling, #entity-grouping, #probabilistic-inference, #data-smoothing, #random-values, #climate-control, #domain-conversion, #template-helpers, #decision-matrix
references/template-guidelines.md	确认模板确实适用于某个用例	#when-templates-are-appropriate, #when-to-avoid-templates, #template-sensor-best-practices, #common-patterns, #error-handling
references/yaml-only-integrations.md	创建或编辑没有配置流的仅 YAML 集成（例如 command_line、基于平台的 mqtt、rest）	#yaml-only-integration-types, #post-edit-actions
references/device-control.md	编写服务调用、Zigbee 按钮自动化或使用 target:	#entity-id-vs-device-id, #service-calls-best-practices, #zigbee-buttonremote-patterns, #domain-specific-patterns
references/scenes.md	创作或激活场景；快照/恢复模式；快照与脚本的区别	#scene-config-shape, #activating-a-scene, #snapshot--restore-scenecreate, #apply-states-without-storing-sceneapply
references/dashboard-guide.md	设计或修改 Lovelace 仪表板——布局、视图类型、策略、部分、卡片、徽章、CSS 样式、HACS	#dashboard-structure, #view-types, #dashboard-strategies, #built-in-cards, #features, #badges, #custom-cards, #css-styling, #common-pitfalls
references/dashboard-cards.md	查找可用的卡片类型或获取卡片特定文档	—
references/domain-docs.md	查找集成/领域文档，或特定触发器、条件或操作的专用文档页面	#fetching-trigger-condition-and-action-docs
references/examples.yaml	需要结合多个最佳实践的复合示例	—
references/appdaemon.md	AppDaemon 应用：何时使用 vs. 原生 HA、应用结构、服务调用、调度、错误处理、安全重构影响	—
references/blueprint-guide.md	创作可复用的 blueprint：元数据与 source_url、输入与选择器、target 与 entity、默认值、输入部分、!input 模板、版本控制	#when-to-author-a-blueprint, #blueprint-metadata, #inputs-and-selectors, #target-selector-vs-entity-selector, #defaults, #input-sections, #referencing-inputs-input-and-templating, #versioning-and-updates, #common-pitfalls