configuration.yaml 拆檔實作：!include 五種形式、packages 功能式拆法，與「改完到底要不要重開」

charles

這篇的內容（25 段）

1. 這篇會做完的事
2. 第零步：準備工作
3. 0-1 裝一個檔案編輯器
4. 0-2 先備份（這一步不能跳）
5. 2-1 !include 檔案.yaml
6. 2-2 剩下四種是目錄式的
7. 3-1 建立資料夾
8. 3-2 建立第一個手寫自動化檔案
9. 3-3 改 configuration.yaml
10. 3-4 檢查設定
11. 3-5 重新載入並驗證
12. 3-6 確認介面編輯器還能存
13. 3-7 同樣的手法可以套到這幾個
14. 第四步：!include 的天花板在哪
15. 5-1 建立資料夾並掛上去
16. 5-2 寫第一個 package
17. 5-3 檢查設定
18. 7-2 三種情況必須完整重新啟動
19. 第八步：建議的目錄結構
20. 9-1 數實體
21. 9-2 列出所有不可用的實體
22. 第十步：搬遷順序
23. 通過這篇的標準
24. 常見失敗對照表
25. 還可以往下做的

先講一個跟大部分舊教學不一樣的前提：今天的 Home Assistant，你的 configuration.yaml 未必會變長。

2020 年左右幾乎每個整合都要寫 YAML，所以「一年後 configuration.yaml 破千行」是常態。現在絕大多數整合改成介面設定（config flow），設定存在 /config/.storage/ 底下的 JSON 裡，根本不經過 configuration.yaml。很多 2026 年新灌的機器跑滿一年，configuration.yaml 還是不到一百行。

所以這篇的第一步不是教你怎麼拆，是教你怎麼量，然後決定要不要拆。



這篇會做完的事

• 量出你的設定檔實際有多大、哪一段最長，再決定拆不拆
  
• 搞懂 !include 家族的五種形式，以及它們各自吃什麼格式的檔案
  
• 做一次「照類型拆」：把自動化拆成多個檔案，而且保留介面編輯器的功能
  
• 做一次「照功能拆」：用 packages 把一個房間的所有東西收進一個檔
  
• 把「改完到底要不要重新啟動」這件事講清楚 —— 三種情況要重開，其他都不用
  
• 學會兩個在拆檔之後救命的驗證動作
  

全部做完約 90 分鐘。需要一個可以編輯 /config 的工具。

第零步：準備工作

0-1 裝一個檔案編輯器

設定 → 應用程式 → 應用程式商店，搜尋 File editor，安裝、啟動、開啟網頁介面。要用終端機的話裝 Advanced SSH & Web Terminal。

名稱改了要注意：2026.2 起 Home Assistant 把「附加元件（Add-ons）」整批改名成「應用程式（Apps）」。舊教學寫的「設定 → 附加元件」現在是「設定 → 應用程式」，東西一樣。

0-2 先備份（這一步不能跳）

設定 → 系統 → 備份 → 建立備份，選「完整備份」。拆檔會動到整個設定結構，拆壞的時候你需要一個回得去的點。

你會看到：備份清單出現一筆新的，大小通常是幾十到幾百 MB，狀態顯示完成。

第一步：量一量，再決定拆不拆

在 Terminal 裡打：

1. wc -l /config/configuration.yaml

複製代碼

你會看到一個行數，例如：

1. 84 /config/configuration.yaml

複製代碼

判斷標準：

• 200 行以下 → 不用拆。拆了只是多開幾個檔案，找東西反而變慢。這篇後面可以當成參考資料，不用現在做
  
• 200 到 600 行 → 拆掉最長的那兩三段就夠了，走第三步的 !include 就好
  
• 600 行以上，或者同一個房間的設定散在五個地方 → 走第五步的 packages
  

想知道是哪一段最長，跑這一句（它會列出每個最外層區塊從第幾行開始）：

1. grep -n '^[a-z_]*:' /config/configuration.yaml

複製代碼

你會看到類似：

1. 1:homeassistant:
2. 12:default_config:
3. 14:frontend:
4. 18:recorder:
5. 31:logger:
6. 38:automation:
7. 39:script:
8. 40:scene:
9. 42:template:
10. 119:sensor:
11. 201:shell_command:

複製代碼

兩個相鄰行號相減就是那一段的長度。上面這個例子裡 template: 佔了 77 行、sensor: 佔了 82 行 —— 這兩段就是該拆的。

第二步：認識 !include 家族的五種形式

這一步不用動手，但後面每一步都靠它。

2-1 !include 檔案.yaml

最單純的一種：把那個檔案的內容原封不動貼到這個位置。

1. # /config/configuration.yaml
2. automation: !include automations.yaml

複製代碼

被引用的 /config/automations.yaml 裡面不可以再寫一次 automation:，直接從內容開始：

1. # /config/automations.yaml
2. - alias: "浴室感應燈"
3.   triggers:
4.     - trigger: state
5.       entity_id: binary_sensor.yu_shi_gan_ying
6.       to: "on"
7.   actions:
8.     - action: light.turn_on
9.       target:
10.         entity_id: light.yu_shi
12. - alias: "走道感應燈"
13.   triggers:
14.     - trigger: state
15.       entity_id: binary_sensor.zou_dao_gan_ying
16.       to: "on"
17.   actions:
18.     - action: light.turn_on
19.       target:
20.         entity_id: light.zou_dao

複製代碼

「不可以在被引用的檔案裡重複最外層的鍵」是最常見的第一次錯誤，而且錯誤訊息很難懂（通常是「expected a list, got dict」之類）。

2-2 剩下四種是目錄式的

它們吃的是一整個資料夾。四種的差別在於「一個檔案代表什麼」：

1. !include_dir_list  資料夾/
2.     一個檔案 = 清單裡的一項。檔案內容是「一個物件」
3.     結果：一個清單
5. !include_dir_merge_list  資料夾/
6.     一個檔案 = 一段清單（可以有很多項）
7.     結果：全部合併成一個大清單
8.     → 自動化、指令碼清單最常用這個
10. !include_dir_named  資料夾/
11.     一個檔案 = 字典裡的一個鍵，檔名（去掉 .yaml）就是鍵名
12.     結果：一個字典
13.     → packages 最常用這個
15. !include_dir_merge_named  資料夾/
16.     一個檔案 = 一個字典（裡面自己寫鍵名）
17.     結果：全部合併成一個大字典

複製代碼

以下還有約 80% 的內容
登入後即可閱讀完整教學

登入繼續閱讀使用 Google 登入