configuration.yaml 破千行？用 !include 和 packages 拆檔

charles

一開始大家的 configuration.yaml 都很短。
一年後它變成一千五百行，你想改一個感測器要捲三分鐘。

這篇講兩種拆法，以及什麼時候該用哪一種。



方法一：!include（照「類型」拆）

這是最常見的做法，HA 預設就幫你拆了兩個：

1. # configuration.yaml
2. automation: !include automations.yaml
3. script: !include scripts.yaml
4. scene: !include scenes.yaml

複製代碼

你可以繼續拆下去：

1. sensor: !include sensors.yaml
2. binary_sensor: !include binary_sensors.yaml
3. template: !include templates.yaml
4. shell_command: !include shell_commands.yaml
5. rest_command: !include rest_commands.yaml

複製代碼

三種 include 的差別（這個很多人搞混）

• !include 檔案.yaml — 就是把那個檔案的內容貼過來
  
• !include_dir_list 資料夾/ — 資料夾裡每個檔案是「清單的一項」
  
• !include_dir_merge_list 資料夾/ — 每個檔案裡本身是清單，全部合併成一個大清單
  
• !include_dir_named 資料夾/ — 檔名變成鍵，內容變成值（適合 script）
  
• !include_dir_merge_named 資料夾/ — 每個檔案是字典，全部合併
  

實務上最常用的是 merge_list：

1. automation: !include_dir_merge_list automations/

複製代碼

1. config/
2. └── automations/
3.     ├── lighting.yaml       ← 裡面是 - alias: ... 的清單
4.     ├── climate.yaml
5.     ├── security.yaml
6.     └── notifications.yaml

複製代碼

每個檔案內容長這樣：

1. # automations/lighting.yaml
2. - alias: 浴室感應燈
3.   triggers: ...
5. - alias: 走道感應燈
6.   triggers: ...

複製代碼

注意：用了 merge_list 之後，UI 編輯器就不能存新自動化了
（它不知道該存到哪個檔案）。這是最大的代價，要想清楚。

我的折衷做法：automations.yaml 留給 UI 用，另外開一個資料夾放手寫的：

1. automation: !include automations.yaml
2. automation manual: !include_dir_merge_list automations/

複製代碼

注意那個「manual」 —— YAML 不允許重複的鍵，
所以第二個要加一個後綴（叫什麼都可以）來區分。這是 HA 特有的寫法。



方法二：packages（照「功能」拆）

這個強大很多，但知道的人比較少。

!include 是照「設定類型」分：所有 sensor 在一起、所有 automation 在一起。
packages 是照「功能」分：跟浴室有關的東西全部在同一個檔案。

1. # configuration.yaml
2. homeassistant:
3.   packages: !include_dir_named packages/

複製代碼

1. config/
2. └── packages/
3.     ├── bathroom.yaml
4.     ├── energy.yaml
5.     ├── presence.yaml
6.     └── notifications.yaml

複製代碼

一個 package 檔案裡面可以有任何類型的設定：

1. # packages/bathroom.yaml
2. input_boolean:
3.   浴室暖風排程:
4.     name: 浴室暖風排程
5.     icon: mdi:radiator
7. template:
8.   - binary_sensor:
9.       - name: 浴室太濕
10.         state: >
11.           {{ states('sensor.浴室濕度') | float(0) > 75 }}
13. automation:
14.   - alias: 浴室感應燈
15.     triggers:
16.       - trigger: state
17.         entity_id: binary_sensor.浴室感應
18.         to: "on"
19.     actions:
20.       - action: light.turn_on
21.         target: {entity_id: light.浴室}
22.     mode: restart
24.   - alias: 太濕自動抽風
25.     triggers:
26.       - trigger: state
27.         entity_id: binary_sensor.浴室太濕
28.         to: "on"
29.         for: "00:05:00"
30.     actions:
31.       - action: switch.turn_on
32.         target: {entity_id: switch.浴室抽風}
33.     mode: single
35. script:
36.   浴室烘乾:
37.     sequence:
38.       - action: switch.turn_on
39.         target: {entity_id: switch.浴室暖風}
40.       - delay: "00:20:00"
41.       - action: switch.turn_off
42.         target: {entity_id: switch.浴室暖風}

複製代碼

好處非常明顯：

• 浴室的所有東西（輔助元件、感測器、自動化、腳本）都在一個檔案
  
• 要改浴室的邏輯，只看這一個檔案就夠
  
• 搬家或重建的時候，整個檔案複製過去就好
  
• 不要浴室自動化了？刪掉那個檔案，相關的所有東西一起消失，不留垃圾
  

最後一點是我最有感的。
用 !include 的話，刪一個功能你要去五個檔案裡找相關設定，一定會漏。

踩過的坑

1. packages 裡的鍵不能跟 configuration.yaml 衝突

如果 configuration.yaml 已經有 sensor:，package 裡也有 sensor:，
HA 會報錯說重複定義。解法是把主檔的那一段也搬進某個 package。

2. 改完要重啟，不能熱重載

packages 是在啟動時合併的。改了裡面的自動化，
雖然「重新載入自動化」有時候會生效，但不保證。養成重啟的習慣比較安全。

3. 縮排一錯就整包不見

package 檔案的最外層是「設定類型」，不能有額外縮排。
錯一格的話 HA 不會報錯，只是那些東西默默不見。

檢查方法：開發者工具 → YAML → 檢查設定，再去實體清單看數量對不對。

我自己的結構

1. config/
2. ├── configuration.yaml      ← 只剩 60 行，都是全域設定
3. ├── automations.yaml        ← UI 編輯器專用，不手動改
4. ├── secrets.yaml
5. └── packages/
6.     ├── _global.yaml        ← recorder、logger、http 這類
7.     ├── presence.yaml
8.     ├── lighting.yaml
9.     ├── climate.yaml
10.     ├── energy.yaml
11.     ├── security.yaml
12.     ├── notifications.yaml
13.     └── rooms/
14.         ├── bathroom.yaml
15.         ├── bedroom.yaml
16.         └── kitchen.yaml

複製代碼

（packages 可以放子資料夾，用 !include_dir_merge_named 就會遞迴掃。）

---

建議的遷移順序：不要一次全部搬。
先挑一個功能（例如浴室）做成 package，跑一週沒問題再搬下一個。

我當初一口氣搬完，結果三個東西默默失效，花了兩天才全部找回來。