系統性除錯：遇到問題怎麼有效地找出原因

charles

大部分人的除錯方式是「亂試」。

這篇講一套可以重複使用的方法。



第一步：把問題講清楚

「燈不會亮」不是一個好的問題描述。

好的描述包含：

• 預期的行為 —— 我以為會怎樣
  
• 實際的行為 —— 結果怎樣
  
• 什麼時候開始的 —— 一直都這樣？還是最近？
  
• 有沒有規律 —— 每次都這樣？還是偶爾？
  
• 最近改了什麼 —— 這個最重要
  

「最近改了什麼」通常就是答案。

第二步：縮小範圍

智慧家庭的一個動作要經過很多層：

1. 觸發（感應器）
2.   ↓
3. 傳輸（Zigbee / Wi-Fi）
4.   ↓
5. HA 收到（實體狀態改變）
6.   ↓
7. 自動化觸發
8.   ↓
9. 條件判斷
10.   ↓
11. 動作執行
12.   ↓
13. 指令傳出
14.   ↓
15. 裝置執行

複製代碼

每一層都可能壞。除錯就是找出斷在哪一層。

用「二分法」



從中間開始查，不要從頭查到尾。

第一個問題：HA 有沒有看到？

• 開發者工具 → 狀態 → 找那個感測器
  
• 手動觸發它（走過去、開門）
  
• 狀態有變嗎？
  

• 有變 → 問題在 HA 之後（自動化、動作）
  
• 沒變 → 問題在 HA 之前（感測器、傳輸）
  

這一個問題就把範圍砍一半。

第二個問題：動作能不能手動執行？

• 開發者工具 → 動作
  
• 手動呼叫那個動作（light.turn_on）
  
• 燈有亮嗎？
  

• 有亮 → 問題在自動化的邏輯
  
• 沒亮 → 問題在裝置或實體 ID
  

兩個問題，四種情況，範圍剩四分之一。

第三步：用對的工具

工具一：自動化追蹤（最重要）

• 設定 → 自動化 → 點那個 → 右上角三個點 → 追蹤
  

它會顯示：

• 最近執行過幾次
  
• 每次走了哪些分支
  
• 每一步的結果
  
• 卡在哪裡
  

「變更的內容」分頁還會顯示所有變數的值 ——
這是排查模板問題最快的方法。

工具二：模板編輯器

• 開發者工具 → 模板
  
• 任何模板都先在這裡測
  
• 會即時顯示結果和錯誤
  

工具三：記錄簿（Logbook）

• 顯示「什麼時候發生了什麼」
  
• 可以篩選特定實體
  
• 會標示「是誰造成的」（哪個自動化、哪個使用者）
  

最後這點很有用 —— 可以找出「到底是哪個自動化把燈關掉的」。

工具四：歷史記錄

• 看狀態隨時間的變化
  
• 適合找「間歇性」的問題
  
• 可以同時看好幾個實體，找出關聯
  

工具五：日誌

1. logger:
2.   default: warning
3.   logs:
4.     homeassistant.components.mqtt: debug
5.     zigpy: debug

複製代碼

注意：debug 會產生大量日誌，查完要關掉。



常見問題的快速診斷

「自動化偶爾不動」

• 九成是 mode 的問題
  
• 看日誌有沒有 "already running"
  
• 改成 restart 或 queued
  

「裝置在 HA 裡是 unavailable」

• 先看那個裝置在 Z2M / ZHA 裡是不是正常
  
• 是 → HA 和網關之間的問題（MQTT？）
  
• 否 → 裝置本身或訊號問題
  

「燈有時候不亮」

• 看記錄簿：指令有發出去嗎？
  
• 有發但沒亮 → 訊號問題或裝置問題
  
• 根本沒發 → 自動化的問題
  

「HA 重啟之後就正常了」

• 這通常是整合的問題
  
• 看日誌裡那個整合有沒有錯誤
  
• 考慮做一個「自動重新載入」的自動化：
  

1. automation:
2.   - alias: 整合卡住就重新載入
3.     triggers:
4.       - trigger: state
5.         entity_id: sensor.某個應該一直有值的
6.         to: unavailable
7.         for: "00:10:00"
8.     actions:
9.       - action: homeassistant.reload_config_entry
10.         target:
11.           entity_id: sensor.某個應該一直有值的

複製代碼

這是治標，但很有用。

「改了設定之後全部壞掉」

• 先看 YAML 語法（設定 → 系統 → 修復 → 檢查設定）
  
• 或者 SSH 進去跑：
  

1. ha core check

複製代碼

• 還是不行就還原備份
  

第四步：一次只改一件事

這是最重要的原則。

• 改一個東西，測試，記錄結果
  
• 沒用的話改回去，再改下一個
  
• 不要一次改五個，然後不知道是哪個有效
  

實務上：

• 改之前先備份（或至少複製一份設定檔）
  
• 寫下你改了什麼
  
• 這樣才能回溯
  

第五步：知道什麼時候該停

查了兩小時還沒解決的話：

• 把你已經確認的事情寫下來
  
• 去論壇問
  
• 或者先繞過它（用別的方法達成目的）
  

「先繞過」不是失敗 ——
有些問題是上游的 bug，你修不了。

一個實際的除錯範例

問題：走道的感應燈半夜不會亮。

1. 1. 問題描述
2.    預期：半夜走過去燈會亮
3.    實際：不會亮
4.    白天測試：正常
5.    最近改動：上週加了「深夜只開 10% 亮度」
7. 2. 縮小範圍
8.    Q: HA 有看到感應器嗎？
9.    → 開發者工具看 binary_sensor.走道人體
10.    → 半夜走過去，狀態有變成 on
11.    → 所以問題在 HA 之後
13. 3. 看自動化追蹤
14.    → 有被觸發
15.    → 條件通過了
16.    → 動作執行了：light.turn_on，brightness_pct: 10
18. 4. 找到問題
19.    → 10% 對那顆燈來說太低，它根本不亮
20.    → 那顆燈的最低亮度大概是 15%
22. 5. 解法
23.    → 改成 20%
24.    → 或者換一顆支援低亮度的燈

複製代碼

注意第 3 步：追蹤顯示「一切正常」，
但實際結果不對 —— 這種情況通常是參數的問題。

最後：建立你自己的「已知問題」清單

寫下來：

• 你遇過什麼問題
  
• 最後是什麼原因
  
• 怎麼解決的
  

同樣的問題你會遇到第二次，而且那時候你已經忘記怎麼解了。

---

下一篇：十個最被低估的 HA 功能。