【設定檔整理】把 configuration.yaml 拆開：packages、secrets、git，以及三個會讓你以為有做的陷阱

charles

這篇的內容（17 段）

1. 四種 include 語法怎麼選
2. 第二步：建 `packages/bathroom.yaml`
3. 建議的檔名編號
4. 步驟 4：secrets.yaml
5. 第二步：在設定檔裡引用
6. 第三步：驗證它真的有讀到
7. 步驟 5：版本控制（git）
8. 第一步：確認你在對的目錄
9. 第四步：第一次 commit
10. 推到 GitHub 的話
11. 日常流程
12. 步驟 6：命名規則
13. 每一條自動化都要有 `id`
14. 實體 ID 一律英文
15. 步驟 7：註解與 README
16. 在設定目錄放一份 README.md
17. 這篇的驗收

自動化寫到五十條之後，`configuration.yaml` 會變成沒人敢動的一坨。這篇把它拆開。

做完這篇，你會有一個「一個功能一個檔案」的設定目錄、一份不會洩漏密碼的版本控制、以及一套改壞了三十秒還原的流程。

這篇會先處理三個「你以為做好了其實沒有」的陷阱，因為它們全都不報錯：

• 在終端機裡 `cd /config` 然後 `git init` —— 那不是 HA 的設定目錄
  
• 用中文當設定鍵名 —— 整份設定會拒絕載入
  
• 把 `http:` 的安全設定放進你新整理的 packages —— 2026.8 之後那段會被完全忽略
  

---

步驟 0：先確認你的設定目錄到底在哪

這一步不能跳。 如果這一步弄錯，後面每一步你都會在錯的資料夾裡操作，而且全程不會有任何錯誤訊息。

裝一個可以看檔案的工具（三選一，建議第二個）：

• File editor 應用程式 —— 最簡單，瀏覽器裡編輯，但沒有終端機
  
• Studio Code Server 應用程式 —— VS Code 在瀏覽器裡跑，有終端機、有 YAML 語法檢查、有 git。本篇用這個
  
• Advanced SSH & Web Terminal 應用程式 —— 只有終端機
  

安裝路徑：設定 → 應用程式 → 應用程式商店。

（HA 2026.2 起「附加元件 Add-ons」正式改名為「應用程式 Apps」。API 沒變，但所有舊教學的選單路徑都對不上了。）

裝好之後，第一件事是在終端機裡打這兩行：

1. ls -la /config/configuration.yaml
2. ls -la /homeassistant/configuration.yaml

複製代碼

你會看到什麼：其中一個有檔案，另一個是 `No such file or directory`。

1. 哪一個有檔案                 意思
2. ------------------------------------------------------------------
3. /homeassistant 有            HA OS / Supervised，用應用程式進來的
4.                              → 你的設定目錄是 /homeassistant
5. /config 有                   Container 版，或你直接在主機上操作
6.                              → 你的設定目錄是 /config
7. 兩個都沒有                   你進錯容器了，或那個應用程式沒給設定目錄的存取權

複製代碼

為什麼會這樣：2023 年 11 月起，應用程式容器裡的 `/config` 被改成指向那個應用程式自己的私有目錄（讓應用程式可以存自己的設定），HA 的設定目錄改掛在 `/homeassistant`。

這是這篇最重要的一行。 所有寫「把檔案放到 `/config/www`」「`cd /config && git init`」的舊教學，在應用程式的終端機裡執行都會落到 HA 永遠不會讀的地方，而且不報錯。

底下的指令我一律寫 `/homeassistant`。你如果是 Container 版，全部換成 `/config`。

先做一次設定檢查，當作基準線：

• 設定 → 工具 → YAML → 最上面的「檢查設定」
  

（路徑變過兩次：2026.2 把「開發者工具」從側邊欄搬進「設定」底下，2026.8 又把它改名叫「工具」。所以現在是 設定 → 工具。）

你會看到什麼：綠色的「設定有效！」。現在就有紅字的話先把它修好再往下 —— 整理設定檔的過程中會重新載入很多次，帶著一個既有錯誤進去，你會分不出新錯誤是誰造成的。

---

步驟 1：把清單型的東西拆成資料夾

HA 預設的 `configuration.yaml` 裡有這幾行：

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

複製代碼

這三個檔案是 UI 編輯器在用的，不要動它們，也不要手動編輯它們（UI 存檔時會整份重寫，你的註解和排版都會沒了）。

手寫的部分另外放資料夾。改成這樣：

1. # configuration.yaml
3. # UI 編輯器用的，保留原樣
4. automation ui: !include automations.yaml
5. script ui: !include scripts.yaml
6. scene: !include scenes.yaml
8. # 手寫的，放資料夾
9. automation manual: !include_dir_merge_list automations/
10. script manual: !include_dir_merge_named scripts/
11. template: !include_dir_merge_list templates/

複製代碼

`automation` 後面那個 `ui` / `manual` 是標籤，你可以隨便取名，但同一個整合底下不能重複。HA 看的是空白前面那個字。

然後建資料夾（在終端機裡）：

1. cd /homeassistant
2. mkdir -p automations scripts templates packages

複製代碼

四種 include 語法怎麼選

這是最多人搞混的地方。判斷只看一件事：那個整合的設定是「清單」還是「字典」。

1. 語法                        什麼時候用                     檔案裡要長什麼樣
2. ------------------------------------------------------------------------------
3. !include_dir_merge_list     清單型：automation、template   每個檔案是一個 [清單]
4.                             binary_sensor、sensor
6. !include_dir_merge_named    字典型：script、shell_command  每個檔案是一個 {字典}
7.                             rest_command
9. !include_dir_list           很少用：每個檔案當成清單裡的    每個檔案是一個項目
10.                             一個項目
12. !include_dir_named          packages 專用：檔名就是鍵名    檔案內容直接就是值

複製代碼

分辨方法：去看你原本寫在 `configuration.yaml` 裡的樣子。

1. automation:            ← 底下第一個字元是「- 」→ 清單 → merge_list
2.   - alias: xxx
4. script:                ← 底下第一個是一個名字加冒號 → 字典 → merge_named
5.   my_script:
6.     sequence: ...

複製代碼

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

登入繼續閱讀使用 Google 登入