HA 的 YAML 十個坑：錯了不報錯，只是理解成別的意思

charles · 發表於 2026-9-21 10:40:17

這篇的內容（14 段）

先把驗證工具準備好
坑 3：Tab 鍵
坑 5：清單的兩種寫法不能混
坑 8：多行字串的三種符號
坑 9：實體 ID 一律小寫
坑 10：重複的鍵
怎麼提早發現，而不是等它爆
方法二：讓編輯器即時畫紅線
方法三：一次只改一件事
步驟 1：裝一個終端機
步驟 2：初始化倉庫
步驟 4：先看清單，再提交
步驟 6：出事的時候怎麼用
最後一句

Home Assistant 的設定幾乎都是 YAML。YAML 討厭的地方不是難寫，是寫錯的時候它常常不報錯，只是把你的意思理解成另一件事。這一篇列十個實際會咬人的，每一個都給「錯的樣子」「對的樣子」，以及「你會看到什麼症狀」。

先把驗證工具準備好

下面每一個坑都可以當場驗。兩個工具：

設定 → 工具 → YAML → 檢查設定 — 驗整份設定的結構
設定 → 工具 → 範本 — 驗單一個值被解析成什麼

（「開發者工具」搬過兩次家：2026.2 從側邊欄移進「設定」底下，2026.8 改名叫「工具」。所以舊教學寫的「開發者工具 → YAML」現在的路徑是設定 → 工具 → YAML。找不到不是你的 HA 壞掉。）

坑 1：on / off / yes / no 會變成布林值

# 錯：你以為在比字串 "on"
conditions:
- condition: state
entity_id: binary_sensor.back_door
state: on

複製代碼

YAML 把沒加引號的 `on` 讀成布林 `True`。HA 拿到的是 `True`，跟實體實際回報的字串 `"on"` 不是同一個東西，條件永遠不成立。

# 對
state: "on"

複製代碼

症狀：自動化存得起來、也沒有紅字，就是永遠不動。跑一次追蹤（設定 → 自動化與場景 → 該自動化 → 三個點 → 追蹤），你會看到流程停在條件那一步，而且標示成不成立。

YAML 1.1 會被當成布林的完整清單：`on` / `off` / `yes` / `no` / `true` / `false` / `y` / `n`，以及它們的大小寫變化（`ON`、`Yes`、`N` 都算）。

養成習慣：狀態值一律加引號。 `"on"`、`"off"`、`"playing"`、`"home"` 全部加，不要挑。

（Python 的 PyYAML 還停在 YAML 1.1，而 HA 用的就是它。YAML 1.2 已經修掉這個設計，但短期內不會改過來。）

坑 2：冒號後面沒有空格，以及值裡面有冒號

# 錯
name:客廳溫度
# 對
name: 客廳溫度

複製代碼

反過來，值裡面出現冒號也會出事：

# 錯：YAML 以為「洗衣機」是鍵、「好了」是值
message: 洗衣機: 好了
# 對
message: "洗衣機: 好了"

複製代碼

症狀：檢查設定會失敗，但訊息指到的行數常常不是出錯那一行（YAML 是讀到後面某處才發現結構不對）。看到「mapping values are not allowed here」就往上面幾行找冒號。

寫中文訊息時改用全形冒號（：）就完全沒這個問題，因為 YAML 只認半形的。

坑 3：Tab 鍵

YAML 完全不接受 Tab 當縮排，一個都不行。

麻煩的是畫面上 Tab 跟四個空格長得一模一樣。

症狀：檢查設定時出現這一行：

found character '\t' that cannot start any token

複製代碼

看到 `\t` 就是 Tab，不用再猜別的。

解法：在編輯器把「Tab 轉成空格」打開。

VS Code / Studio Code Server：右下角狀態列會顯示「空格: 4」或「Tab 大小: 4」，點它 → 選「使用空格縮排」 → 再選 2。

你會看到右下角變成「空格: 2」。之後按 Tab 插入的就是兩個空格。

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

登入繼續閱讀使用 Google 登入

		自動登入	找回密碼
密碼			立即註冊

HA 的 YAML 十個坑：錯了不報錯，只是理解成別的意思

延伸閱讀

瀏覽過的版塊