n8n-node-configuration

n8n 节点配置

针对具有属性依赖关系的操作感知型节点配置提供专家指导。

---

配置理念

渐进式呈现：从最简配置开始，按需增加复杂度

配置最佳实践：

• get_node 使用 detail: "standard" 是最常用的发现模式
• 配置编辑之间平均间隔 56 秒
• 通过 1-2K 个令牌的响应覆盖 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 个令牌）
   • 必填字段 + 常用选项
   • 优先使用——可满足 95% 的需求

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

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

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

   • 所有属性（约 3-8K 个令牌）
   • 仅在标准详情不足时使用

---

配置工作流

标准流程

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 个令牌）：

• 必填字段
• 常用选项
• 操作列表
• 元数据

用途：满足 95% 的配置需求

完整详情（谨慎使用）

✅ 标准详情不足时

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

返回内容（约 3-8K 个令牌）：

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

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

搜索属性模式

✅ 查找特定字段

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

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

决策树

1. 开始配置新节点 → get_node（标准）。
2. 标准详情包含所需内容 → 使用它进行配置。否则继续。
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 仅为显示文本。

以下六个参数都必填，且不会相互推断：

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 关系（例如，body 在 sendBody=true 且 method IN (POST, PUT, PATCH) 时显示）。常见模式有三种：布尔开关（sendBody → body）、操作切换（post 和 update 显示不同字段）以及类型选择（string 和 boolean 条件）。要查找控制某个字段的属性，请使用 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>",      // 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，不能使用易读的标识符——前端会将表单和凭据组件绑定到该 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），则 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 调用。要批量写入，请先在 Code 节点中汇总输入项，然后使用单个 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. 手动修复自动清理问题

   • 让自动清理处理运算符结构
   • 专注于业务逻辑
   • 保存并让系统修复结构

---

各节点系列中的静默失败陷阱

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

• Switch — 未设置 options.fallbackOutput ⇒ 未匹配的项目会被静默丢弃。
• Merge — numberOfInputs 默认为 2（额外的数据源会被丢弃）；useDataOfInput 从 1 开始计数，而 connections.<src>.main[idx] 中的槽位索引从 0 开始（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）

---

总结

配置策略：

1. 从 get_node 开始（默认使用标准详情）
2. 配置操作所需的字段
3. 验证配置
4. 遇到问题时搜索属性
5. 持续迭代，直到配置有效（平均 2–3 轮）
6. 满怀信心地部署

核心原则：

• 关注操作：不同操作有不同要求
• 渐进式呈现：从最少配置开始，按需添加
• 关注依赖：了解字段可见性规则
• 以验证为依据：让验证结果指导配置

相关技能：

• n8n MCP Tools Expert - 如何正确使用发现工具
• n8n Validation Expert - 解读验证错误
• n8n Expression Syntax - 配置表达式字段
• n8n Workflow Patterns - 使用正确配置应用模式