N8N 工作流除錯完整指南：找到錯誤、讀懂日誌、快速修復

n8n 除錯是一套從定位錯誤節點、讀懂執行日誌、隔離測試到建立錯誤處理機制的系統化流程，透過 n8n 內建的執行紀錄與資料檢視工具，解決工作流「跑一半就掛、卻不知道哪裡出問題」的排查困境。

工作流昨天還好好的，今天跑到一半紅了一個節點，整條流程停擺。多數人此時的反應是憑感覺亂改，改到能跑為止——然後過幾天又掛。真正有效的做法是把除錯當成有步驟的流程：先看 n8n 告訴你的訊息，定位是哪個節點、什麼資料讓它出錯，再針對根因修。這份指南把這套流程從頭講到尾，並教你怎麼讓工作流以後自己回報問題，不用等它默默壞掉才發現。

這是 N8NMarket 的 n8n 除錯支柱文章，串連底下幾篇深入主題；建議搭配 n8n 常見錯誤 Top 10 一起看。

目錄

• 第一步：定位出錯的節點
• 讀懂 n8n 執行日誌
• 檢視節點的輸入與輸出資料
• 用 pin data 與分段測試找根因
• 常見錯誤類型與對策
• 表達式除錯
• 建立錯誤處理機制：讓流程自己回報
• Webhook 與排程的除錯眉角
• 除錯前的預防習慣
• 常見問題 FAQ

第一步：定位出錯的節點 {#定位}

n8n 除錯的起點永遠是：先確認是哪個節點失敗，不要憑印象猜。

當工作流執行失敗，n8n 會在畫布上把出錯的節點標成紅色，並在節點上顯示錯誤摘要。點開那個節點，右側會跳出錯誤訊息全文。這一步看似廢話，但很多人一看到流程紅了就開始改開頭，其實錯在中段，白白浪費時間。

定位節點時記住三件事：

• 紅色節點是「失敗」的節點，不一定是「根因」節點。 例如 HTTP Request 紅了，可能是它前面 Set 節點組錯了 URL。失敗點是症狀，根因可能在上游。
• 看執行的資料流向。 n8n 是由左往右一個個節點跑，紅色節點之前的節點都成功了，問題八成出在「進入紅色節點的那包資料」或「紅色節點自己的設定」。
• 同一個節點對不同資料可能時好時壞。 批次處理 100 筆時第 37 筆才掛，通常是那筆資料的格式特殊。

定位錯節點是整個除錯的地基，地基沒打對，後面全是亂槍打鳥。

讀懂 n8n 執行日誌 {#讀日誌}

n8n 左側選單的 Executions 頁面，是除錯時最重要的地方。它記錄每一次工作流執行的完整歷史。

進到 Executions，你會看到一張清單：

欄位	意義
Status	成功（綠）／失敗（紅）／執行中
Started	開始時間
Run time	執行耗時
Mode	觸發方式（手動／webhook／排程）

點任何一筆失敗紀錄，n8n 會把當時的畫布狀態完整還原——每個節點當下收到什麼、吐出什麼、哪裡紅了，全都在。這比「重跑一次看會不會再錯」有效太多，因為失敗當下的真實資料就在眼前。

讀日誌的重點技巧：

• 比對成功與失敗的執行。 找一筆成功的、一筆失敗的，並排看「進入出錯節點的資料」差在哪。差異處往往就是根因。
• 看 Run time 抓效能問題。 某節點突然從 2 秒變 40 秒，可能是外部 API 變慢或回傳爆量資料。
• 注意執行模式。 手動跑成功、排程跑失敗，差別常在環境變數或觸發時的資料來源不同，這類環境差異見 n8n 變數與環境設定。

檢視節點的輸入與輸出資料 {#檢視資料}

定位到節點後，下一步是看資料。n8n 每個節點都能檢視 Input（收到什麼）和 Output（吐出什麼）。

點開節點，切到 Input/Output 分頁，n8n 提供三種檢視：

• Table — 表格檢視，適合看欄位結構是否齊全。
• JSON — 原始 JSON，適合看巢狀結構與實際值。
• Schema — 欄位樹狀圖，適合快速確認某欄位到底存不存在、型別對不對。

除錯時最常見的真相是：節點設定沒錯，是進來的資料長得跟你以為的不一樣。 你以為某欄位叫 email，實際 API 回傳的是 user.contact.email，表達式自然抓到 undefined。打開 Input 的 JSON 一看就知道。

養成習慣：節點出錯，第一個動作是看它的 Input，確認資料結構真的是你預期的那樣。十次有七次問題在這。資料結構處理見 n8n 資料轉換 JSON 教學。

用 pin data 與分段測試找根因 {#分段測試}

當錯誤難以重現，或外部 API 每次回傳不同，pin data 是 n8n 除錯的利器。

Pin data：把資料釘住

在任何節點的 Output，點 Pin 圖示，n8n 會把這次的輸出資料「釘住」。之後重跑工作流，這個節點不會真的去呼叫外部 API，而是直接用釘住的資料往下傳。

這解決兩個痛點：

• 不用每次重跑都打外部 API——省額度、省時間，也避免測試污染正式資料。
• 用固定資料反覆測下游節點——把出問題的那包資料釘住，專心調後面的節點，輸入不再變動，問題好抓很多。

分段測試：縮小範圍

n8n 支援 Execute Node（只跑單一節點）和 Execute Previous Nodes（跑到這個節點為止）。用這兩個功能切開工作流：

1. 從頭跑到中段，確認前半段資料正確。
2. 釘住中段資料，單獨反覆測後半段。
3. 一個節點一個節點往下推，直到找到「輸入正確、輸出錯誤」的那個節點——它就是根因。

這套「二分逼近」的方法，比從頭到尾盯著整條流程看快得多，本質上就是經典的二分搜尋思路套用在除錯上。複雜流程更該善用子流程切分，讓每段獨立可測，見 n8n Sub-workflow 可重用設計。

常見錯誤類型與對策 {#常見錯誤}

n8n 的錯誤大致分四類，對策各不同。

1. 連線／認證錯誤

訊息常見 401 Unauthorized、403 Forbidden、ECONNREFUSED。原因多半是憑證過期、API Key 錯、或端點打錯環境。先檢查 Credentials 是否有效，憑證設定見 n8n 憑證設定教學。

2. 資料格式錯誤

訊息如 Cannot read property 'x' of undefined、is not iterable。幾乎都是「資料結構跟預期不符」，回到上一段的 Input 檢視就能抓。

3. 表達式錯誤

{{ }} 裡寫錯語法或引用不存在的欄位，下一段細講。

4. 速率限制／逾時

429 Too Many Requests、ETIMEDOUT。外部 API 擋你太頻繁或回應太慢，對策是加重試與延遲，見 n8n 錯誤處理與重試機制。完整的錯誤訊息對照見 n8n 常見錯誤 Top 10；n8n 官方也維護一份錯誤處理文件可對照。

表達式除錯 {#表達式}

表達式（{{ }}）是 n8n 出錯重災區，因為它在執行時才解析，編輯時看不出對錯。

除錯技巧：

• 用節點的表達式編輯器即時預覽。 n8n 在表達式欄位下方會顯示「目前會解析成什麼」，直接看結果對不對，不用整條跑。
• 先確認欄位真的存在。 {{ $json.user.email }} 報錯，先到 Input 的 Schema 分頁確認 user.email 這條路徑真的有。
• 用 ?. 防 undefined。 不確定欄位一定存在時，{{ $json.user?.email }} 比 {{ $json.user.email }} 安全，後者遇到 user 不存在會直接炸。
• 分步驟拆複雜表達式。 一行寫了三層轉換又報錯，拆成多個 Set 節點，一步一個值，哪步錯一目了然。

表達式的完整語法與常用範例見 n8n 表達式速查表。

建立錯誤處理機制：讓流程自己回報 {#錯誤處理}

除錯到這裡都是「壞掉之後去查」。更高段的做法是讓工作流壞掉時主動通知你，而不是默默失敗等你某天發現。

n8n 提供 Error Workflow 機制：

1. 建一條專門的錯誤處理工作流，開頭放 Error Trigger 節點。
2. 裡面接「組錯誤訊息 → 發 Slack／Email 通知」。
3. 到要監控的工作流設定（Settings → Error Workflow），指定剛建的錯誤工作流。

之後只要被監控的工作流任何一次執行失敗，n8n 會自動觸發錯誤工作流，把失敗的工作流名稱、出錯節點、錯誤訊息打包通知你。這條通知邏輯很適合抽成可重用子流程，見 n8n Sub-workflow 可重用設計。

進階一點，可在關鍵節點開啟 Continue On Fail，讓單一節點失敗不中斷整條流程，改由後續 IF 節點判斷錯誤分支處理。搭配死信佇列（DLQ）保留失敗資料、稍後重放，是正式環境的標配，完整模式見 n8n 錯誤處理與重試機制。

Webhook 與排程的除錯眉角 {#webhook}

非手動觸發的工作流，除錯方式不太一樣。

Webhook 除錯：用測試 URL（n8n 提供 Test 與 Production 兩組 webhook URL）。測試模式下，n8n 會即時把收到的請求顯示在畫布上，你能直接看到外部送進來的真實 payload。記得正式 webhook URL 由 WEBHOOK_URL 環境變數決定，環境設錯會導致回呼打到錯的機器，見 n8n 變數與環境設定。

排程除錯：排程觸發無法即時盯著看。靠的是前面講的 Executions 日誌——排程跑完，到 Executions 看那筆紀錄即可。常見坑是時區：n8n 的排程依 GENERIC_TIMEZONE 設定，沒設對就會在錯的時間觸發。

除錯前的預防習慣 {#預防}

最好的除錯是不用除錯。幾個能大幅減少出錯的習慣：

• 節點命名清楚。 把 HTTP Request 改名成 取得訂單 API，出錯時一眼知道是哪段。
• 關鍵節點後加 Set 整理欄位。 把雜亂的 API 回傳整理成乾淨的內部格式，下游不用每次面對不同結構。
• 重要流程接 Error Workflow。 上線前就接好錯誤通知，不要等出事才補。
• 改動前先複製一份。 大改之前匯出備份，改壞能還原，備份流程見 n8n 備份與升級 SOP。
• 用環境變數隔離測試與正式。 在測試環境改到飽，確認沒問題再上正式，見 n8n 變數與環境設定。

常見問題 FAQ {#faq}

n8n 工作流失敗了，第一步該做什麼？

先到畫布看哪個節點標紅、點開看錯誤訊息全文，再到 Executions 頁面打開那筆失敗紀錄，檢視進入出錯節點的輸入資料。先定位節點與資料，不要憑印象亂改。

怎麼在不重跑外部 API 的情況下反覆測試？

用 pin data 功能。在節點的 Output 點 Pin 把資料釘住，之後重跑工作流時該節點不會真的呼叫外部 API，而是直接用釘住的資料往下傳，方便專心調試下游節點。

n8n 可以在出錯時自動通知我嗎？

可以。建一條開頭放 Error Trigger 的錯誤處理工作流，接上 Slack 或 Email 通知，再到目標工作流的 Settings → Error Workflow 指定它。之後該工作流任何一次失敗都會自動觸發通知。

表達式一直報 undefined 怎麼辦？

先到節點 Input 的 Schema 分頁確認你引用的欄位路徑真的存在，欄位名稱常和你以為的不同。不確定欄位是否存在時，用 ?. 選擇性串連（如 $json.user?.email）避免直接報錯。

排程觸發的工作流怎麼除錯？

排程無法即時盯著看，靠 Executions 日誌：排程跑完到該頁打開對應紀錄查看。若觸發時間不對，多半是 GENERIC_TIMEZONE 時區沒設正確。

---

n8n 除錯不是靠手感，而是靠流程：定位節點 → 讀日誌 → 看資料 → 分段逼近根因 → 對症修復 → 接上錯誤處理讓它以後自己回報。把這套走熟，工作流壞掉對你就不再是慌張，而是一條清楚的查修路徑。

想持續精進 n8n 實戰，追蹤 N8NMarket 每週 n8n 精選。