我的 HA 設定資料夾長什麼樣（完整結構公開）

charles

看過很多人的設定分享，大多只貼片段。
這篇直接把整個結構攤開，順便講每個決定背後的理由。



完整結構

1. /config
2. ├── configuration.yaml          # 只剩 58 行
3. ├── automations.yaml            # UI 編輯器專用，我不手動改
4. ├── scripts.yaml                # 同上
5. ├── scenes.yaml                 # 同上
6. ├── secrets.yaml                # 密碼與權杖（不進版控）
7. ├── .gitignore
8. ├── known_devices.yaml          # 舊的，其實已經沒用了
9. │
10. ├── packages/                   # 主戰場
11. │   ├── _system.yaml            # recorder、logger、http
12. │   ├── _notify.yaml            # 通知服務與分級
13. │   ├── presence.yaml           # 在家判斷
14. │   ├── lighting.yaml           # 跨房間的燈光邏輯
15. │   ├── climate.yaml            # 冷氣與除濕
16. │   ├── energy.yaml             # 用電監控
17. │   ├── security.yaml           # 門窗與警報
18. │   ├── appliances.yaml         # 洗衣機、掃地機
19. │   └── rooms/
20. │       ├── bathroom.yaml
21. │       ├── bedroom.yaml
22. │       ├── kitchen.yaml
23. │       ├── living_room.yaml
24. │       └── study.yaml
25. │
26. ├── blueprints/
27. │   └── automation/
28. │       └── charles/
29. │           ├── motion_light.yaml
30. │           └── low_battery.yaml
31. │
32. ├── custom_components/          # HACS 裝的（不進版控）
33. ├── www/                        # 圖片、自訂卡片
34. │   └── local/
35. │       └── floorplan.png
36. ├── scripts/                    # shell 腳本
37. │   ├── git_autocommit.sh
38. │   └── backup_to_nas.sh
39. ├── ssh/                        # 金鑰（不進版控）
40. └── themes/

複製代碼

configuration.yaml 裡剩什麼

1. default_config:
3. homeassistant:
4.   name: 家
5.   latitude: !secret home_latitude
6.   longitude: !secret home_longitude
7.   elevation: 12
8.   unit_system: metric
9.   currency: TWD
10.   country: TW
11.   time_zone: Asia/Taipei
12.   packages: !include_dir_merge_named packages/
14. frontend:
15.   themes: !include_dir_merge_named themes/
17. automation: !include automations.yaml
18. script: !include scripts.yaml
19. scene: !include scenes.yaml
21. http:
22.   use_x_forwarded_for: true
23.   trusted_proxies:
24.     - 192.168.1.20        # 反向代理的 IP
26. logger:
27.   default: warning
28.   logs:
29.     homeassistant.components.zha: info

複製代碼

就這樣。所有實際的邏輯都在 packages 裡。

為什麼是 packages 而不是 !include

一句話：刪除的時候不會留垃圾。

我拆掉過一個「陽台植物澆水」的自動化。
如果是 !include 的結構，我要去 sensors.yaml、automations.yaml、
input_numbers.yaml、scripts.yaml 四個地方各刪一段 —— 一定會漏。

用 packages 的話，刪掉 plants.yaml 就全部乾淨消失。



一個 package 長什麼樣：bathroom.yaml

1. # ============ 浴室 ============
2. # 這個檔案包含浴室的所有東西。
3. # 刪掉這個檔案 = 浴室的所有自動化、感測器、輔助元件一起消失。
5. input_number:
6.   bathroom_humidity_threshold:
7.     name: 浴室除濕門檻
8.     min: 50
9.     max: 95
10.     step: 5
11.     initial: 75
12.     unit_of_measurement: "%"
13.     icon: mdi:water-percent
15. input_boolean:
16.   bathroom_guest_mode:
17.     name: 浴室訪客模式
18.     icon: mdi:account-question
20. template:
21.   - binary_sensor:
22.       - name: 浴室太濕
23.         unique_id: bathroom_too_humid
24.         device_class: moisture
25.         delay_on: "00:02:00"
26.         delay_off: "00:10:00"
27.         state: >
28.           {{ states('sensor.bathroom_humidity') | float(0)
29.              > states('input_number.bathroom_humidity_threshold') | float(75) }}
31. automation:
32.   - alias: 浴室感應燈
33.     id: bathroom_motion_light          # ← 一定要給 id
34.     use_blueprint:
35.       path: charles/motion_light.yaml
36.       input:
37.         motion_sensor: binary_sensor.bathroom_motion
38.         target_light:
39.           entity_id: light.bathroom
40.         no_motion_wait: 180
41.         day_brightness: 90
42.         night_brightness: 5
44.   - alias: 浴室太濕自動抽風
45.     id: bathroom_auto_fan
46.     triggers:
47.       - trigger: state
48.         entity_id: binary_sensor.浴室太濕
49.         to: "on"
50.     actions:
51.       - action: switch.turn_on
52.         target:
53.           entity_id: switch.bathroom_fan
54.       - wait_template: >
55.           {{ is_state('binary_sensor.浴室太濕', 'off') }}
56.         timeout: "01:00:00"
57.       - action: switch.turn_off
58.         target:
59.           entity_id: switch.bathroom_fan
60.     mode: restart
62. script:
63.   bathroom_dry:
64.     alias: 浴室烘乾 20 分鐘
65.     icon: mdi:hair-dryer
66.     sequence:
67.       - action: switch.turn_on
68.         target: {entity_id: switch.bathroom_heater}
69.       - delay: "00:20:00"
70.       - action: switch.turn_off
71.         target: {entity_id: switch.bathroom_heater}
72.     mode: single

複製代碼

幾個刻意的決定

1. 每個自動化都給 id

1.   - alias: 浴室感應燈
2.     id: bathroom_motion_light

複製代碼

沒有 id 的自動化不能在 UI 上編輯，也不能被追蹤。
而且 id 一旦改了，那個自動化的歷史紀錄就斷了。

命名規則：<區域>_<做什麼>，全小寫底線。

2. 門檻值用 input_number，不寫死

「濕度超過 75 就抽風」的 75 寫死在 YAML 裡，
調的時候要改檔案、重載。做成 input_number 就能在介面上拉。

而且家人也能調 —— 這比什麼都重要。

3. template 的 delay_on / delay_off

1.         delay_on: "00:02:00"
2.         delay_off: "00:10:00"

複製代碼

洗澡時濕度會瞬間飆高，delay_on 兩分鐘避免一進去就啟動。
delay_off 十分鐘避免抽到一半就停。

這兩個參數讓感測器「有脾氣」，是我後來覺得最有用的小設定。

4. 檔案開頭一定有註解

三個月後打開這個檔案，你不會記得為什麼這樣寫。
註解不是寫給別人看的，是寫給未來的自己看的。

我的命名慣例

• 檔案：小寫底線，底線開頭的是「系統級」（_system、_notify）
  
• 實體 ID：英文，<區域>_<裝置>_<功能>
  
• 自動化 id：英文，<區域>_<做什麼>
  
• alias（顯示名）：中文，給人看的
  
• 輔助元件：英文 ID + 中文 name
  

遷移的順序建議

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

正確做法：一次搬一個功能，跑一週再搬下一個。

順序建議：

• 先搬最獨立的（例如某個房間）
  
• 再搬跨房間的邏輯（通知、在家判斷）
  
• 最後才搬系統設定（recorder、logger）
  

每搬完一個就 git commit，出事可以精準回退。

---

最後講一個心得：結構的價值在「半年後你還敢動它」。

我第一年的設定是一坨兩千行的 configuration.yaml，
到後來我完全不敢改，因為不知道會影響什麼。

整理完之後，加一個新功能大概二十分鐘，而且不用擔心弄壞別的東西。