YAML 的七個語法坑，每個都讓我 debug 過一小時以上

charles

HA 的設定幾乎都是 YAML。
而 YAML 的特色是：錯的時候它常常不報錯，只是理解成別的意思。

這七個是我真的被咬過的。



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

1. # 你以為在比字串 "on"
2. conditions:
3.   - condition: state
4.     entity_id: binary_sensor.門
5.     state: on         # ← YAML 把它讀成 True

複製代碼

HA 拿到的是布林 True，跟字串 "on" 不一樣，條件永遠不成立。
而且不會報錯。

1. # 正確
2.     state: "on"

複製代碼

YAML 1.1 會把這些全部當成布林：
on / off / yes / no / true / false / y / n（還有大小寫變化）。

養成習慣：狀態值一律加引號。

坑 2：冒號後面沒有空格

1. # 錯（HA 會說解析失敗，但訊息指向奇怪的行數）
2. name:客廳溫度
4. # 對
5. name: 客廳溫度

複製代碼

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

1. # 錯：YAML 以為 "洗衣機" 是鍵、"好了" 是值
2. message: 洗衣機: 好了
4. # 對
5. message: "洗衣機: 好了"

複製代碼

中文全形冒號（：）不會有這個問題，所以寫中文訊息時我都用全形。

坑 3：Tab 鍵

YAML 完全不接受 Tab 當縮排。

慘的是很多編輯器按 Tab 會插入 Tab 字元，而畫面上看起來跟空格一模一樣。

解法：在編輯器設定裡把「Tab 轉成空格」打開。
VS Code 是右下角點「空格: 4」→ 選「使用空格縮排」。

出錯時的訊息通常是 found character '\t' that cannot start any token。
看到這行就是 Tab。



坑 4：縮排差一格，意思完全不同

1. # A：conditions 是 automation 的一部分（正確）
2. - alias: 測試
3.   triggers:
4.     - trigger: state
5.       entity_id: sensor.x
6.   conditions:
7.     - condition: state
8.       entity_id: sensor.y
9.       state: "on"
11. # B：conditions 變成 triggers 清單的一項（錯，但不會報錯）
12. - alias: 測試
13.   triggers:
14.     - trigger: state
15.       entity_id: sensor.x
16.     conditions:
17.       - condition: state
18.         ...

複製代碼

B 的情況 HA 可能會安靜地忽略那段，自動化變成沒有條件。
你只會發現「它好像什麼時候都在觸發」。

自保方法：開一個會顯示縮排參考線的編輯器。
VS Code 內建就有，Studio Code Server 附加元件也有。

坑 5：清單的兩種寫法混用

1. # 區塊寫法
2. entity_id:
3.   - light.客廳
4.   - light.餐廳
6. # 流式寫法（一行）
7. entity_id: [light.客廳, light.餐廳]
9. # 錯：混在一起
10. entity_id: [
11.   - light.客廳
12.   - light.餐廳
13. ]

複製代碼

兩種都合法，但不能混。

流式寫法在裡面有中文或特殊字元時容易出事，建議只在很短的時候用。

坑 6：數字被當成字串，或字串被當成數字

1. # 這是數字 6
2. brightness: 6
4. # 這是字串 "06"
5. brightness: "06"
7. # 這是數字 0.5
8. volume: .5
10. # 這是字串（因為有兩個點）
11. version: 1.2.3
13. # 這是「一分鐘」不是 60！
14. delay: 60          # HA 會當成 60 秒（這個剛好對）
15. delay: "00:01:00"  # 明確寫比較安全

複製代碼

最陰險的一個：開頭是 0 的數字

1. # 你以為是 8，實際上 YAML 1.1 會嘗試用八進位解析
2. code: 08          # 錯誤或變成奇怪的值
3. code: "08"        # 正確

複製代碼

門鎖密碼、電話號碼這類一律加引號。

坑 7：多行字串的三種符號

1. # > 摺疊：換行會變成空格（適合長句子）
2. message: >
3.   這是一段很長的文字，
4.   換行只是為了好讀，
5.   實際上會變成一行。
7. # | 保留：換行就是換行（適合程式碼、多行訊息）
8. message: |
9.   第一行
10.   第二行
11.   第三行
13. # >- 或 |- ：結尾不留換行
14. message: >-
15.   沒有結尾換行

複製代碼

範本一定要用 >：

1. value_template: >
2.   {{ states('sensor.溫度') | float(0) > 28
3.      and is_state('binary_sensor.有人','on') }}

複製代碼

用 | 的話換行會被保留，Jinja 通常還是能處理，
但如果範本結果要當成一個值（例如 brightness_pct），
多餘的換行會讓它變成字串而不是數字。

怎麼提早發現錯誤

方法一：HA 內建檢查

1. 開發者工具 → YAML → 檢查設定

複製代碼

或命令列：

1. ha core check

複製代碼

方法二：編輯器即時檢查

VS Code 裝 YAML 擴充套件（Red Hat 出的），
再加 HA 的 schema，打錯會直接畫紅線。

Studio Code Server 附加元件已經內建了。

方法三：線上驗證器

yamllint.com 之類的，貼上去看有沒有語法錯。
但它只能驗 YAML 語法，不會知道 HA 的欄位名稱對不對。

方法四：一次只改一件事

這個最實用。改完一段就檢查設定、重載一次。
一口氣改五個地方然後出錯，你要花三倍時間找。



一個救命的習慣

改設定之前，先 git commit。

這樣出事的時候 git diff 會直接告訴你改了哪幾行，
而不是憑記憶回想「我剛剛動了什麼」。

（上一篇有講怎麼設定，這裡就不重複了。）

---

補充一個冷知識：YAML 1.2 已經修掉 on/off 變布林的問題了，
但 Python 的 PyYAML（HA 在用的）還停在 1.1。

所以這個坑短期內不會消失，加引號的習慣還是要養成。