Apr 2, 2026

Claude Code 除錯技巧大全：從 error message 到修好的最短路徑

這篇文章和之前的除錯實戰互補： 📖 Claude Code 實戰：用 AI 除錯 Legacy PHP 專案

🎯 前言

除錯是開發者每天花最多時間的事之一。Claude Code 可以大幅縮短除錯時間，但前提是你要用對方式。

最常見的錯誤做法：

❌ "程式壞了，幫我修"
→ Claude 不知道什麼壞了、怎麼壞的、在哪裡壞的

這篇文章整理不同類型的 bug 該怎麼讓 Claude 幫你修，目標是從發現問題到修好的最短路徑。

📂 第一步：怎麼丟錯誤訊息

原則：直接貼原文，不要自己解讀

❌ "有一個 import 的錯誤"

✅ "npm run build 出現這個錯誤：

    Error: Cannot find module './components/Header'
    at Module._resolveFilename (node:internal/modules/cjs/loader:1075:15)
    at Module._load (node:internal/modules/cjs/loader:920:27)
    
    幫我修"

Claude 從完整的錯誤訊息能讀出：

具體是什麼錯：模組找不到
在哪裡出錯：loader.js:1075
呼叫鏈：誰在呼叫誰
是什麼環境：Node.js（CJS loader）

你自己轉述會丟失這些資訊。

多個錯誤時，貼第一個

如果終端輸出了 50 行錯誤，通常只有第一個錯誤是根因，後面的都是連鎖反應。

✅ "build 失敗了，第一個錯誤是：
    
    [第一個錯誤訊息]
    
    後面還有一堆衍生錯誤，應該修好第一個就好了"

沒有錯誤訊息的情況

有時候不是 crash，而是「結果不對」：

✅ "getUserById(123) 應該回傳 { id: 123, name: 'Alice' }，
    但實際回傳了 null。
    資料庫裡確實有 id=123 的資料。
    
    相關檔案：src/lib/user.ts:45"

這種 bug 要給三個資訊：

預期行為：應該回傳什麼
實際行為：實際回傳什麼
已知條件：你確認過的事實

🔧 五種常見 Bug 類型的除錯方式

類型 1：Build / Compile Error

特徵：有明確的錯誤訊息和行號。

你：npm run build 失敗：

    src/pages/blog/[...slug].astro:15:3
    Type error: Property 'title' does not exist on type 'never'

    幫我修

Claude 的處理方式：

讀取出錯的檔案和行號
分析型別定義
找出型別不符的根因
修正

這類 bug 最簡單——資訊完整，Claude 幾乎都能一次修對。

類型 2：Runtime Error（有 Stack Trace）

特徵：程式跑到一半 crash，有 stack trace。

你：使用者登入時 crash 了：

    TypeError: Cannot read properties of undefined (reading 'role')
    at checkPermission (src/middleware/auth.ts:23:15)
    at processLogin (src/lib/login.ts:45:8)
    at handler (src/api/auth.ts:12:5)

    幫我修

技巧：讓 Claude 從 stack trace 的最上層（最接近 crash 的地方）開始讀。

你：先讀 src/middleware/auth.ts:23 那一行，
    理解為什麼 user 可能是 undefined

類型 3：邏輯錯誤（結果不對）

特徵：不會 crash，但結果和預期不同。最難除的 bug。

你：計算訂單折扣的函數有問題：

    calcDiscount(1000, 'VIP') 應該回傳 200（8折），
    但實際回傳 0。
    
    calcDiscount(1000, 'normal') 回傳 100（9折），
    這個是對的。
    
    看起來 VIP 的分支有問題。
    
    檔案：src/lib/pricing.ts

技巧：給 Claude 正確的案例和錯誤的案例，讓它比較差異。

✅ 對的案例：calcDiscount(1000, 'normal') → 100 ✓
❌ 錯的案例：calcDiscount(1000, 'VIP') → 0（應該是 200）

類型 4：間歇性 Bug

特徵：有時候對有時候錯，難以重現。

你：上傳檔案偶爾會失敗，大約 1/10 的機率。
    錯誤訊息是 "Connection reset"。
    大檔案（> 5MB）比較容易失敗。
    
    src/api/upload.ts 是處理上傳的。
    
    你覺得可能的原因是什麼？
    先列出可能性，不要急著改。

技巧：先讓 Claude 列出可能的原因，不要直接讓它改。間歇性 bug 的根因通常不在最明顯的地方。

常見的間歇性原因：

Race condition
Timeout 設定太短
Memory 不足
連線池耗盡
檔案鎖定

類型 5：環境問題

特徵：在你的電腦上可以跑，在 CI/CD 或別人的電腦上不行。

你：本機 npm run build 沒問題，
    但 GitHub Actions 上失敗：

    [錯誤訊息]

    本機 Node 版本：18.17.0
    CI 的 Node 版本：20.11.0
    
    應該是版本差異的問題

技巧：給 Claude 兩個環境的差異，不只是錯誤訊息。

💡 進階除錯策略

策略 1：二分法

當你不知道 bug 是什麼時候引入的：

你：這個功能上週還正常，這週壞了。
    幫我用 git log 找出最近一週改了哪些檔案，
    列出可能影響這個功能的 commit

Claude 會分析 git log，找出嫌疑最大的 commit。

策略 2：最小重現

當 bug 涉及很多檔案時：

你：這個查詢在完整系統中跑會出錯，
    幫我寫一個最小的重現腳本，
    只包含出錯的核心邏輯

最小重現能排除無關因素，讓 Claude 專注在問題本身。

策略 3：加 log 追蹤

當你不確定程式執行到哪裡出問題：

你：在 src/lib/auth.ts 的 login 函數中，
    每個關鍵步驟加上 console.log，
    格式：[AUTH] 步驟描述 + 變數值
    
    我跑一次後把 log 貼給你

Claude 加完 log 後，你跑一次，把 log 貼回去：

你：log 輸出：
    [AUTH] 開始驗證 user=alice
    [AUTH] 查詢資料庫成功 user={id:1, name:'alice'}
    [AUTH] 檢查權限 role=undefined
    ← 問題在這裡，role 應該有值

    user 物件有 id 和 name 但沒有 role，
    看起來查詢少了 role 欄位

策略 4：讓 Claude 解釋再修

對於你看不懂的 bug：

你：先解釋為什麼這段程式碼會造成這個錯誤，
    用簡單的語言，
    確認我理解後再修

理解根因比直接修更重要——不然同樣的問題還會再出現。

策略 5：搭配 Subagent 平行除錯

如果有多個可能的原因：

你：這個 bug 可能是以下三個原因之一：
    1. 認證中間層沒有正確傳遞 user 物件
    2. 資料庫查詢少了 JOIN
    3. Session 過期但沒有正確處理
    
    同時幫我檢查這三個方向

Claude 可以派 Subagent 平行檢查三個方向，比一個一個查快三倍。

📋 除錯 Prompt 速查表

Bug 類型	給 Claude 什麼	prompt 範例
Build error	完整錯誤訊息	「build 失敗：[貼錯誤] 幫我修」
Runtime crash	Stack trace + 觸發條件	「登入時 crash：[貼 stack trace]」
結果不對	預期 vs 實際 + 檔案位置	「f(x) 應回傳 A 但回傳 B，檔案在 src/…」
間歇性	觸發條件 + 頻率	「1/10 機率失敗，大檔案容易出現」
環境差異	兩個環境的差異	「本機OK、CI失敗，Node 版本不同」
不知道原因	git log + 「上週還正常」	「幫我找最近改了什麼」
看不懂	「先解釋再修」	「解釋為什麼會出這個錯」

⚠️ 常見的除錯反模式

反模式 1：不給錯誤訊息

❌ "登入功能壞了"
✅ "登入時出現 401 Unauthorized，console 顯示 [貼錯誤]"

反模式 2：猜測原因後只告訴 Claude 你的猜測

❌ "我覺得是 Session 過期的問題，幫我修 Session"
✅ "登入後 5 分鐘會被踢出來，錯誤是 [貼錯誤]。
    我懷疑是 Session 過期，但不確定"

如果你只告訴 Claude 你的猜測，Claude 會照著你的方向走，即使你猜錯了。讓它看到原始錯誤，它可能會發現真正的原因。

反模式 3：一次丟太多 bug

❌ "以下是 20 個 bug，幫我修：
    1. ...
    2. ...
    ..."

✅ 一次一個 bug，修好確認後再下一個

反模式 4：不驗證修復結果

❌ Claude 修了 → 你說「好」→ 繼續下一個任務

✅ Claude 修了 → 你跑一次確認 → 確認修好了 → 繼續

Claude 的修復有時候只修了表面症狀，沒修到根因。跑一次確認是必要的。

🎉 結語

用 Claude Code 除錯的核心原則就兩個：

給完整的錯誤資訊：不要自己解讀，貼原文
給足夠的上下文：預期 vs 實際、環境資訊、觸發條件

做到這兩點，大多數 bug 都能在一兩次對話內修好。

對於複雜的 bug，善用分階段策略：先讓 Claude 分析原因，你理解後再讓它修。盲目修復可能會引入新的問題。

📎 相關文章：