n8n-node-configuration

n8n 节点配置

有关根据操作配置节点及属性依赖关系的专业指导。

---

配置理念

渐进式呈现：从最精简的配置开始，根据需要增加复杂度

配置最佳实践：

• get_node 搭配 detail: "standard" 是最常用的发现模式
• 配置编辑之间平均间隔 56 秒
• 响应只需 1–2K 个 token 即可满足 95% 的使用场景

关键要点：大多数配置只需要标准详情，而非完整架构！

---

核心概念

1. 操作感知型配置

并非所有字段都始终必填——这取决于操作！

示例：Slack 节点

// For operation='post'
{
  "resource": "message",
  "operation": "post",
  "channel": "#general",  // Required for post
  "text": "Hello!"        // Required for post
}

// For operation='update'
{
  "resource": "message",
  "operation": "update",
  "messageId": "123",     // Required for update (different!)
  "text": "Updated!"      // Required for update
  // channel NOT required for update
}

关键：资源和操作决定哪些字段必填！

2. 属性依赖关系

字段会根据其他字段的值显示或隐藏

示例：HTTP Request 节点

// When method='GET'
{
  "method": "GET",
  "url": "https://api.example.com"
  // sendBody not shown (GET doesn't have body)
}

// When method='POST'
{
  "method": "POST",
  "url": "https://api.example.com",
  "sendBody": true,       // Now visible!
  "body": {               // Required when sendBody=true
    "contentType": "json",
    "content": {...}
  }
}

机制：displayOptions 控制字段可见性

3. 渐进式发现

选择合适的详情级别：

1. get_node({detail: "standard"}) - 默认

   • 快速概览（约 1–2K 个 token）
   • 必填字段和常用选项
   • 优先使用——可满足 95% 的需求

2. get_node({mode: "search_properties", propertyQuery: "..."})（用于查找特定字段）

   • 按名称查找属性
   • 查找身份验证、正文、标头等内容时使用

3. get_node({detail: "full"})（完整架构）

   • 所有属性（约 3–8K 个 token）
   • 仅在标准详情不够用时使用

---

配置工作流

标准流程

1. 确定节点类型和操作。
2. 使用 get_node（默认采用标准详情）。
3. 配置必填字段。
4. 验证配置。
5. 如果字段不明确 → get_node({mode: "search_properties"})。
6. 根据需要添加可选字段。
7. 再次验证。
8. 部署。

示例：配置 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" is the default

返回内容（约 1–2K 个 token）：

• 必填字段，根据节点当前的 typeVersion 解析
• 操作列表
• options 集合中的设置（n8n-mcp 2.97.0+）：名称，以及一行说明，其中列出嵌套字段名称、允许的值和各自适用的情况——HTTP Request 分页和批处理、Webhook 原始正文、Merge 合并设置等
• 元数据

用途：满足 95% 的配置需求。考虑是否需要 Code 节点之前，请先查看选项列表。

完整详情（谨慎使用）

✅ 标准详情不足时

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

返回内容（约 3–8K 个 token）：

• 完整架构
• 所有属性
• 所有嵌套选项

警告：响应内容较大，仅在标准详情不足时使用

搜索属性模式

✅ 查找特定字段

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

用途：查找身份验证、标头、正文等字段

决策树

1. 开始配置新节点 → 使用 get_node（标准）。
2. 标准详情中包含所需内容 → 使用这些信息进行配置。否则继续。（在 n8n-mcp 2.97.0+ 中，标准详情还会列出每个 options 集合；如果设置列表被截断在 25 项，会注明这一点。）
3. 查找特定字段 → 使用 search_properties 模式。否则继续。
4. 仍需要更多信息 → 使用 get_node({detail: "full"})。

动态属性：当 standard 详情使用 dynamicOptions: {methodName, methodType, dependsOn} 标记某个属性时，其实际值来自实时的 loadOptions/listSearch 方法，而非随附文档——不要猜测其 ID。使用 n8n_explore_node_resources 获取该值（需要 N8N_MCP_ACCESS_TOKEN，且 n8n 需为 2.34+），并将返回的 value 写入配置；name 仅是显示文本。

以下 6 个参数均为必填项，且彼此之间不会自动推导：

n8n_explore_node_resources({
  nodeType: "n8n-nodes-base.googleSheets",  // LONG form
  version: 4.5,                              // the node typeVersion the method belongs to
  methodName: "getSheets",                   // copied verbatim from dynamicOptions
  methodType: "listSearch",                  // "listSearch" for resource locators, "loadOptions" for plain dropdowns
  credentialType: "googleSheetsOAuth2Api",
  credentialId: "c2",                        // from n8n_manage_credentials({action: "list"})
  currentNodeParameters: {                   // whatever dependsOn names, in its real shape
    documentId: {__rl: true, mode: "id", value: "1AbC…"}
  }
})

dependsOn 列出方法需要预先选定的参数——将它们传入 currentNodeParameters，并保持资源定位器值的 {__rl: true, mode, value} 格式，否则该方法不会返回有用内容。methodName 区分大小写，并且针对特定的 nodeType + version 组合；不匹配时会返回 OFFICIAL_MCP_ERROR，而非空列表。

---

属性依赖详解

字段具有 displayOptions 可见性规则：show/hide 块中的多个条件采用 AND 逻辑，多个值采用 OR 逻辑（例如，sendBody=true 且 method IN (POST, PUT, PATCH) 时显示 body）。常见的 3 种模式是布尔开关（sendBody → body）、操作切换（post 和 update 显示不同字段）以及类型选择（字符串与布尔条件）。若要查找控制某个字段的设置，请使用 get_node({mode: "search_properties", propertyQuery: "..."}) 或 get_node({detail: "full"})——尤其是在验证标记了你看不到的字段时。

机制详情、全部 4 种依赖模式、复杂流程、嵌套依赖和故障排除均见 DEPENDENCIES.md（快速参考摘要见 快速参考：displayOptions 和常见依赖模式）。

---

常见节点模式

模式 1：资源/操作节点

示例：Slack、Google Sheets、Airtable

结构：

{
  "resource": "<entity>",      // What type of thing
  "operation": "<action>",     // What to do with it
  // ... operation-specific fields
}

配置方法：

1. 选择资源
2. 选择操作
3. 使用 get_node 查看特定操作的要求
4. 配置必填字段

模式 2：基于 HTTP 的节点

示例：HTTP Request、Webhook

结构：

{
  "method": "<HTTP_METHOD>",
  "url": "<endpoint>",
  "authentication": "<type>",
  // ... method-specific fields
}

依赖项：

• POST/PUT/PATCH → 可使用 sendBody
• sendBody=true → 必须填写 body
• authentication != "none" → 必须提供凭据

关键事项：credentials 块、节点 ID、typeVersion

• 绝不要设置占位凭据 ID（例如 "id": "REPLACE_ME"）——对于未知 ID，n8n 的 UI 会渲染永久禁用的凭据选择器。若不知道真实 ID，请省略 credentials 块；这样用户就会看到正常可点击的下拉菜单。
• 节点 id 必须是 UUID v4，不能是易读的 slug——前端会将表单和凭据组件绑定到此 ID。
• 不要硬编码旧版 typeVersion 值——使用 get_node 验证当前版本（httpRequest 为 4.4+）。

模式 3：数据库节点

示例：Postgres、MySQL、MongoDB

结构：

{
  "operation": "<query|insert|update|delete>",
  // ... operation-specific fields
}

依赖项：

• 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": "..."  // Only for binary operators
      }
    ]
  }
}

依赖关系：

• 二元运算符（equals、contains 等）→ value1 + value2
• 一元运算符（isEmpty、isNotEmpty）→ 仅 value1 + singleValue: true

---

特定操作的配置

必填字段会随资源和操作而变化：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。

---

处理条件要求

某些字段仅在特定条件下必填：当 sendBody=true 且 method IN (POST, PUT, PATCH, DELETE) 时，HTTP body 必填；当运算符为一元运算符（isEmpty、isNotEmpty、true、false）时，IF singleValue 应为 true——自动清理会为你设置此值。可通过读取验证错误、搜索属性（get_node({mode: "search_properties"})），或从最简配置开始迭代，来发现条件要求。发现过程示例见 DEPENDENCIES.md。

---

特定节点的配置说明

SplitInBatches v3

{
  "batchSize": 100,  // Number of items per batch
  "options": {}
}

输出连线：

• main[0]（完成）→ 连接到下游处理（先添加 Limit 1）
• main[1]（每个批次）→ 连接到循环体，然后连回 SplitInBatches 输入端

详细的循环和嵌套循环模式请参阅 n8n Workflow Patterns 技能。

Google Sheets 节点

逐项执行：每个输入项都会触发单独的 API 调用。如果有 100 个输入项并使用 Google Sheets “Append Row” 节点，就会发出 100 次 API 调用。如需批量写入，请先使用 Aggregate 节点将行收集到一个输入项中，然后通过单个 HTTP Request 调用 Sheets API。

公式列：对于包含公式列的工作表，切勿使用 append——它会覆盖公式。应改用 HTTP Request，通过 Google Sheets API 的 values.update（PUT）方法，并使用 googleApi 凭据。

---

配置反模式

❌ 不要：预先过度配置

错误：

// Adding every possible field
{
  "method": "GET",
  "url": "...",
  "sendQuery": false,
  "sendHeaders": false,
  "sendBody": false,
  "timeout": 10000,
  "ignoreResponseCode": false,
  // ... 20 more optional fields
}

正确：

// Start minimal
{
  "method": "GET",
  "url": "...",
  "authentication": "none"
}
// Add fields only when needed

❌ 不要：跳过验证

错误：

// Configure and deploy without validating
const config = {...};
n8n_update_partial_workflow({...});  // YOLO

正确：

// Validate before deploying
const config = {...};
const result = validate_node({...});
if (result.valid) {
  n8n_update_partial_workflow({...});
}

❌ 不要：忽略操作上下文

错误：

// Same config for all Slack operations
{
  "resource": "message",
  "operation": "post",
  "channel": "#general",
  "text": "..."
}

// Then switching operation without updating config
{
  "resource": "message",
  "operation": "update",  // Changed
  "channel": "#general",  // Wrong field for update!
  "text": "..."
}

正确：

// Check requirements when changing operation
get_node({
  nodeType: "nodes-base.slack"
});
// See what update operation needs (messageId, not channel)

---

使用 patchNodeField 精准编辑字段

如果需要编辑节点字段中的特定字符串，而不是替换整个字段，请在 n8n_update_partial_workflow 中使用 patchNodeField。这对以下情况尤其有用：

• 编辑 Code 节点中的代码，而无需重新传输完整代码块
• 更新大型 HTML 邮件模板中的 URL 或文本
• 修正 JSON 请求体或长文本字段中的拼写错误

// Instead of replacing the entire jsCode field:
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 要求严格——如果找不到查找字符串，或匹配到多个位置（除非设置了 replaceAll: true），就会报错。这可以防止配置更新时意外地静默失败。完整语法和示例请参阅 n8n MCP Tools Expert 技能。

---

最佳实践

应该做

1. 从 get_node（标准详情）开始

   • 响应约 1-2K 个 token
   • 覆盖 95% 的配置需求
   • 默认详情级别

2. 迭代验证

   • 配置 → 验证 → 修复 → 重复
   • 平均迭代 2-3 次很正常
   • 仔细阅读验证错误

3. 遇到困难时使用 search_properties 模式

   • 如果字段似乎缺失，就搜索该字段
   • 了解哪些因素会控制字段的可见性
   • get_node({mode: "search_properties", propertyQuery: "..."})

4. 遵循操作上下文

   • 不同操作有不同要求
   • 更改操作时，务必检查 get_node
   • 不要假设配置可以通用

5. 信任自动清理

   • 自动修正操作符结构
   • 不要手动添加或删除 singleValue
   • 保存时会添加 IF/Switch 元数据

❌ 不要做

1. 不要立刻跳到 detail="full"

   • 先尝试标准详情
   • 仅在需要时提升详情级别
   • 完整架构需要 3-8K 个 token

2. 不要盲目配置

   • 部署前务必验证
   • 了解字段为何必填
   • 对条件字段使用 search_properties

3. 不要复制未理解的配置

   • 不同操作需要不同字段
   • 复制后进行验证
   • 根据新的上下文调整

4. 不要手动修复自动清理问题

   • 让自动清理处理操作符结构
   • 专注于业务逻辑
   • 保存并让系统修正结构

---

数据任务的原生节点

using-n8n-mcp-skills 中的任务到节点对照表可用于选择节点；NATIVE_NODES.md 列出了每个节点的 parameters JSON 和注意事项。最常见的问题：

• Summarize — fieldsToSplitBy 是一个逗号分隔的字符串；输出名称为 sum_amount、count_id 等。
• Split Out — include 默认为 noOtherFields：除非保留父级字段，否则这些字段会被丢弃。
• Merge — combineByFields + joinMode（keepMatches、keepNonMatches、enrichInput1 等）；numberInputs 仅用于追加 / SQL / 位置 / 选择分支模式。
• Compare Datasets — 按固定顺序提供四个输出：仅在 A 中、相同、不同、仅在 B 中。
• Remove Duplicates — removeItemsSeenInPreviousExecutions 会跨运行去重（v2），替代静态数据 Code。
• Date & Time — 设置 options.includeInputFields: true，否则只会保留新的日期字段。
• HTTP Request 分页 — 始终设置 limitPagesFetched: true + maxRequests；对象正文会作为每页一个项目传入。
• Crypto — 使用 typeVersion 2：HMAC 和签名密钥来自 crypto 凭据（v1 将它们保存在 JSON 中）。
• 节点设置 — executeOnce、alwaysOutputData、notes / notesInFlow 与 parameters 并列，而非包含在其中。

---

按节点系列分类的静默失败注意事项

某些配置错误可以通过 validate_node 和 validate_workflow 验证，运行时也不会报错，却会悄悄执行错误操作——get_node 会显示字段存在，但不会说明省略这些字段时会发生什么。高频问题如下：

• Switch — 未设置 options.fallbackOutput ⇒ 不匹配的项目会被静默丢弃。
• Merge — numberInputs 默认为 2（额外来源会被丢弃；numberOfInputs 不是字段，会被忽略）；useDataOfInput 从 1 开始计数，而 connections.<src>.main[idx] 中的 idx 从 0 开始（useDataOfInput: "N" → main[N-1]）。
• Database — 将 {{ }} 插值到 parameters.query 会造成 SQL 注入；请使用 $1/$2 占位符 + options.queryReplacement。
• Slack — Block Kit 必须用 ={{ { "blocks": ... } }} 包装，否则会作为纯文本发布。
• Webhook / Respond — 即使在错误分支中，options.responseCode 也默认为 200；顶层的 responseCode 会被忽略。
• Schedule Trigger — 时区是工作流级设置（Workflow Settings），不是每条规则的设置。

完整的症状 / 原因 / 修复详情（以 JSON 和 n8n_update_partial_workflow 的术语说明）见 NODE_FAMILY_GOTCHAS.md。

---

详细参考资料

有关特定主题的完整指南：

• DEPENDENCIES.md - 深入了解属性依赖项和 displayOptions
• OPERATION_PATTERNS.md - 按节点类型划分的常见配置模式
• NATIVE_NODES.md - 用于替代 Code 的原生节点（转换、去重、差异比较、日期、分页、HMAC、文件）的配置及节点设置
• NODE_FAMILY_GOTCHAS.md - 各节点系列中不易察觉的运行时陷阱（Switch、Merge、Database、Slack、Webhook、Schedule）

---

总结

配置策略：

1. 从 get_node 开始（默认采用标准详细程度）
2. 配置操作所需的字段
3. 验证配置
4. 遇到问题时搜索属性
5. 反复调整，直到验证通过（平均 2–3 轮）
6. 放心部署

核心原则：

• 操作感知：不同操作 = 不同要求
• 渐进式披露：从最精简配置开始，按需添加
• 依赖感知：了解字段可见性规则
• 以验证为导向：让验证过程指导配置

相关技能：

• n8n MCP 工具专家 - 如何正确使用发现工具
• n8n 验证专家 - 解读验证错误
• n8n 表达式语法 - 配置表达式字段
• n8n 工作流模式 - 使用正确的配置应用模式