systematic-debugginglisted

# 系統化除錯 ## 概述 **核心原則：** 一律先找出根因再嘗試修復。只修症狀等於失敗。 **違反本流程的字面規定，就是違反除錯的精神。** ## 鐵律 ``` 未先調查根因，不得提出任何修復 ``` 如果沒有完��第一階段，就不能提出���復方案。 ## 使用時機 任何技術問題都適用： - 測試失敗 - 生產環境的 bug - 非預期行為 - 效能問題 - 建置失敗 - 整合問題 **尤其是以下情況時使用：** - 時間壓力下（緊急狀況更容易讓人想用猜的） - 「就修一下而已」看似顯而易見 - 你已經嘗試過多種修復 - 之前的修復沒有效 - 你沒有完全理解問題 **以下情況不可跳過：** - 問題看似��單（簡單的 bug 一樣有根因） - 你很趕時間（越急越容易返工） - 主管要你「現在就修好」（系統化比亂槍打鳥更快） ## 四個階段 你必須依序完成每個階段，才能進入下一個。 ### 第一階段：根因調查 **在嘗試任何修復「之前」：** 1. **仔細閱讀錯誤訊息** - 不要跳過錯誤或警告 - 它們往往就包含確切的解法 - 完整閱讀堆疊追蹤 - 記下行號、檔案路徑、錯誤碼 2. **穩定重現** - 你能可靠地觸發它嗎？ - 確切的步驟是什麼？ - 每次都會發生嗎？ - 無法重現 → 蒐集更多資料，不要用猜的 3. **檢查最近的變更** - 是什麼變更可能導致這個問題？ - Git diff、最近的 commit - 新的相依套件、設定變更 - 環境差異 4. **在多元件系統中蒐集證據** **當系統含有多個元件時（CI → 建置 → 簽署、API → 服務 → 資料庫）：** **在提出修復方案之前，先加入診斷儀器：** ``` 對每個元件的邊界： - 記錄進入元件的是什麼資料 - 記錄離開元件的是什麼資料 - 驗證環境/設定的傳遞 - 檢查每一層的狀態 先執行一次，蒐集可顯示在哪裡壞掉的證據 然後分析證據，找出失敗的元件 再深入調查該特定元件 ``` **範例（多層系統）：** ```bash # 第一層：工作流 echo "=== Secrets available in workflow: ===" echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}" # 第二層：建置腳本 echo "=== Env vars in build script: ===" env | grep IDENTITY || echo "IDENTITY not in environment" # 第三層：簽署腳本 echo "=== Keychain state: ===" security list-keychains security find-identity -v # 第四層：實際簽署 codesign --sign "$IDENTITY" --verbose=4 "$APP" ``` **這能顯示出：** 哪一層失敗（secrets → workflow ✓、workflow → build ✗） 5. **追蹤資料流** **當錯誤位在呼叫堆疊深處時：** 本目錄中的