n8n-node-configuration

n8n 節點設定

關於操作感知的節點設定與屬性相依性的專家指引。

設定哲學

漸進式揭露：從最小開始，依需求增加複雜度

設定最佳實務：

get_node 搭配 detail: "standard" 是最常用的探索模式
平均每次設定編輯間隔 56 秒
1-2K token 回應即可涵蓋 95% 的使用案例

關鍵洞察：大多數設定只需要標準詳細程度，不需要完整結構！

核心概念

1. 操作感知設定

並非所有欄位永遠都是必填——取決於操作！

範例：Slack 節點

// 對於 operation='post'
{
  "resource": "message",
  "operation": "post",
  "channel": "#general",  // post 必填
  "text": "Hello!"        // post 必填
}

// 對於 operation='update'
{
  "resource": "message",
  "operation": "update",
  "messageId": "123",     // update 必填（不同！）
  "text": "Updated!"      // update 必填
  // channel 在 update 中非必填
}

重點：Resource + operation 決定哪些欄位是必填的！

2. 屬性相依性

欄位會根據其他欄位的值顯示或隱藏

範例：HTTP Request 節點

// 當 method='GET'
{
  "method": "GET",
  "url": "https://api.example.com"
  // sendBody 不顯示（GET 沒有 body）
}

// 當 method='POST'
{
  "method": "POST",
  "url": "https://api.example.com",
  "sendBody": true,       // 現在顯示了！
  "body": {               // 當 sendBody=true 時必填
    "contentType": "json",
    "content": {...}
  }
}

機制：displayOptions 控制欄位顯示

3. 漸進式探索

使用正確的詳細程度：

get_node({detail: "standard"}) - 預設
- 快速概覽（約 1-2K token）
- 必填欄位 + 常用選項
- 優先使用 - 涵蓋 95% 的需求
get_node({mode: "search_properties", propertyQuery: "..."})（用於尋找特定欄位）
- 依名稱搜尋屬性
- 用於尋找驗證、body、headers 等
get_node({detail: "full"})（完整結構）
- 所有屬性（約 3-8K token）
- 僅在標準詳細程度不足時使用

設定工作流程

標準流程

識別節點類型和操作。
使用 get_node（預設為標準詳細程度）。
設定必填欄位。
驗證設定。
如果欄位不明確 → get_node({mode: "search_properties"})。
依需求加入選填欄位。
再次驗證。
部署。

範例：設定 HTTP Request

實際的驗證驅動迴圈：從最小開始（method、url、authentication），然後讓每次 validate_node 錯誤提示下一個必填欄位（POST 的 sendBody → 當 sendBody=true 時的 body），直到驗證通過。完整逐步說明請見 OPERATION_PATTERNS.md。

get_node 詳細程度

標準詳細程度（預設 - 請使用這個！）

✅ 起始設定

get_node({
  nodeType: "nodes-base.slack"
});
// detail="standard" 是預設值

回傳（約 1-2K token）：

必填欄位
常用選項
操作列表
中繼資料

用途：95% 的設定需求

完整詳細程度（謹慎使用）

✅ 當標準不足時

get_node({
  nodeType: "nodes-base.slack",
  detail: "full"
});

回傳（約 3-8K token）：

完整結構
所有屬性
所有巢狀選項

警告：回應較大，僅在標準不足時使用

搜尋屬性模式

✅ 尋找特定欄位

get_node({
  nodeType: "nodes-base.httpRequest",
  mode: "search_properties",
  propertyQuery: "auth"
});

用途：尋找驗證、headers、body 欄位等

決策樹

開始新的節點設定 → get_node（標準）。
標準有你要的內容 → 用它來設定。否則繼續。
尋找特定欄位 → search_properties 模式。否則繼續。
仍需要更多 → get_node({detail: "full"})。

屬性相依性深入探討

欄位具有 displayOptions 可見性規則：show/hide 區塊中，多個條件為 AND 關係，多個值為 OR 關係（例如 body 在 sendBody=true 且 method IN (POST, PUT, PATCH) 時顯示）。三種常見模式為布林切換（sendBody → body）、操作切換（post 與 update 顯示不同欄位）、以及類型選擇（字串與布林條件）。若要找出控制某個欄位的條件，請使用 get_node({mode: "search_properties", propertyQuery: "..."}) 或 get_node({detail: "full"})——特別是在驗證標記了你未見的欄位時。

機制細節、所有四種相依模式、複雜流程、巢狀相依性及疑難排解，請見 DEPENDENCIES.md（快速參考摘要位於 Quick Reference: displayOptions and Common Dependency Patterns）。

常見節點模式

模式 1：資源/操作節點

範例：Slack、Google Sheets、Airtable

結構：

{
  "resource": "<entity>",      // 事物的類型
  "operation": "<action>",     // 對它做什麼
  // ... 操作特定欄位
}

如何設定：

選擇 resource
選擇 operation
使用 get_node 查看操作特定需求
設定必填欄位

模式 2：HTTP 基礎節點

範例：HTTP Request、Webhook

結構：

{
  "method": "<HTTP_METHOD>",
  "url": "<endpoint>",
  "authentication": "<type>",
  // ... 方法特定欄位
}

相依性：

POST/PUT/PATCH → sendBody 可用
sendBody=true → body 必填
authentication != "none" → credentials 必填

關鍵：credentials 區塊、節點 id、typeVersion

絕對不要設定佔位憑證 ID（例如 "id": "REPLACE_ME"）——n8n 的 UI 會為未知 ID 顯示一個永久停用的憑證選擇器。當真實 ID 未知時，請省略 credentials 區塊；使用者會看到一個正常的可點擊下拉選單。
節點 id 必須是 UUID v4，而不是可讀的 slug——前端會將表單和憑證元件綁定到它。
不要硬編碼舊的 typeVersion 值——請使用 get_node 確認目前版本（httpRequest 為 4.4+）。

模式 3：資料庫節點

範例：Postgres、MySQL、MongoDB

結構：

{
  "operation": "<query|insert|update|delete>",
  // ... 操作特定欄位
}

相依性：

operation="executeQuery" → query 必填
operation="insert" → table + values 必填
operation="update" → table + values + where 必填

關鍵：寫入操作可能回傳 0 個項目

INSERT、UPDATE、DELETE 可能產生 0 個 n8n 輸出項目，取決於節點和操作（原始查詢執行可靠地回傳 0 個結果行；某些資料庫節點會回傳受影響的行）
在寫入操作節點上設定 alwaysOutputData: true 以保持下游鏈存活
下游節點如果需要資料，應使用 $('UpstreamNode').all() 而非 $input

模式 4：條件邏輯節點

範例：IF、Switch、Merge

結構：

{
  "conditions": {
    "<type>": [
      {
        "operation": "<operator>",
        "value1": "...",
        "value2": "..."  // 僅用於二元運算子
      }
    ]
  }
}

相依性：

二元運算子（equals、contains 等）→ value1 + value2
一元運算子（isEmpty、isNotEmpty）→ 僅 value1 + singleValue: true

操作特定設定

必填欄位隨 resource + operation 而變：Slack post 需要 channel+text，但 update 需要 messageId+text（channel 選填），而 channel/create 需要 name。HTTP GET 使用 sendQuery+queryParameters；POST 需要 sendBody+body。IF 二元運算子（equals）需要 value1+value2；一元運算子（isEmpty）僅需要 value1 加上自動加入的 singleValue: true。每個操作的具體最小設定請見 OPERATION_PATTERNS.md。

處理條件式需求

某些欄位僅在特定條件下為必填：HTTP body 在 sendBody=true 且 method IN (POST, PUT, PATCH, DELETE) 時必填；IF 的 singleValue 在運算子為一元（isEmpty、isNotEmpty、true、false）時應為 true——自動清理會為你設定。透過閱讀驗證錯誤、搜尋屬性（get_node({mode: "search_properties"})）或從最小設定迭代來發現條件式需求。實際的發現範例請見 DEPENDENCIES.md。

節點特定設定說明

SplitInBatches v3

{
  "batchSize": 100,  // 每批項目數
  "options": {}
}

輸出接線：

main[0]（完成）→ 連接到下游處理（先加入 Limit 1）
main[1]（每批）→ 連接到迴圈主體，然後迴圈回到 SplitInBatches 輸入

詳細的迴圈與巢狀迴圈模式請參閱 n8n Workflow Patterns 技能。

Google Sheets 節點

逐項執行：每個輸入項目觸發一個獨立的 API 呼叫。如果你有 100 個項目並使用 Google Sheets「Append Row」節點，它會進行 100 次 API 呼叫。若要批次寫入，請先在 Code 節點中彙整項目，然後使用單一 HTTP Request 搭配 Sheets API。

公式欄位：絕對不要在包含公式欄位的工作表上使用 append——它會覆寫公式。請改用 HTTP Request 搭配 Google Sheets API 的 values.update（PUT）方法以及 googleApi 憑證。

設定反模式

❌ 不要：一開始就過度設定

不好：

// 加入所有可能的欄位
{
  "method": "GET",
  "url": "...",
  "sendQuery": false,
  "sendHeaders": false,
  "sendBody": false,
  "timeout": 10000,
  "ignoreResponseCode": false,
  // ... 20 個以上的選填欄位
}

好：

// 從最小開始
{
  "method": "GET",
  "url": "...",
  "authentication": "none"
}
// 只在需要時加入欄位

❌ 不要：跳過驗證

不好：

// 不驗證就直接設定並部署
const config = {...};
n8n_update_partial_workflow({...});  // 冒險

好：

// 部署前先驗證
const config = {...};
const result = validate_node({...});
if (result.valid) {
  n8n_update_partial_workflow({...});
}

❌ 不要：忽略操作上下文

不好：

// 所有 Slack 操作使用相同設定
{
  "resource": "message",
  "operation": "post",
  "channel": "#general",
  "text": "..."
}

// 然後切換操作卻不更新設定
{
  "resource": "message",
  "operation": "update",  // 已變更
  "channel": "#general",  // update 的錯誤欄位！
  "text": "..."
}

好：

// 變更操作時檢查需求
get_node({
  nodeType: "nodes-base.slack"
});
// 查看 update 操作需要什麼（messageId，不是 channel）

使用 patchNodeField 進行精確欄位編輯

當你需要編輯節點欄位中的特定字串——而不是取代整個欄位時——請在 n8n_update_partial_workflow 中使用 patchNodeField。這在以下情況特別有用：

編輯 Code 節點中的程式碼，而不重新傳輸整個程式碼區塊
更新大型 HTML 郵件範本中的 URL 或文字
修正 JSON body 或長文字欄位中的錯字

// 與其取代整個 jsCode 欄位：
n8n_update_partial_workflow({
  id: "wf-123",
  operations: [{
    type: "patchNodeField",
    nodeName: "Code",
    fieldPath: "parameters.jsCode",
    patches: [{find: "const limit = 10;", replace: "const limit = 50;"}]
  }]
})

patchNodeField 很嚴格——如果找不到 find 字串或找到多次（除非 replaceAll: true），它會報錯。這可以防止在設定更新期間意外地靜默失敗。完整語法與範例請參閱 n8n MCP Tools Expert 技能。

最佳實務

應該做的事

從 get_node（標準詳細程度）開始
- 約 1-2K token 回應
- 涵蓋 95% 的設定需求
- 預設詳細程度
迭代驗證
- 設定 → 驗證 → 修正 → 重複
- 平均 2-3 次迭代是正常的
- 仔細閱讀驗證錯誤
卡住時使用 search_properties 模式
- 如果欄位似乎遺失，搜尋它
- 了解什麼控制欄位可見性
- get_node({mode: "search_properties", propertyQuery: "..."})
尊重操作上下文
- 不同操作 = 不同需求
- 變更操作時務必檢查 get_node
- 不要假設設定可以轉移
信任自動清理
- 運算子結構會自動修正
- 不要手動加入/移除 singleValue
- IF/Switch 中繼資料會在儲存時加入

❌ 不該做的事

立即跳到 detail="full"
- 先嘗試標準詳細程度
- 只在必要時升級
- 完整結構為 3-8K token
盲目設定
- 部署前務必驗證
- 了解為什麼欄位是必填的
- 對條件式欄位使用 search_properties
不經理解就複製設定
- 不同操作需要不同欄位
- 複製後驗證
- 根據新上下文調整
手動修正自動清理問題
- 讓自動清理處理運算子結構
- 專注於業務邏輯
- 儲存並讓系統修正結構

各節點家族的靜默失敗陷阱

某些錯誤設定會通過 validate_node 和 validate_workflow 的檢查，執行時不會報錯，但悄悄地做了錯誤的事——get_node 顯示欄位存在，但不會說明省略它們會發生什麼。高頻陷阱包括：

Switch — 沒有 options.fallbackOutput ⇒ 未匹配的項目被靜默丟棄。
Merge — numberOfInputs 預設為 2（額外來源被丟棄）；useDataOfInput 是 1-indexed，而 connections.<src>.main[idx] 是 0-indexed（useDataOfInput: "N" → main[N-1]）。
Database — 在 parameters.query 中使用 {{ }} 插值會導致 SQL 注入；請使用 $1/$2 佔位符 + options.queryReplacement。
Slack — Block Kit 必須包裝為 ={{ { "blocks": ... } }}，否則會以純文字發布。
Webhook / Respond — responseCode 即使在錯誤分支也預設為 200。
Schedule Trigger — 時區是工作流程層級（Workflow Settings），而非每個規則。

完整的症狀/原因/修正細節（以 JSON + n8n_update_partial_workflow 用語）請見 NODE_FAMILY_GOTCHAS.md。

詳細參考資料

關於特定主題的完整指南：

DEPENDENCIES.md - 屬性相依性與 displayOptions 深入探討
OPERATION_PATTERNS.md - 各節點類型的常見設定模式
NODE_FAMILY_GOTCHAS.md - 各家族的靜默執行時陷阱（Switch、Merge、Database、Slack、Webhook、Schedule）

總結

設定策略：

從 get_node 開始（預設為標準詳細程度）
設定操作的必填欄位
驗證設定
卡住時搜尋屬性
迭代直到驗證通過（平均 2-3 次循環）
有信心地部署

關鍵原則：

操作感知：不同操作 = 不同需求
漸進式揭露：從最小開始，依需求加入
相依性感知：了解欄位可見性規則
驗證驅動：讓驗證引導設定

相關技能：

n8n MCP Tools Expert - 如何正確使用探索工具
n8n Validation Expert - 解讀驗證錯誤
n8n Expression Syntax - 設定表達式欄位
n8n Workflow Patterns - 以正確設定應用模式

您可能也喜歡

uncloud

240Kdatabase

Use when managing an Uncloud cluster — deploying services, configuring Caddy ingress, adding static proxy routes for non-cluster devices, publishing ports, scaling, inspecting logs, or managing machines and volumes with the `uc` CLI.

affaan-m

獲取

prisma-patterns

238Kdatabase

適用於 TypeScript 後端的 Prisma ORM 設計模式 — 涵蓋 Schema 設計、查詢最佳化、事務處理（Transaction）、分頁機制，以及關鍵陷阱解析（如 updateMany 僅返回計數而非記錄筆數、$transaction 超時、migrate dev 重置資料庫、批次寫入時跳過 @updatedAt，以及 Serverless 環境下的連線耗盡問題）。

affaan-m

獲取

database-design

45Kdatabase

Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases.

sickn33

獲取

繼續探索

瀏覽 database 熱門 Skills 最近更新