n8n-validation-expert

n8n 驗證專家

解讀與修正 n8n 驗證錯誤的專家指南。

驗證理念

及早驗證，頻繁驗證

驗證通常是迭代的：

預期會有驗證回饋循環
通常需要 2-3 次驗證→修正循環
平均：23 秒思考錯誤，58 秒修正

關鍵洞察：驗證是迭代過程，不是一次到位！

錯誤嚴重程度分級

1. 錯誤（必須修正）

阻擋工作流程執行——必須在啟用前解決

類型：

missing_required - 未提供必填欄位
invalid_value - 值不符合允許的選項
type_mismatch - 資料型別錯誤（字串而非數字）
invalid_reference - 參照的節點不存在
invalid_expression - 表達式語法錯誤

範例：

{
  "type": "missing_required",
  "property": "channel",
  "message": "頻道名稱為必填",
  "fix": "提供頻道名稱（小寫、無空格、1-80 個字元）"
}

2. 警告（建議修正）

不阻擋執行——工作流程可啟用，但可能有問題

類型：

best_practice - 建議但不強制——僅在 ai-friendly / strict 設定檔下出現
deprecated - 使用舊版 API/功能——所有設定檔下都會出現
security - 寫死的密碼、未驗證的 Webhook——所有設定檔下都會出現
performance - 潛在效能問題——建議性質，ai-friendly / strict 設定檔

範例（最佳實務——在 ai-friendly / strict 下出現）：

{
  "type": "warning",
  "nodeName": "Slack",
  "message": "Slack API 可能有速率限制與暫時性失敗"
}

3. 建議（可選）

有則更好——可改善工作流程的改進

類型：

optimization - 可以更有效率
alternative - 達成相同結果的更好方式

驗證循環

來自遙測資料的模式

7,841 次出現此模式：

1. 設定節點
   ↓
2. validate_node（23 秒思考錯誤）
   ↓
3. 仔細閱讀錯誤訊息
   ↓
4. 修正錯誤
   ↓
5. 再次 validate_node（58 秒修正）
   ↓
6. 重複直到有效（通常 2-3 次迭代）

範例

// 迭代 1
let config = {
  resource: "channel",
  operation: "create"
};

const result1 = validate_node({
  nodeType: "nodes-base.slack",
  config,
  profile: "runtime"
});
// → 錯誤：缺少 "name"

// ⏱️  23 秒思考...

// 迭代 2
config.name = "general";

const result2 = validate_node({
  nodeType: "nodes-base.slack",
  config,
  profile: "runtime"
});
// → 錯誤：缺少 "text"

// ⏱️  58 秒修正...

// 迭代 3
config.text = "Hello!";

const result3 = validate_node({
  nodeType: "nodes-base.slack",
  config,
  profile: "runtime"
});
// → 有效！ ✅

這是正常的！ 不要因為多次迭代而氣餒。

驗證設定檔

四個設定檔是累加的（n8n-mcp ≥ 2.63.0）：每個設定檔都會顯示較低設定檔的所有內容，再加上更多。分界線在於最佳實務建議——minimal 和 runtime 不顯示它們；ai-friendly 和 strict 則會加入。錯誤在所有設定檔中相同，但 minimal 會跳過一些設定層級的檢查（例如對明確 operation 的列舉驗證）。安全性和棄用警告在所有設定檔下都會出現。

minimal

使用時機：在組合工作流程時進行快速結構檢查。

顯示內容：會停止執行的嚴重錯誤（缺少必填欄位、空程式碼、中斷的連線）。跳過列舉檢查和所有建議。

最快且最寬容。

runtime（建議預設）

使用時機：建置過程中的持續驗證；日常使用的設定檔。

顯示內容：錯誤（必填欄位、值型別、允許值、相依性、中斷的參照）加上安全性和棄用警告。不包含最佳實務建議。

平衡——捕捉所有會中斷的問題，對風格保持沉默。

ai-friendly

使用時機：在部署前想要獲得最佳實務建議。

顯示內容：runtime 的所有內容，加上最佳實務建議——每個節點的「缺少錯誤處理」建議、「Webhook 應始終發送回應」、速率限制備註、過時 typeVersion 建議、cachedResultName 和長鏈提示。

注意：ai-friendly 比 runtime 更嚴格，而不是更寬鬆。（舊文件描述它減少誤判——那僅在設定檔門控有問題時才成立；現在已修正。）

strict

使用時機：強化生產環境關鍵工作流程。

顯示內容：ai-friendly 的所有內容，加上殘留屬性檢查（「屬性 'X' 不會被使用——在目前設定下不可見」）。

最大程度的 lint。 隨著誤判在源頭被修正，其警告是值得權衡的建議，而不是需要對抗的雜訊。

常見錯誤類型

五種核心錯誤類型，大致按頻率排序：

missing_required — 未提供必填欄位。使用 get_node 查看必填欄位，然後加入。
invalid_value — 值不符合允許的選項（列舉區分大小寫）。檢查錯誤的允許清單或使用 get_node。
type_mismatch — 資料型別錯誤（字串 "100" 與數字 100）。轉換為預期型別。
invalid_expression — 表達式語法錯誤（缺少 {{}}、拼寫錯誤）。請參閱 n8n 表達式語法技能。
invalid_reference — 參照的節點不存在（已重新命名、刪除或拼錯）。修正名稱或使用 cleanStaleConnections。

第六類，patchNodeField 錯誤（找不到、模糊匹配、無效/不安全的正規表達式），在 n8n_update_partial_workflow 期間 patchNodeField 操作失敗時出現——它設計上很嚴格，會回傳錯誤而不是默默繼續。

上述每種類型都有實際範例（錯誤設定 → 修正），加上 patchNodeField 錯誤案例及其修正，請參閱 ERROR_CATALOG.md。

自動清理系統

在任何工作流程更新時自動正規化常見的運算子結構——n8n_create_workflow、n8n_update_partial_workflow 或任何儲存操作。請信任它；不要手動修正這些。

儲存時正規化的內容：

二元運算子（equals、notEquals、contains、notContains、greaterThan、lessThan、startsWith、endsWith）——移除多餘的 singleValue 屬性。
一元運算子（isEmpty、isNotEmpty、true、false）——加入 singleValue: true。
IF/Switch 中繼資料——為 IF v2.2+ 和 Switch v3.2+ 填入 conditions.options。

驗證不再對這些形狀回傳錯誤（n8n-mcp ≥ 2.63.0）。n8n 從運算子名稱推斷一元性質，並預設 conditions.options 子欄位，因此 validate_node / validate_workflow 接受條件，無論 singleValue 和選項中繼資料是否存在——清理器只是在儲存時整理規範形式。（舊版伺服器錯誤地對未正規化的形狀回傳錯誤；如果您看到這種情況，請升級。）仍然是真正錯誤的情況：v2 節點上的 v1 形狀 conditions 物件、沒有條件的空 filter，以及 v2 結構內的舊版 v1 運算子名稱（例如 smaller）。

清理器無法修正的內容（需手動處理）：連接到不存在節點的中斷連線（使用 cleanStaleConnections）、分支數量不匹配（新增/移除連線或規則），以及矛盾的損毀狀態（可能需要手動資料庫介入）。

前後範例和完整的無法修正細節請參閱 ERROR_CATALOG.md（自動清理章節）。

誤判

驗證器改版（n8n-mcp ≥ 2.63.0）移除了經典的誤判——表達式內的模板字串、可選鏈、省略操作的預設值、Webhook → Respond-to-Webhook 模式、IF/Filter 舊版形狀等不再觸發。沒有「已知需忽略的誤判」清單。

剩下的是最佳實務建議（僅在 ai-friendly / strict 下顯示），它們標記了真正的取捨，但在您的情況下可能是可接受的。並非每個建議都需要修正——許多取決於情境。常見的建議以及何時可接受 vs. 值得修正：

「...缺少錯誤處理」——開發/測試和非關鍵通知可接受；處理重要資料的生產環境應修正。（永遠不是嚴重錯誤——風格不阻擋執行。）
「無重試邏輯」——冪等操作、自帶重試的 API、手動觸發可接受；不穩定的外部服務和生產自動化應修正。
「...速率限制和暫時性失敗」——內部/低流量/伺服器端限制的 API 可接受；公開、高流量的 API 應修正。
「無限制查詢」——小型已知資料集、彙總、開發/測試可接受；大型資料表的生產查詢應修正。

相比之下，安全性和棄用警告在每個設定檔下都會出現，應視為真正的問題。

完整的逐案例指引、驗證器不再標記的項目清單、設定檔策略、「我該修正這個嗎？」決策框架，以及如何記錄已接受的建議，請參閱 FALSE_POSITIVES.md。

驗證結果結構

完整回應

{
  "valid": false,
  "errors": [
    {
      "type": "missing_required",
      "property": "channel",
      "message": "頻道名稱為必填",
      "fix": "提供頻道名稱（小寫、無空格）"
    }
  ],
  "warnings": [
    {
      "type": "best_practice",
      "property": "errorHandling",
      "message": "Slack API 可能有速率限制",
      "suggestion": "加入 onError: 'continueRegularOutput'"
    }
  ],
  "suggestions": [
    {
      "type": "optimization",
      "message": "考慮對多個訊息使用批次操作"
    }
  ],
  "summary": {
    "hasErrors": true,
    "errorCount": 1,
    "warningCount": 1,
    "suggestionCount": 1
  }
}

如何解讀

先檢查 valid——true 表示設定有效；false 表示在部署前有錯誤需要修正。
先修正 errors——每個錯誤都帶有 property、message 和 fix。這些必須解決。
檢視 warnings——每個警告都有 message 和 suggestion；逐案例決定是否處理（請參閱上面的誤判）。
考慮 suggestions——可選的改進，非必要。

工作流程驗證

validate_workflow（結構）

驗證整個工作流程，而不只是個別節點

檢查項目：

節點設定 - 每個節點有效
連線 - 無中斷的參照
表達式 - 語法和參照有效
流程 - 邏輯工作流程結構

範例：

validate_workflow({
  workflow: {
    nodes: [...],
    connections: {...}
  },
  options: {
    validateNodes: true,
    validateConnections: true,
    validateExpressions: true,
    profile: "runtime"
  }
})

常見工作流程錯誤

1. 中斷的連線

{
  "error": "從 'Transform' 到 'NonExistent' 的連線 - 找不到目標節點"
}

修正：移除過時的連線或建立遺失的節點

2. 循環（警告，非錯誤）

{
  "warning": "工作流程包含循環：節點 A → 節點 B → 節點 A"
}

循環是警告，不是嚴重錯誤（n8n-mcp ≥ 2.63.0）——執行階段控制的循環（錯誤重試、資料驅動的分頁、回饋的路由器）會執行到完成，是合法的。僅在循環非故意時修正：確保循環有真正的出口（條件節點、錯誤輸出或有界計數器），以免無限循環。

3. 多個起始節點

{
  "warning": "找到多個觸發節點 - 只有一個會執行"
}

修正：移除多餘的觸發器或拆分為單獨的工作流程

4. 未連線的節點

{
  "warning": "節點 'Transform' 未連線到工作流程流程"
}

修正：連線節點，或如果未使用則移除

復原策略

策略 1：重新開始

時機：設定嚴重損毀

步驟：

從 get_node 記下必填欄位
建立最小的有效設定
逐步加入功能
每次加入後驗證

策略 2：二元搜尋

時機：工作流程驗證通過但執行不正確

步驟：

移除一半的節點
驗證並測試
如果正常：問題在移除的節點中
如果失敗：問題在剩餘的節點中
重複直到問題被隔離

策略 3：清理過時連線

時機：出現「找不到節點」錯誤

步驟：

n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [{
    type: "cleanStaleConnections"
  }]
})

策略 4：使用自動修正

時機：驗證錯誤可自動解決

步驟：

// 預覽修正（預設 - 不套用）
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: false,
  confidenceThreshold: "medium"  // high, medium, low
})

// 檢視修正，然後套用
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: true
})

自動修正功能

n8n_autofix_workflow 工具可修正這些問題類型：

expression-format - 表達式中缺少 = 前綴（例如 {{ $json.field }} → ={{ $json.field }}）
typeversion-correction - 降級具有不支援 typeVersion 的節點
error-output-config - 移除衝突的 onError 設定
node-type-correction - 使用相似度比對修正未知節點類型（90% 以上信心度）
webhook-missing-path - 為缺少路徑設定的 Webhook 節點產生 UUID
typeversion-upgrade - 智慧升級到最新節點版本並自動遷移
version-migration - 針對需要手動步驟的複雜重大變更提供指引

信心度等級：high（90% 以上，可安全自動套用）、medium（70-89%，建議檢視）、low（低於 70%，需要手動檢視）

// 預覽所有修正
n8n_autofix_workflow({id: "workflow-id"})

// 僅套用高信心度修正
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: true,
  confidenceThreshold: "high"
})

// 針對特定修正類型
n8n_autofix_workflow({
  id: "workflow-id",
  fixTypes: ["expression-format", "typeversion-upgrade"],
  applyFixes: true
})

更新後指引：對於版本升級，請檢查回應中的 postUpdateGuidance 欄位以取得逐步遷移說明。

最佳實務

✅ 應該做

每次重大變更後進行驗證
完整閱讀錯誤訊息
迭代修正錯誤（一次一個）
部署前使用 runtime 設定檔
在假設成功前檢查 valid 欄位
信任運算子問題的自動清理
對需求不清楚時使用 get_node
記錄您接受的誤判

❌ 不應該做

在啟用前跳過驗證
嘗試一次修正所有錯誤
忽略錯誤訊息
開發期間使用 strict 設定檔（太吵雜）
假設驗證已通過（始終檢查結果）
手動修正自動清理的問題
部署帶有未解決錯誤的工作流程
忽略所有警告（有些很重要！）

檢閱現有工作流程

在建置過程中驗證（上述循環）是為了捕捉您自己進行中的工作中的結構錯誤。檢閱現有工作流程——您自己的或別人交給您的——是另一項工作：工作流程已經通過 validate_workflow 檢查，而您正在尋找驗證看不到的問題（無聲的連線錯誤、易受注入攻擊的查詢、丟棄項目的 Switch、Set/Code 反模式、缺少的錯誤路徑）。為此，請使用 n8n_get_workflow 拉取工作流程，並逐步檢視 REVIEW_CHECKLIST.md——這是一個按嚴重程度分層的稽核清單（必須修正 / 建議修正 / 有則更好），其中每個項目都指向對應的修正技能。同時執行 n8n_audit_instance 以找出整個實例中的寫死密碼和未驗證的 Webhook。

詳細指南

如需完整的錯誤目錄、誤判和工作流程檢閱：

ERROR_CATALOG.md - 完整的錯誤類型清單與範例
FALSE_POSITIVES.md - 何時警告是可接受的
REVIEW_CHECKLIST.md - 檢閱現有工作流程的嚴重程度分層稽核

總結

重點：

驗證是迭代的（平均 2-3 次循環，23 秒 + 58 秒）
錯誤必須修正，警告可選
自動清理在儲存時正規化運算子結構；驗證不再對原始形狀回傳錯誤
預設使用 runtime 設定檔；需要最佳實務建議時升級到 ai-friendly/strict
經典誤判已修正（≥ 2.63.0）——剩餘的警告是建議或安全性/棄用通知，不是驗證器的錯誤
閱讀錯誤訊息——它們包含修正指引

驗證流程：

驗證 → 閱讀錯誤 → 修正 → 再次驗證
重複直到有效（通常 2-3 次迭代）
檢視警告並決定是否可接受
有信心地部署

相關技能與工具：

n8n MCP Tools Expert - 正確使用驗證工具
n8n Expression Syntax - 修正表達式錯誤
n8n Node Configuration - 了解必填欄位
n8n_audit_instance - 主動安全性驗證（寫死密碼、未驗證的 Webhook、缺少錯誤處理、資料保留）

您可能也喜歡

mcp-builder

69Kresearch-knowledge

建立高品質 MCP（Model Context Protocol）伺服器的指南，讓 LLM 能透過設計良好的工具與外部服務互動。在建置 MCP 伺服器以整合外部 API 或服務時使用，無論是 Python（FastMCP）或 Node/TypeScript（MCP SDK）皆適用。

composiohq

獲取

orch-pipeline

240Kresearch-knowledge

Shared orchestration engine for the orch-* skill family. Defines the gated Research-Plan-TDD-Review-Commit pipeline, the size classifier, the agent map, and the two human gates that the orch-* operation skills delegate to. Not usually invoked directly. Not usually invoked directly; it applies when an orch-* skill delegates its gated Research-Plan-TDD-Review-Commit pipeline.

affaan-m

獲取

recsys-pipeline-architect

239Kresearch-knowledge

Design composable recommendation, ranking, and feed pipelines using the six-stage Source→Hydrator→Filter→Scorer→Selector→SideEffect framework popularized by xAI's open-sourced For You algorithm. Use this skill whenever the user is building any system that picks "the top K items for a (user, context)" — social feeds, content CMSs, RAG rerankers, task prioritizers, notification triage, search reranking, ad ranking.

affaan-m

獲取

繼續探索

瀏覽 research-knowledge 熱門 Skills 最近更新