n8n 學習地圖

n8n 除錯實驗室

這一篇不再講抽象原理，而是直接處理你在 n8n 最常遇到的失敗現場。

想一想

很多人學 n8n 卡住，不是因為不努力，而是因為除錯順序錯了。明明問題在 input 欄位，卻去改 credential；明明是 response 結構變了，卻一直重跑同一個 prompt。除錯不是亂試，而是把問題縮小。

你在 n8n 裡最有價值的能力，不是會記多少 node，而是能不能在 3 分鐘內回答這四題：哪一個 node 壞了？壞之前的 input 長什麼樣？壞掉時實際報了什麼錯？如果把 workflow 切成最小步驟，哪一步先能證明是正常的？只要這四題能回答，很多問題其實很快就會變簡單。

本篇怎麼讀

  • 學習目標：建立穩定的除錯順序，知道常見錯誤怎麼定位
  • 先修需求：至少看過 Execution、JSON、HTTP Request 的基本觀念
  • 讀完後你應該能：看錯誤現象、判斷問題層級、知道先改哪裡

目錄

  1. 除錯時第一件事不是重跑
  2. 一條最小除錯順序
  3. 5 個最常見錯誤現象
  4. Expression 類錯誤
  5. Webhook 類錯誤
  6. API 類錯誤
  7. Google Sheets 類錯誤
  8. OpenAI 類錯誤
  9. 卡很久時怎麼縮小問題
  10. 除錯檢查表

1. 除錯時第一件事不是重跑

很多新手一看到紅字就一直按 Execute workflow。這通常沒用。

先做這三件事：

  1. 找出是哪一個 node 先紅掉
  2. 打開它的 input / output / error message
  3. 判斷問題是資料、設定、還是外部服務

如果連哪一層出錯都沒搞清楚，重跑只是在浪費時間。

2. 一條最小除錯順序

照這個順序查，速度通常最快：

  1. 先看是哪個 node 壞
  2. 再看上一個 node 的 output
  3. 再看這個 node 實際收到的 input
  4. 再看你填的 expression / 欄位 mapping / credential
  5. 最後才懷疑 API、網路或第三方服務

一句話記住： 先看資料，再看設定，最後才看外部服務。

3. 5 個最常見錯誤現象

3.1 沒有資料進來

  • 常見原因：trigger 沒真的觸發、測試模式沒打到、workflow 沒啟用
  • 先查：trigger node 的 execution 有沒有產生

3.2 有資料進來，但欄位是空的

  • 常見原因：expression 路徑寫錯、資料其實在更深層、上一個 node 已經改結構
  • 先查：上一個 node 的 output JSON

3.3 API 回 400 / 401 / 403

  • 常見原因：body 錯、header 錯、token 錯、權限不夠
  • 先查：status code 與 response body

3.4 Google Sheets 寫進去了，但欄位亂掉

  • 常見原因：欄位名稱對不到、資料型別混亂、mapping 沒對齊
  • 先查：Set 節點整理後的欄位長相

3.5 OpenAI 有回應，但內容不對

  • 常見原因：輸入欄位抓錯、prompt 太模糊、前面給模型的資料不完整
  • 先查：送進模型的原始文字到底是什麼

4. Expression 類錯誤

錯誤現象：

  • undefined
  • 欄位是空字串
  • IF 判斷跟預期不同

最常見原因：

  • 寫成 {{$json.name}}，但資料其實在 {{$json.body.name}}
  • node 改名後，expression 還指向舊 node
  • 數字其實是字串

修法：

  1. 直接打開 output，不要用猜的
  2. 找出欄位真正路徑
  3. 先用最短 expression 測一次

5. Webhook 類錯誤

錯誤現象：

  • LINE / Postman / curl 打過來沒反應
  • Cloudflare 或外部平台回 404
  • 有收到 request，但對方拿不到預期 response

最常見原因：

  • 打到 test URL，但 workflow 沒在 listening
  • 打到 production URL，但 workflow 沒 publish / activate
  • 少接 Respond to Webhook

修法：

  1. 先分清楚你現在用的是 test 還是 production
  2. 確認 workflow 是否真的 active
  3. 確認回應節點有沒有接上

6. API 類錯誤

錯誤現象：

  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found

對照表：

  • 400：通常是 body、欄位、格式錯
  • 401：通常是 token 錯或過期
  • 403：通常是權限不足
  • 404：通常是 URL、path、resource id 打錯

修法順序：

  1. URL
  2. Method
  3. Auth
  4. Headers
  5. Body
  6. Response body

7. Google Sheets 類錯誤

錯誤現象：

  • 寫不進去
  • 寫到錯的 sheet
  • 欄位順序怪掉

最常見原因：

  • credential 沒授權成功
  • spreadsheet id / sheet 名稱填錯
  • 前面整理欄位時名稱不一致

修法：

  1. 先手動確認 Google Sheets credential 可用
  2. 先只寫 2 到 3 個欄位做最小測試
  3. 成功後再補完整欄位

8. OpenAI 類錯誤

錯誤現象：

  • 模型不回
  • 回太慢
  • 回了但內容偏掉

最常見原因：

  • credential 錯
  • 模型名稱不對
  • 輸入文字其實是空的或抓錯欄位
  • prompt 沒有限定輸出格式

修法：

  1. 先確認模型節點收到的文字不是空值
  2. 先把 prompt 縮到最小
  3. 先只要求摘要或分類，不要一次做太多事

9. 卡很久時怎麼縮小問題

最有效的方法，是把 workflow 切成最小閉環。

例如原本： Webhook -> Set -> OpenAI -> Google Sheets -> Slack

先縮成： Webhook -> Set

如果這一步正常，再加： Webhook -> Set -> OpenAI

這樣你很快就能知道問題在哪一段，而不是一次懷疑全部。

10. 除錯檢查表

每次卡住，照著檢查：

  • 我知道是哪個 node 先出錯嗎
  • 我看過上一個 node 的 output 了嗎
  • 我知道這個 node 實際收到什麼 input 嗎
  • 我有先做最小版本測試嗎
  • 我現在改的是資料、設定，還是外部服務
  • 我有沒有一次改太多地方

本篇練習

  1. 找一個失敗過的 workflow，照本篇順序重查一次。
  2. 用 Webhook -> Set -> Respond to Webhook 做一個最小閉環。
  3. 故意把一個 expression 寫錯，觀察 input / output / error message。
  4. 把一個大 workflow 切成兩段測試。

下一步建議

如果你卡在 expression，回去看 04 n8n Expression 完全指南。
如果你卡在 HTTP Request，回去看 05 n8n API 串接觀念與除錯手冊。
如果你要看實戰流程，回去看 03 n8n 實戰手冊：Webhook、Google Sheets、OpenAI。