HA 的設定檔怎麼整理：分檔、共用、版本控制

charles

自動化寫到五十個之後，configuration.yaml 會變成一團。

這篇講怎麼整理。



第一步：分檔

HA 預設就有這幾行：

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

複製代碼

但這樣每個檔案還是會很長。

更好的做法：用資料夾

1. configuration.yaml
2. automations/
3.   照明.yaml
4.   空調.yaml
5.   安全.yaml
6.   通知.yaml
7. templates/
8.   溫濕度.yaml
9.   能源.yaml
10. packages/
11.   浴室.yaml
12.   客廳.yaml

複製代碼

三種 include 語法

1. # 把資料夾裡所有檔案的「清單」合併成一個大清單
2. automation manual: !include_dir_merge_list automations/
4. # 每個檔案是一個獨立的項目
5. sensor: !include_dir_list sensors/
7. # 把資料夾裡所有檔案的「字典」合併
8. script: !include_dir_merge_named scripts/
10. # 每個檔案變成一個 key（檔名就是 key）
11. input_boolean: !include_dir_named booleans/

複製代碼

最常用的是 merge_list（自動化、感測器這種清單型的）。

完整的範例：

1. # configuration.yaml
3. # UI 編輯的自動化（不要動這行）
4. automation ui: !include automations.yaml
6. # 手寫的自動化，放在資料夾裡
7. automation manual: !include_dir_merge_list automations/
9. script ui: !include scripts.yaml
10. script manual: !include_dir_merge_named scripts/
12. template: !include_dir_merge_list templates/

複製代碼

注意：

• automation 後面那個 ui / manual 是「標籤」，可以隨便取
  
• 但不能重複
  
• 保留 UI 那一行 —— 不然 UI 編輯器會壞掉
  

第二步：用 packages 按「功能」組織

這是最好用的一招。

問題：一個功能的東西散在好幾個檔案。

1. 浴室通風這個功能需要：
2.   configuration.yaml      的 input_boolean
3.   templates/濕度.yaml      的模板感測器
4.   automations/空調.yaml    的三個自動化
5.   scripts.yaml            的一個腳本

複製代碼

改一個功能要開四個檔案。

用 packages 解決：

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

複製代碼

然後 packages/浴室.yaml 裡面可以放所有東西：

1. # packages/浴室.yaml
3. input_boolean:
4.   浴室除濕中:
5.     name: 浴室除濕中
6.   浴室手動模式:
7.     name: 浴室手動模式
9. template:
10.   - sensor:
11.       - name: 浴室濕度差
12.         state: >
13.           ...
15. automation:
16.   - alias: 浴室 - 開始除濕
17.     ...
18.   - alias: 浴室 - 結束除濕
19.     ...
20.   - alias: 浴室 - 偵測手動操作
21.     ...
23. script:
24.   浴室強制除濕:
25.     sequence:
26.       ...

複製代碼

一個檔案包含這個功能的所有東西。

好處：

• 改一個功能只要開一個檔案
  
• 要停用整個功能只要把檔案改名
  
• 要分享給別人只要給一個檔案
  
• 很好理解
  

這是我最推薦的組織方式。

建議的 packages 分法：

1. packages/
2.   01-基礎.yaml       recorder、logger、http 設定
3.   10-客廳.yaml
4.   11-主臥.yaml
5.   12-浴室.yaml
6.   13-廚房.yaml
7.   20-能源.yaml
8.   21-安全.yaml
9.   22-通知.yaml
10.   30-語音.yaml

複製代碼

用數字開頭 —— 檔案列表會按順序排。



第三步：secrets.yaml

所有的密碼、金鑰、位址都放這裡。

1. # secrets.yaml
2. wifi_ssid: 我家WiFi
3. wifi_password: 密碼
4. mqtt_user: mqtt
5. mqtt_password: 密碼
6. latitude: 25.0
7. longitude: 121.5
8. telegram_token: 123456:ABC...

複製代碼

在設定檔裡用 !secret 引用：

1. homeassistant:
2.   latitude: !secret latitude
3.   longitude: !secret longitude
5. mqtt:
6.   username: !secret mqtt_user
7.   password: !secret mqtt_password

複製代碼

為什麼要這樣做：

• 分享設定檔的時候不會洩漏密碼
  
• 做版本控制的時候可以排除 secrets.yaml
  
• 改密碼只要改一個地方
  

第四步：版本控制（Git）

這個會改變你的工作方式。

好處：

• 改壞了可以還原
  
• 可以看到「什麼時候改了什麼」
  
• 可以在電腦上編輯再推上去
  

設定

1. cd /config
2. git init

複製代碼

.gitignore（很重要）：

1. secrets.yaml
2. *.db
3. *.db-shm
4. *.db-wal
5. *.log
6. .storage/
7. .cloud/
8. .google.token
9. tts/
10. deps/
11. home-assistant.log*
12. known_devices.yaml
13. backups/
14. www/community/

複製代碼

重點：

• 一定要排除 secrets.yaml
  
• 一定要排除 .storage/（裡面有 token 和使用者資料）
  
• 排除資料庫（很大而且一直變）
  

然後：

1. git add -A
2. git commit -m "初始設定"

複製代碼

推到 GitHub 的話一定要用私有倉庫。

就算排除了 secrets，設定檔還是會透露你家的結構。

實用的工作流程

• 用 VS Code 附加元件（在瀏覽器裡編輯）
  
• 或者用 Samba 掛載，在電腦上編輯
  
• 改完 commit
  
• 重新載入設定
  
• 測試
  
• 壞了就 git checkout 還原
  

其他整理技巧

一、自動化的命名規則

1. alias: 客廳 - 有人開燈
2. alias: 客廳 - 沒人關燈
3. alias: 浴室 - 開始除濕
4. alias: 系統 - 備份失敗提醒

複製代碼

「區域 - 動作」的格式：

• 列表會按區域排在一起
  
• 一眼看出是哪裡的
  

二、給自動化一個 id

1. automation:
2.   - id: bathroom_vent_start
3.     alias: 浴室 - 開始除濕

複製代碼

為什麼：

• 有 id 才能在 UI 裡編輯
  
• 改名字的時候追蹤記錄不會斷
  
• 可以用 automation.turn_on 精確指定
  

三、寫註解

1. automation:
2.   # 為什麼是 12%：
3.   # 觀察一週的結果，洗澡後濕度差通常會到 15-20%
4.   # 洗手大概 5-8%，所以 12 是安全的分界點
5.   - alias: 浴室 - 開始除濕
6.     triggers:
7.       - trigger: numeric_state
8.         entity_id: sensor.浴室濕度差
9.         above: 12

複製代碼

三個月後你會忘記為什麼是 12。

注意：UI 編輯器會把註解吃掉 ——
所以重要的東西寫在 YAML 檔裡，不要用 UI 編輯。

四、定期清理

• 設定 → 系統 → 修復 —— 看有沒有警告
  
• 設定 → 裝置與服務 → 實體 → 篩選「不可用」 —— 清掉舊的
  
• 停用（不是刪除）三個月沒用的自動化
  

五、寫一份 README

在 /config 放一個 README.md：

1. # 我家的 HA 設定
3. ## 架構
4. - 主機：N100 迷你主機
5. - Zigbee：SONOFF Dongle-P，頻道 20
6. - MQTT：Mosquitto 附加元件
8. ## 重要的決定
9. - Zigbee 頻道選 20（Wi-Fi 用 6 和 11）
10. - recorder 排除了 linkquality（資料庫太大）
11. - 所有通知走 script.通知
13. ## 已知問題
14. - 陽台的溫濕度計訊號偏弱，夏天會掉線
15. - 掃地機的整合偶爾要重新載入
17. ## 待辦
18. - [ ] 主臥加電動窗簾
19. - [ ] 熱水器接智慧斷路器

複製代碼

這份文件的價值會隨時間增加。

---

下一篇：系列總結 ——
一份完整的檢查表。