home-assistant-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Home Assistant Best Practices

Home Assistant 最佳实践

Core principle: Use native Home Assistant constructs wherever possible. Templates bypass validation, fail silently at runtime, and make debugging opaque.

核心原则： 尽可能使用 Home Assistant 的原生功能。模板会绕过验证，在运行时静默失败，且调试难度大。

Decision Workflow

决策流程

Follow this sequence when creating any automation:

创建任何自动化时，请遵循以下步骤：

0. Gate: modifying existing config?

0. 前置检查：是否修改现有配置？

If your change affects entity IDs or cross-component references — renaming entities, replacing template sensors with helpers, converting device triggers, or restructuring automations — read

references/safe-refactoring.md

first. That reference covers impact analysis, device-sibling discovery, and post-change verification. Complete its workflow before proceeding.

Steps 1-5 below apply to new config or pattern evaluation.

如果你的更改涉及实体 ID 或跨组件引用——例如重命名实体、用辅助工具替换模板传感器、转换设备触发器或重构自动化——请先阅读

references/safe-refactoring.md

。该文档涵盖了影响分析、设备关联项发现及变更后验证。完成该文档中的流程后再继续操作。

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

1. Check for native condition/trigger

1. 检查是否有原生条件/触发器

Before writing any template, check

references/automation-patterns.md

for native alternatives.

Common substitutions:

{{ states('x') | float > 25 }}

→

numeric_state

condition with

above: 25

{{ is_state('x', 'on') and is_state('y', 'on') }}

→

condition: and

with state conditions

{{ now().hour >= 9 }}

→

condition: time

with

after: "09:00:00"

wait_template: "{{ is_state(...) }}"

→

wait_for_trigger

with state trigger (caveat: different behavior when state is already true — see

references/safe-refactoring.md#trigger-restructuring

)

在编写任何模板之前，请查看

references/automation-patterns.md

寻找原生替代方案。

常见替代示例：

{{ states('x') | float > 25 }}

→ 带

above: 25

的

numeric_state

条件

{{ is_state('x', 'on') and is_state('y', 'on') }}

→ 包含状态条件的

condition: and

{{ now().hour >= 9 }}

→ 带

after: "09:00:00"

的

condition: time

wait_template: "{{ is_state(...) }}"

→ 带状态触发器的

wait_for_trigger

（注意：当状态已为真时行为不同——详见

references/safe-refactoring.md#trigger-restructuring

）

2. Check for built-in helper

2. 检查是否有内置辅助工具

Before creating a template sensor, check

references/helper-selection.md

Common substitutions:

Sum/average multiple sensors →
```
min_max
```
integration
Binary any-on/all-on logic →
```
group
```
helper
Rate of change →
```
derivative
```
integration
Cross threshold detection →
```
threshold
```
integration
Consumption tracking →
```
utility_meter
```
helper

在创建模板传感器之前，请查看

references/helper-selection.md

。

常见替代示例：

多个传感器求和/取平均值 →
```
min_max
```
集成
任意开启/全部开启的二进制逻辑 →
```
group
```
辅助工具
变化率计算 →
```
derivative
```
集成
跨阈值检测 →
```
threshold
```
集成
消耗量追踪 →
```
utility_meter
```
辅助工具

3. Select correct automation mode

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

Default

single

mode is often wrong. See

references/automation-patterns.md#automation-modes

Scenario	Mode
Motion light with timeout	`restart`
Sequential processing (door locks)	`queued`
Independent per-entity actions	`parallel`
One-shot notifications	`single`

默认的

single

模式通常并不合适。详见

references/automation-patterns.md#automation-modes

。

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

4. Use entity_id over device_id

4. 使用 entity_id 而非 device_id

device_id

breaks when devices are re-added. See

references/device-control.md

Exception: Zigbee2MQTT autodiscovered device triggers are acceptable.

device_id

在设备重新添加后会失效。详见

references/device-control.md

。

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

5. For Zigbee buttons/remotes

5. Zigbee 按钮/遥控器配置

ZHA: Use
```
event
```
trigger with
```
device_ieee
```
(persistent)
Z2M: Use
```
device
```
trigger (autodiscovered) or
```
mqtt
```
trigger

See

references/device-control.md#zigbee-buttonremote-patterns

ZHA： 使用带
```
device_ieee
```
（持久化标识）的
```
event
```
触发器
Z2M： 使用自动发现的
```
device
```
触发器或
```
mqtt
```
触发器

详见

references/device-control.md#zigbee-buttonremote-patterns

。

Critical Anti-Patterns

关键反模式

Anti-pattern	Use instead	Why	Reference
`condition: template` with `float > 25`	`condition: numeric_state`	Validated at load, not runtime	`references/automation-patterns.md#native-conditions`
`wait_template: "{{ is_state(...) }}"`	`wait_for_trigger` with state trigger	Event-driven, not polling; waits for change (see `references/safe-refactoring.md#trigger-restructuring` for semantic differences)	`references/automation-patterns.md#wait-actions`
`device_id` in triggers	`entity_id` (or `device_ieee` for ZHA)	device_id breaks on re-add	`references/device-control.md#entity-id-vs-device-id`
`mode: single` for motion lights	`mode: restart`	Re-triggers must reset the timer	`references/automation-patterns.md#automation-modes`
Template sensor for sum/mean	`min_max` helper	Declarative, handles unavailable states	`references/helper-selection.md#numeric-aggregation`
Template binary sensor with threshold	`threshold` helper	Built-in hysteresis support	`references/helper-selection.md#threshold`
Renaming entity IDs without impact analysis	Follow `references/safe-refactoring.md` workflow	Renames break dashboards, scripts, and scenes silently	`references/safe-refactoring.md#entity-renames`

反模式	替代方案	原因	参考文档
带 `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`
用模板传感器计算求和/平均值	`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`

Reference Files

参考文档

Read these when you need detailed information:

File	When to read	Key sections
`references/safe-refactoring.md`	Renaming entities, replacing helpers, restructuring automations, or any modification to existing config	`#universal-workflow` , `#entity-renames` , `#helper-replacements` , `#trigger-restructuring`
`references/automation-patterns.md`	Writing triggers, conditions, waits, or choosing automation modes	`#native-conditions` , `#trigger-types` , `#wait-actions` , `#automation-modes` , `#ifthen-vs-choose` , `#trigger-ids`
`references/helper-selection.md`	Deciding whether to use a built-in helper vs template sensor	`#numeric-aggregation` , `#rate-and-change` , `#time-based-tracking` , `#counting-and-timing` , `#scheduling` , `#entity-grouping` , `#decision-matrix`
`references/template-guidelines.md`	Confirming templates ARE appropriate for a use case	`#when-templates-are-appropriate` , `#when-to-avoid-templates` , `#template-sensor-best-practices` , `#common-patterns` , `#error-handling`
`references/device-control.md`	Writing service calls, Zigbee button automations, or using target:	`#entity-id-vs-device-id` , `#service-calls-best-practices` , `#zigbee-buttonremote-patterns` , `#domain-specific-patterns`
`references/examples.yaml`	Need compound examples combining multiple best practices	—

需要详细信息时，请阅读以下文档：

文档	阅读场景	核心章节
`references/safe-refactoring.md`	重命名实体、替换辅助工具、重构自动化或任何现有配置修改	`#universal-workflow` , `#entity-renames` , `#helper-replacements` , `#trigger-restructuring`
`references/automation-patterns.md`	编写触发器、条件、等待逻辑或选择自动化模式	`#native-conditions` , `#trigger-types` , `#wait-actions` , `#automation-modes` , `#ifthen-vs-choose` , `#trigger-ids`
`references/helper-selection.md`	决定使用内置辅助工具还是模板传感器	`#numeric-aggregation` , `#rate-and-change` , `#time-based-tracking` , `#counting-and-timing` , `#scheduling` , `#entity-grouping` , `#decision-matrix`
`references/template-guidelines.md`	确认模板是否适用于当前场景	`#when-templates-are-appropriate` , `#when-to-avoid-templates` , `#template-sensor-best-practices` , `#common-patterns` , `#error-handling`
`references/device-control.md`	编写服务调用、Zigbee 按钮自动化或使用 target:	`#entity-id-vs-device-id` , `#service-calls-best-practices` , `#zigbee-buttonremote-patterns` , `#domain-specific-patterns`
`references/examples.yaml`	需要结合多种最佳实践的复合示例	—