n8n 工作流程除錯診斷提示詞

用途

系統性診斷 n8n 工作流程失敗原因，提供根因分析、5 分鐘快速驗證步驟、修復方案與預防設計建議。

何時用

適合：n8n workflow 執行失敗、行為異常（跑了但輸出不對）、特定節點報錯或無輸出時；上線後忽然壞掉、找不到原因時。
不要用：設計全新流程不要用這個診斷提示語——這是偵錯工具，不是設計工具；如果你的問題是「不確定用哪種架構」，請用架構模式選擇器。

Prompt

text

我的 n8n 工作流程出問題了，請幫我做系統性診斷。

流程用途：
{{流程用途——這個 workflow 應該做什麼}}

問題描述：
{{問題描述——症狀是什麼：報錯 / 無輸出 / 輸出不正確 / 跑了沒反應}}

錯誤訊息（如有）：
{{錯誤訊息——從 n8n 執行日誌複製完整訊息}}

節點順序：
{{節點順序——如：Webhook → IF → Code → HTTP Request → Notion}}

輸入資料範例（如有）：
{{輸入資料範例——貼觸發節點收到的資料 JSON}}

請輸出：
1. 根因分析（列 3 個最可能的原因，按機率高到低排序，每個原因 2-3 句說明）
2. 5 分鐘快速驗證步驟（在 n8n 裡怎麼確認是哪個原因）
3. 修復方案（針對最高機率原因，給具體修復步驟）
4. 預防設計（這次的根因，未來怎麼設計可以避免再發生）

範例 / 變體

填好變數：流程用途「Gmail 新信觸發 → 分類打標籤 → 摘要存 Notion」；問題「Notion 節點沒寫入，但前面節點顯示成功」；錯誤訊息貼 Error: Notion API returned 400 - body failed validation；節點順序「Gmail Trigger → Code → Notion」。
變體（只有症狀沒有錯誤訊息）：錯誤訊息欄填「無，節點顯示成功但下游沒資料」，AI 會改從資料格式問題切入診斷。
變體（定期失敗型）：問題描述填「每天早上 8 點跑，週一到週四 OK，週五固定失敗」，AI 會優先診斷時區、限流（rate limit）、外部 API 週期性問題。

🎯 範例輸出（實測）

在 Claude.ai 跑這句、把 {{變數}} 填成「流程：Gmail 新信 → 分類打標籤 → 存 Notion；問題：Notion 節點沒寫入但前面顯示成功；錯誤：Notion API 400 body failed validation；節點：Gmail Trigger → Code → Notion」的結果：

點開看 AI 實際輸出

1. 根因分析（按機率排序）

可能原因 1（機率最高）：Notion 欄位型別不符

Notion Database 的欄位型別（如 Select、Multi-select、Relation）需要特定格式，直接傳字串會 400。例如 Select 欄位需傳 {"select": {"name": "標籤名"}} 而非純字串 "標籤名"。Code 節點輸出的資料格式若沒包成 Notion property 格式，就會觸發 body failed validation。

可能原因 2（機率中）：Title 欄位缺失或名稱不對

每個 Notion Database 必須有 Title 欄位，且 n8n Notion 節點的 Title 設定要對應到 database 中實際命名的 title property（預設叫 "Name"，若改過名就會失敗）。

可能原因 3（機率低）：Notion API Token 權限範圍不足

Integration 未被加入目標 Database，或 Token 只有 read 權限沒有 write，API 回 400 時錯誤訊息跟格式錯誤相似，容易混淆。

2. 5 分鐘快速驗證步驟

在 n8n Notion 節點右鍵 → "Execute Single Node"，看原始 API 請求 body
複製 body，到 Notion API Playground 手動貼上送出，確認是否同樣 400
對比 n8n 節點設定中的 Property 名稱與 Notion Database 實際欄位名稱（大小寫、空格都要完全一致）

3. 修復方案（針對原因 1）

在 Code 節點輸出改成 Notion property 格式：

text

// 把純字串改成 Notion Select 格式
return [{ json: {
  title: [{ text: { content: subject } }],
  label: { select: { name: category } },
  created_date: { date: { start: new Date().toISOString() } }
}}];

4. 預防設計

在 Code 節點加「格式驗證」子步驟：輸出前用 if (!result.title) throw new Error('title 缺失') 檢查必填欄位，讓錯誤在 Code 節點就暴露，而不是等 Notion API 才報 400。

💡 實測心得：把完整錯誤訊息（不只截圖、要貼文字）和節點順序一起給 AI，診斷精準度大幅提升；「節點顯示成功但下游沒資料」通常是 Code 節點輸出格式問題，不是 Notion 的問題。

延伸

簡單來說，n8n 除錯最常見的三大類問題：資料格式不符（欄位名錯、型別錯）、API 驗證失敗（token 過期、權限不夠）、節點設定問題（mode 選錯、JSON path 寫錯）。把這三類放在根因分析的第一優先，通常能在 15 分鐘內找到問題。

如果修完後發現是架構根本設計錯了，用「n8n 需求描述轉規格文件」重新設計，再重建。

n8n 工作流程除錯診斷提示詞 ​

用途 ​

何時用 ​

Prompt ​

範例 / 變體 ​

🎯 範例輸出（實測） ​

1. 根因分析（按機率排序） ​

2. 5 分鐘快速驗證步驟 ​

3. 修復方案（針對原因 1） ​

4. 預防設計 ​

延伸 ​