n8n-node-configuration

n8n 节点配置

关于操作感知的节点配置与属性依赖的专业指南。

配置理念

渐进式披露：从最小配置开始，按需增加复杂度

配置最佳实践：

get_node 配合 detail: "standard" 是最常用的发现模式
配置编辑平均间隔56秒
覆盖95%的使用场景，响应约1-2K tokens

关键洞察：大多数配置只需要标准详情，而非完整模式！

核心概念

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 不是必需的
}

关键：资源 + 操作决定了哪些字段是必需的！

2. 属性依赖

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

示例：HTTP Request 节点

// 当 method='GET'
{
  "method": "GET",
  "url": "https://api.example.com"
  // sendBody 不显示（GET 没有请求体）
}

// 当 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 tokens）
- 必填字段 + 常用选项
- 首先使用 - 覆盖95%的需求
get_node({mode: "search_properties", propertyQuery: "..."})（用于查找特定字段）
- 按名称查找属性
- 在查找认证、请求体、请求头等时使用
get_node({detail: "full"})（完整模式）
- 所有属性（约3-8K tokens）
- 仅在标准详情不足时使用

配置工作流

标准流程

确定节点类型和操作。
使用 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 tokens）：

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

使用：95%的配置需求

完整详情（谨慎使用）

✅ 当标准详情不足时

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

返回（约3-8K tokens）：

完整模式
所有属性
所有嵌套选项

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

搜索属性模式

✅ 查找特定字段

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

使用：查找认证、请求头、请求体字段等。

决策树

开始新节点配置 → 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": "<实体>",      // 事物的类型
  "operation": "<操作>",     // 对其执行的操作
  // ... 操作特定字段
}

如何配置：

选择资源
选择操作
使用 get_node 查看操作特定要求
配置必填字段

模式 2：基于 HTTP 的节点

示例：HTTP Request、Webhook

结构：

{
  "method": "<HTTP_METHOD>",
  "url": "<端点>",
  "authentication": "<类型>",
  // ... 方法特定字段
}

依赖：

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": {
    "<类型>": [
      {
        "operation": "<运算符>",
        "value1": "...",
        "value2": "..."  // 仅用于二元运算符
      }
    ]
  }
}

依赖：

二元运算符（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。

处理条件性需求

某些字段仅在特定条件下必需：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 主体或长文本字段中的拼写错误

// 而不是替换整个 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 是严格的——如果未找到查找字符串或匹配多次（除非 replaceAll: true），它会报错。这可以防止在配置更新期间发生意外的静默失败。有关完整语法和示例，请参阅 n8n MCP Tools Expert 技能。

最佳实践

应该做

从 get_node（标准详情）开始
- 约1-2K tokens 响应
- 覆盖95%的配置需求
- 默认详细级别
迭代验证
- 配置 → 验证 → 修复 → 重复
- 平均2-3次迭代是正常的
- 仔细阅读验证错误
卡住时使用 search_properties 模式
- 如果字段似乎缺失，搜索它
- 理解什么控制字段可见性
- get_node({mode: "search_properties", propertyQuery: "..."})
尊重操作上下文
- 不同操作 = 不同需求
- 更改操作时始终检查 get_node
- 不要假设配置是可转移的
信任自动清理
- 运算符结构自动修复
- 不要手动添加/删除 singleValue
- IF/Switch 元数据在保存时添加

❌ 不要做

立即跳转到 detail="full"
- 先尝试标准详情
- 仅在需要时升级
- 完整模式为3-8K tokens
盲目配置
- 部署前始终验证
- 理解为什么字段是必需的
- 对条件字段使用 search_properties
不理解就复制配置
- 不同操作需要不同字段
- 复制后验证
- 根据新上下文调整
手动修复自动清理问题
- 让自动清理处理运算符结构
- 专注于业务逻辑
- 保存并让系统修复结构

按节点家族的静默失败陷阱

某些错误配置能通过 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 — 时区是工作流级别的（工作流设置），而不是每个规则的。

完整的症状/原因/修复详情（以 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 - 使用正确配置应用模式

你可能还喜欢

clickhouse-io

230Kdatabase

ClickHouse database patterns, query optimization, analytics, and data engineering best practices for high-performance analytical workloads.

affaan-m

获取

postgres-pro

11Kdatabase

Use when optimizing PostgreSQL queries, configuring replication, or implementing advanced database features. Invoke for EXPLAIN analysis, JSONB operations, extension usage, VACUUM tuning, performance monitoring.

jeffallan

获取

supabase-postgres-best-practices

2.2Kdatabase

来自 Supabase 的 Postgres 性能优化和最佳实践。在编写、审查或优化 Postgres 查询、模式设计或数据库配置时使用此技能。

supabase

获取

继续探索

浏览 database 热门 Skills 最近更新