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 }} → 帶有 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（注意：當狀態已為 true 時行為不同——請參閱 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 輔助元素	宣告式，處理 unavailable 狀態	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「附加元件」	使用術語「應用程式」	HA 在 2026.2 將附加元件重新命名為應用程式——「應用程式是與 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 中移除；僅支援 Kelvin	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
在藍圖主體中硬編碼實體 ID	將其公開為帶有選擇器的 !input	硬編碼違背了藍圖的目的——無法重複使用	references/blueprint-guide.md#inputs-and-selectors
在藍圖中對實體/裝置使用自由文字輸入	類型化的 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	將 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	編寫可重複使用的藍圖：中繼資料與 source_url、輸入與選擇器、target vs 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