n8n-workflow-patterns

n8n 工作流程模式

經過驗證的 n8n 工作流程建構架構模式。

---

6 大核心模式

基於真實工作流程使用情況分析：

1. Webhook 處理（最常見）

   • 接收 HTTP 請求 → 處理 → 輸出
   • 模式：Webhook → 驗證 → 轉換 → 回應/通知

2. HTTP API 整合

   • 從 REST API 擷取 → 轉換 → 儲存/使用
   • 模式：觸發器 → HTTP 請求 → 轉換 → 動作 → 錯誤處理器

3. 資料庫操作

   • 讀取/寫入/同步資料庫資料
   • 模式：排程 → 查詢 → 轉換 → 寫入 → 驗證

4. AI 代理工作流程

   • 具有工具和記憶體的 AI 代理
   • 模式：觸發器 → AI 代理（模型 + 工具 + 記憶體）→ 輸出

5. 排程任務

   • 定期自動化工作流程
   • 模式：排程 → 擷取 → 處理 → 傳送 → 記錄

6. 批次處理（如下）

   • 以區塊處理大型資料集，並遵守 API 速率限制
   • 模式：準備 → SplitInBatches → 每批次處理 → 累積 → 彙總

---

模式選擇指南

何時使用每種模式：

Webhook 處理 - 用於：

• 從外部系統接收資料
• 建立整合（Slack 指令、表單提交、GitHub webhook）
• 需要即時回應事件
• 範例：「接收 Stripe 付款 webhook → 更新資料庫 → 發送確認」

HTTP API 整合 - 用於：

• 從外部 API 擷取資料
• 與第三方服務同步
• 建立資料管道
• 範例：「擷取 GitHub issue → 轉換 → 建立 Jira 工單」

資料庫操作 - 用於：

• 資料庫之間的同步
• 依排程執行資料庫查詢
• ETL 工作流程
• 範例：「讀取 Postgres 記錄 → 轉換 → 寫入 MySQL」

AI 代理工作流程 - 用於：

• 建立對話式 AI
• 需要具有工具存取權的 AI
• 多步驟推理任務
• 範例：「與可搜尋文件、查詢資料庫、發送電子郵件的 AI 聊天」

排程任務 - 用於：

• 定期報告或摘要
• 定期資料擷取
• 維護任務
• 範例：「每日：擷取分析資料 → 產生報告 → 透過電子郵件發送團隊」

批次處理 - 用於：

• 處理超過 API 批次限制的大型資料集
• 需要跨多個 API 呼叫累積結果
• 巢狀迴圈（例如，多個類別 × 每個類別的分頁 API 呼叫）
• 範例：「為 4 個市場擷取產品 × 每次 API 呼叫 1000 筆 → 彙總所有結果」

---

常見工作流程元件

所有模式都共享這些建構區塊：

1. 觸發器

• Webhook - HTTP 端點（即時）
• 排程 - 基於 Cron 的定時（定期）
• 手動 - 點擊執行（測試）
• 輪詢 - 檢查變更（間隔）

2. 資料來源

• HTTP 請求 - REST API
• 資料庫節點 - Postgres、MySQL、MongoDB
• 服務節點 - Slack、Google Sheets 等
• 程式碼 - 自訂 JavaScript/Python

3. 轉換

• Set - 對應/轉換欄位
• 程式碼 - 複雜邏輯
• IF/Switch - 條件路由
• Merge - 合併資料流

4. 輸出

• HTTP 請求 - 呼叫 API
• 資料庫 - 寫入資料
• 通訊 - 電子郵件、Slack、Discord
• 儲存 - 檔案、雲端儲存

5. 錯誤處理

• 錯誤觸發器 - 捕捉工作流程錯誤
• IF - 檢查錯誤條件
• Stop and Error - 明確失敗
• 繼續執行（失敗時） - 每個節點設定

---

工作流程建立檢查清單

建立任何工作流程時，請遵循此檢查清單：

規劃階段

• [ ] 識別模式（webhook、API、資料庫、AI、排程）
• [ ] 列出所需節點（使用 search_nodes）
• [ ] 了解資料流程（輸入 → 轉換 → 輸出）
• [ ] 規劃錯誤處理策略

實作階段

• [ ] 使用適當的觸發器建立工作流程
• [ ] 新增資料來源節點
• [ ] 設定驗證/憑證
• [ ] 新增轉換節點（Set、Code、IF）
• [ ] 新增輸出/動作節點
• [ ] 設定錯誤處理

驗證階段

• [ ] 驗證每個節點設定（validate_node）
• [ ] 驗證完整工作流程（validate_workflow）
• [ ] 使用範例資料測試
• [ ] 處理邊緣情況（空資料、錯誤）

部署階段

• [ ] 檢視工作流程設定（執行順序、逾時、錯誤處理）
• [ ] 使用 activateWorkflow 操作啟用工作流程
• [ ] 監控首次執行
• [ ] 記錄工作流程目的和資料流程

---

工作流程生命週期：啟用前先驗證、確認、測試

建立節點只是開始，不是結束。在工作流程上線前，請通過四個關卡——並記住標題規則：驗證通過是必要條件，但不是充分條件。 一個工作流程可以驗證通過，但仍然會遺失項目、選錯 Merge 輸入，或以純文字形式發布 Slack 訊息。乾淨的驗證只表示形狀正確，不代表邏輯正確。

1. 驗證。 在建置期間對完整 JSON 執行 validate_workflow，或在工作流程存在於實例後執行 n8n_validate_workflow({ id })。修正每個錯誤並重新驗證。這會捕捉結構層的 schema、節點設定、運算式和參考錯誤。
2. 確認連線。 使用 n8n_get_workflow({ id }) 拉取工作流程，並直接讀取 connections 物件。驗證確認連線沒有中斷；它不確認連線是否正確。這是你會發現有效但接錯線的地方：Merge 的 useDataOfInput 與連線插槽不符、Switch 的 fallback 未連接到任何東西、分支從未接線到後續節點、錯誤輸出沒有去處。（請參閱 n8n Node Configuration 技能的 NODE_FAMILY_GOTCHAS.md 以了解無聲錯誤。）
3. 測試。 執行 n8n_test_workflow 並透過 n8n_executions 檢查輸出。確認輸出形狀符合消費者的預期、所有分支都產生了資料，並且（對於 webhook API）狀態/主體/標頭正確。測試期間會觸發真實的副作用——寫入會提交、訊息會發送、外部 API 會被呼叫。如果任何節點有使用者可見的副作用，請在使用者確認後再執行，或先針對安全資料進行測試。
4. 僅在前三步通過後才啟用——使用 n8n_update_partial_workflow 搭配 activateWorkflow 操作。不要在乾淨驗證後就直接啟用；一個會遺失資料或重複發送的活躍工作流程，比從未啟動的更糟。

跳過任何關卡，就是用現在幾分鐘的時間，換取之後除錯一個可能具有狀態、可能承載流量的線上工作流程。這個交易從來不值得。

---

資料流程模式

線性流程

觸發器 → 轉換 → 動作 → 結束

用於：具有單一路徑的簡單工作流程

分支流程

觸發器 → IF → [True 路徑]
             └→ [False 路徑]

用於：根據條件執行不同動作

並行處理

觸發器 → [分支 1] → Merge
       └→ [分支 2] ↗

用於：可以同時執行的獨立操作

迴圈模式

觸發器 → Split in Batches → 處理 → 迴圈（直到完成）

用於：以區塊處理大型資料集

錯誤處理器模式

主要流程 → [成功路徑]
         └→ [錯誤觸發器 → 錯誤處理器]

用於：需要獨立的錯誤處理工作流程

---

批次處理模式

SplitInBatches 迴圈

SplitInBatches 節點將大型資料集分割成較小的區塊進行處理。了解其輸出至關重要：

• main[0] = 完成 — 在所有批次完成後觸發一次
• main[1] = 每個批次 — 每個批次觸發一次（這是迴圈主體）

準備項目 → SplitInBatches → [main[1]: 處理批次] → （迴圈回去）
                                  [main[0]: 完成] → Limit 1 → 彙總

務必在完成輸出後新增一個 Limit 1 節點。

選擇 batchSize（成本槓桿）

SplitInBatches 迴圈每次迭代都會重新執行整個主體——每次迭代約 0.8 毫秒的引擎開銷加上主體本身的成本——因此總成本約為 ⌈items / batchSize⌉ × (overhead + body)。batchSize 是一個直接的加速旋鈕：

• 選擇實際限制允許的最大 batchSize（API 頁面大小、速率限制、記憶體）。較大的批次 = 較少的迭代 = 較少的開銷；主體仍然會處理每個項目。
• batchSize: 1 是最昂貴的極端——每個項目一次完整的引擎傳遞。僅在必須一次處理一個項目時使用（巢狀迴圈控制，或只接受一個 id 的 API）。
• 如果你只是為了「遍歷項目」而迴圈，且沒有外部限制，通常不需要迴圈——單一的 All Items Code 節點處理整個集合的成本要低得多。

跨迭代資料

迴圈結束後，$('Node Inside Loop').all() 只會回傳最後一個批次的項目。要跨所有迭代累積，請在迴圈內的 Code 節點中使用 $getWorkflowStaticData('global')。完整模式請參閱 n8n Code JavaScript 技能。

巢狀迴圈

當處理 N 個類別 × 每個類別 M 個項目（API 有批次限制）時：

定義類別（N 個項目）
  → 外層迴圈（SplitInBatches, batchSize=1）
    → 準備類別資料
    → 內層迴圈（SplitInBatches, batchSize=1000）
      → API 呼叫 → 驗證 → （透過 main[1] 迴圈回內層迴圈）
    → 內層完成[0] → 速率限制延遲 → 回到外層迴圈
  → 外層完成[0] → Limit 1 → 最終彙總

接線陷阱：內層完成[0]必須連回外層迴圈輸入，而不是彙總。外層完成[0]饋入最終彙總。

API 分頁

對於沒有多 ID 過濾的 API，使用 id_from 加上日期視窗進行高效分頁：

排程 → 設定日期視窗 → 擷取頁面 → 處理
  → IF 還有更多？ → [true] 更新 id_from → 擷取頁面（迴圈）
                  → [false] → 彙總 → 輸出

乾執行 / 驗證容錯

當測試時 API 寫入節點被停用（用於乾執行），下游驗證節點會收到請求主體而非回應。讓驗證具有容錯性：

// 在驗證 Code 節點中
const body = $input.first().json;
const looksLikeRequest = body.method && body.parameters && !body.status;
if (looksLikeRequest) {
  return [{ json: { status: 'SKIPPED', message: '上游已停用用於測試' }}];
}
// 以下為正常回應驗證...

---

熱路徑效能

當工作流程處理數千個項目且 I/O 很少時，其速度取決於 n8n 跨越每個項目/每次迭代邊界的次數——每次跨越都會建立執行上下文並複製項目。四個架構選擇主導效能：

1. 偏好更少、更胖的 All-Items 節點，而非長轉換鏈。 每個節點→節點跳躍都會重新複製所有項目（每次跳躍約 0.05 毫秒/項目），因此六個串聯的 Code/Set 節點的成本約為執行相同步驟的單一 All-Items Code 節點的 7 倍。合併熱路徑。
2. 使用 Code「Run Once for All Items」，而非「Each Item」——約 0.02 毫秒/項目 vs 約 0.6 毫秒/項目（約 25–30 倍）。Each-Item Code 節點的鏈是最糟的情況；每個項目的稅金會乘以節點數量。
3. 最大化 SplitInBatches 迴圈中的 batchSize（請參閱上面的批次處理模式）——迭代是成本所在。
4. 不要微調運算式——複雜度是免費的；節點和迭代次數才是你付出的成本。

但先做效能分析。 大多數生產工作流程是 I/O 密集型——順序的 HTTP / DB / Sheets 呼叫（每個數百毫秒）使上述所有因素相形見絀。這些規則在轉換工作是瓶頸時，或反模式（Each-Item Code、batchSize 1、長每個項目鏈）將低成本操作變成慢速操作時才重要。在少於幾百個項目時，這些都不重要。n8n Code JavaScript 技能有完整的測量模型。

---

整合特定陷阱

Google Sheets

• 絕對不要對有公式欄位的試算表使用 append——它會破壞公式。使用 Google Sheets API values.update（PUT）透過 HTTP Request 節點搭配 googleApi 憑證
• 對依賴公式的欄位寫入數字，而非字串——字串 "4.98" 會破壞 ADD() 公式。在 Code 節點中使用 parseFloat()
• 每個項目執行陷阱：Google Sheets 節點對每個輸入項目執行一次。如果你需要單次大量寫入，先在 Code 節點中將項目彙總為一個
• UNFORMATTED_VALUE 回傳數字，而非像 "N/A" 的文字——在 Code 節點中明確過濾

Google Drive

• convertToGoogleDocument: true 會建立 Google 文件（文字），而非 Google 試算表——要上傳 CSV 供下載，請完全省略此選項
• CSV 下載連結格式：https://drive.google.com/uc?id={fileId}&export=download——使用此格式而非 /view 連結

雙向閾值檢查

比較值（價格、數量、指標）時，務必檢查兩個方向：

// ❌ 只捕捉增加
if (diff > threshold) { flag(); }

// ✅ 同時捕捉暴漲和暴跌——兩者都是資料品質訊號
if (Math.abs(diff) > threshold) { flag(); }

---

常見陷阱

1. Webhook 資料結構

問題：無法存取 webhook 負載資料

解決方案：資料巢狀於 $json.body 下

❌ {{$json.email}}
✅ {{$json.body.email}}

請參閱：n8n Expression Syntax 技能

2. 多個輸入項目

問題：節點處理所有輸入項目，但我只想要一個

解決方案：使用「Execute Once」模式或僅處理第一個項目

{{$json[0].field}}  // 僅第一個項目

3. 驗證問題

問題：API 呼叫失敗，出現 401/403

解決方案：

• 正確設定憑證
• 使用「Credentials」區段，而非參數
• 在工作流程啟用前測試憑證

4. 節點執行順序

問題：節點以非預期順序執行

解決方案：檢查工作流程設定 → 執行順序

• v0：從上到下（舊版）
• v1：基於連線（建議）

5. 運算式錯誤

問題：運算式顯示為文字

解決方案：在運算式周圍使用 {{}}

• 詳情請參閱 n8n Expression Syntax 技能

---

與其他技能的整合

這些技能可與工作流程模式搭配使用：

n8n MCP Tools Expert - 用於：

• 為你的模式尋找節點（search_nodes）
• 了解節點操作（get_node）
• 建立工作流程（n8n_create_workflow）
• 部署範本（n8n_deploy_template）
• 使用 tools_documentation({topic: "ai_agents_guide", depth: "full"}) 取得 AI 模式指導
• 使用 n8n_manage_datatable 管理資料表

n8n Expression Syntax - 用於：

• 在轉換節點中編寫運算式
• 正確存取 webhook 資料（{{$json.body.field}}）
• 參考先前的節點（{{$node["Node Name"].json.field}}）

n8n Node Configuration - 用於：

• 設定模式節點的特定操作
• 了解節點特定需求

n8n Validation Expert - 用於：

• 驗證工作流程結構
• 修正驗證錯誤
• 確保工作流程在部署前正確

---

模式統計

常見工作流程模式：

最常見觸發器：

1. Webhook - 35%
2. 排程（定期任務） - 28%
3. 手動（測試/管理） - 22%
4. 服務觸發器（Slack、電子郵件等） - 15%

最常見轉換：

1. Set（欄位對應） - 68%
2. Code（自訂邏輯） - 42%
3. IF（條件路由） - 38%
4. Switch（多條件） - 18%

最常見輸出：

1. HTTP 請求（API） - 45%
2. Slack - 32%
3. 資料庫寫入 - 28%
4. 電子郵件 - 24%

平均工作流程複雜度：

• 簡單（3-5 個節點）：42%
• 中等（6-10 個節點）：38%
• 複雜（11+ 個節點）：20%

---

快速入門範例

範例 1：簡單 Webhook → Slack

1. Webhook（路徑："form-submit"，POST）
2. Set（對應表單欄位）
3. Slack（發送訊息到 #notifications）

範例 2：排程報告

1. 排程（每天上午 9 點）
2. HTTP 請求（擷取分析資料）
3. Code（彙總資料）
4. 電子郵件（發送格式化報告）
5. 錯誤觸發器 → Slack（失敗時通知）

範例 3：資料庫同步

1. 排程（每 15 分鐘）
2. Postgres（查詢新記錄）
3. IF（檢查記錄是否存在）
4. MySQL（插入記錄）
5. Postgres（更新同步時間戳）

範例 4：AI 助理

1. Webhook（接收聊天訊息）
2. AI Agent
   ├─ OpenAI Chat Model（ai_languageModel）
   ├─ HTTP Request Tool（ai_tool）
   ├─ Database Tool（ai_tool）
   └─ Window Buffer Memory（ai_memory）
3. Webhook Response（發送 AI 回覆）

範例 5：API 整合

1. 手動觸發器（用於測試）
2. HTTP 請求（GET /api/users）
3. Split In Batches（一次處理 100 筆）
4. Set（轉換使用者資料）
5. Postgres（更新或插入使用者）
6. 迴圈（回到步驟 3 直到完成）

---

詳細模式檔案

有關每種模式的全面指導：

• webhook_processing.md - Webhook 模式、資料結構、回應處理
• http_api_integration.md - REST API、驗證、分頁、重試
• database_operations.md - 查詢、同步、交易、批次處理
• ai_agent_workflow.md - AI 代理、工具、記憶體、langchain 節點
• scheduled_tasks.md - Cron 排程、報告、維護任務

---

真實範本範例

來自 n8n 範本庫：

範本 #2947：天氣到 Slack

• 模式：排程任務
• 節點：排程 → HTTP 請求（天氣 API）→ Set → Slack
• 複雜度：簡單（4 個節點）

Webhook 處理：最常見模式

• 最常見：表單提交、付款 webhook、聊天整合

HTTP API：常見模式

• 最常見：資料擷取、第三方整合

資料庫操作：常見模式

• 最常見：ETL、資料同步、備份工作流程

AI 代理：使用量成長中

• 最常見：聊天機器人、內容生成、資料分析

使用 n8n-mcp 工具的 search_templates 和 get_template 尋找範例！

---

最佳實務

✅ 要

• 從解決問題的最簡單模式開始
• 在建置前規劃工作流程結構
• 在所有工作流程上使用錯誤處理
• 在啟用前使用範例資料測試
• 遵循工作流程建立檢查清單
• 使用描述性節點名稱
• 記錄複雜工作流程（備註欄位）
• 部署後監控工作流程執行

❌ 不要

• 一次建置完整工作流程（迭代！編輯間隔平均 56 秒）
• 在啟用前跳過驗證
• 忽略錯誤情境
• 在簡單模式足夠時使用複雜模式
• 在參數中硬編碼憑證
• 忘記處理空資料情況
• 混合多種模式而沒有明確邊界
• 未經測試就部署

---

摘要

重點：

1. 6 大核心模式涵蓋 90% 以上的工作流程使用案例
2. Webhook 處理是最常見的模式
3. 每個工作流程都使用工作流程建立檢查清單
4. 規劃模式 → 選擇節點 → 建置 → 驗證 → 部署
5. 與其他技能整合以完成工作流程開發

下一步：

1. 識別你的使用案例模式
2. 閱讀詳細的模式檔案
3. 使用 n8n MCP Tools Expert 尋找節點
4. 遵循工作流程建立檢查清單
5. 使用 n8n Validation Expert 進行驗證

相關技能：

• n8n MCP Tools Expert - 尋找和設定節點
• n8n Expression Syntax - 正確編寫運算式
• n8n Validation Expert - 驗證和修正錯誤
• n8n Node Configuration - 設定特定操作