n8n-node-configuration

n8n 节点配置

为你提供包含属性依赖项的操作感知型节点配置专家指导。

---

配置理念

渐进式披露：从最简配置开始，根据需要逐步增加复杂度

配置最佳实践：

• get_node_essentials 是最常用的发现模式
• 配置编辑之间平均间隔 56 秒
• 基于 essentials 的配置成功率为 91.7%

关键要点：大多数配置只需要 essentials，而不需要完整架构！

---

核心概念

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_essentials（成功率为 91.7%）

   • 快速概览
   • 必填字段
   • 常用选项
   • 优先使用——可满足 90% 的需求

2. get_property_dependencies（适用于复杂节点）

   • 显示字段之间的依赖关系
   • 揭示条件要求
   • essentials 不够用时使用

3. get_node_info（完整架构）

   • 完整文档
   • 所有可能的字段
   • essentials + 依赖项仍不够用时使用

---

配置工作流

标准流程

1. Identify node type and operation
   ↓
2. Use get_node_essentials
   ↓
3. Configure required fields
   ↓
4. Validate configuration
   ↓
5. If dependencies unclear → get_property_dependencies
   ↓
6. Add optional fields as needed
   ↓
7. Validate again
   ↓
8. Deploy

示例：配置 HTTP Request

步骤 1：确定需求

// Goal: POST JSON to API

步骤 2：获取 essentials

const info = get_node_essentials({
  nodeType: "nodes-base.httpRequest"
});

// Returns: method, url, sendBody, body, authentication required/optional

步骤 3：最简配置

{
  "method": "POST",
  "url": "https://api.example.com/create",
  "authentication": "none"
}

步骤 4：验证

validate_node_operation({
  nodeType: "nodes-base.httpRequest",
  config,
  profile: "runtime"
});
// → Error: "sendBody required for POST"

步骤 5：添加必填字段

{
  "method": "POST",
  "url": "https://api.example.com/create",
  "authentication": "none",
  "sendBody": true
}

步骤 6：再次验证

validate_node_operation({...});
// → Error: "body required when sendBody=true"

步骤 7：完成配置

{
  "method": "POST",
  "url": "https://api.example.com/create",
  "authentication": "none",
  "sendBody": true,
  "body": {
    "contentType": "json",
    "content": {
      "name": "={{$json.name}}",
      "email": "={{$json.email}}"
    }
  }
}

步骤 8：最终验证

validate_node_operation({...});
// → Valid! ✅

---

get_node_essentials 与 get_node_info 的比较

适用场景：get_node_essentials

✅ 开始配置时（成功率为 91.7%）

get_node_essentials({
  nodeType: "nodes-base.slack"
});

返回内容：

• 必填字段
• 常用选项
• 基本示例
• 操作列表

速度快：平均约 18 秒（从搜索到获取 essentials）

适用场景：get_node_info

✅ essentials 不够用时

get_node_info({
  nodeType: "nodes-base.slack"
});

返回内容：

• 完整架构
• 所有属性
• 完整文档
• 高级选项

速度较慢：需要处理更多数据

决策树

┌─────────────────────────────────┐
│ Starting new node config?       │
├─────────────────────────────────┤
│ YES → get_node_essentials       │
└─────────────────────────────────┘
         ↓
┌─────────────────────────────────┐
│ Essentials has what you need?   │
├─────────────────────────────────┤
│ YES → Configure with essentials │
│ NO  → Continue                  │
└─────────────────────────────────┘
         ↓
┌─────────────────────────────────┐
│ Need dependency info?           │
├─────────────────────────────────┤
│ YES → get_property_dependencies │
│ NO  → Continue                  │
└─────────────────────────────────┘
         ↓
┌─────────────────────────────────┐
│ Still need more details?        │
├─────────────────────────────────┤
│ YES → get_node_info             │
└─────────────────────────────────┘

---

深入了解属性依赖项

displayOptions 机制

字段具有可见性规则：

{
  "name": "body",
  "displayOptions": {
    "show": {
      "sendBody": [true],
      "method": ["POST", "PUT", "PATCH"]
    }
  }
}

解释：“body”字段在以下条件成立时显示：

• sendBody = true，且
• method = POST、PUT 或 PATCH

常见依赖模式

模式 1：布尔开关

示例：HTTP Request 的 sendBody

// sendBody controls body visibility
{
  "sendBody": true   // → body field appears
}

模式 2：操作切换

示例：Slack 的 resource/operation

// Different operations → different fields
{
  "resource": "message",
  "operation": "post"
  // → Shows: channel, text, attachments, etc.
}

{
  "resource": "message",
  "operation": "update"
  // → Shows: messageId, text (different fields!)
}

模式 3：类型选择

示例：IF 节点条件

{
  "type": "string",
  "operation": "contains"
  // → Shows: value1, value2
}

{
  "type": "boolean",
  "operation": "equals"
  // → Shows: value1, value2, different operators
}

使用 get_property_dependencies

示例：

const deps = get_property_dependencies({
  nodeType: "nodes-base.httpRequest"
});

// Returns dependency tree
{
  "dependencies": {
    "body": {
      "shows_when": {
        "sendBody": [true],
        "method": ["POST", "PUT", "PATCH", "DELETE"]
      }
    },
    "queryParameters": {
      "shows_when": {
        "sendQuery": [true]
      }
    }
  }
}

适用场景：验证失败，且你不明白为什么缺少某字段或该字段为何必填

---

常见节点模式

模式 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_essentials 查看特定于操作的要求
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" → 凭据必填

模式 3：数据库节点

示例：Postgres、MySQL、MongoDB

结构：

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

依赖项：

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

模式 4：条件逻辑节点

示例：IF、Switch、Merge

结构：

{
  "conditions": {
    "<type>": [
      {
        "operation": "<operator>",
        "value1": "...",
        "value2": "..."  // Only for binary operators
      }
    ]
  }
}

依赖项：

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

---

特定操作的配置

Slack 节点示例

发布消息

{
  "resource": "message",
  "operation": "post",
  "channel": "#general",      // Required
  "text": "Hello!",           // Required
  "attachments": [],          // Optional
  "blocks": []                // Optional
}

更新消息

{
  "resource": "message",
  "operation": "update",
  "messageId": "1234567890",  // Required (different from post!)
  "text": "Updated!",         // Required
  "channel": "#general"       // Optional (can be inferred)
}

创建频道

{
  "resource": "channel",
  "operation": "create",
  "name": "new-channel",      // Required
  "isPrivate": false          // Optional
  // Note: text NOT required for this operation
}

HTTP Request 节点示例

GET 请求

{
  "method": "GET",
  "url": "https://api.example.com/users",
  "authentication": "predefinedCredentialType",
  "nodeCredentialType": "httpHeaderAuth",
  "sendQuery": true,                    // Optional
  "queryParameters": {                  // Shows when sendQuery=true
    "parameters": [
      {
        "name": "limit",
        "value": "100"
      }
    ]
  }
}

使用 JSON 的 POST

{
  "method": "POST",
  "url": "https://api.example.com/users",
  "authentication": "none",
  "sendBody": true,                     // Required for POST
  "body": {                             // Required when sendBody=true
    "contentType": "json",
    "content": {
      "name": "John Doe",
      "email": "[email protected]"
    }
  }
}

IF 节点示例

字符串比较（二元）

{
  "conditions": {
    "string": [
      {
        "value1": "={{$json.status}}",
        "operation": "equals",
        "value2": "active"              // Binary: needs value2
      }
    ]
  }
}

空值检查（一元）

{
  "conditions": {
    "string": [
      {
        "value1": "={{$json.email}}",
        "operation": "isEmpty",
        // No value2 - unary operator
        "singleValue": true             // Auto-added by sanitization
      }
    ]
  }
}

---

处理条件要求

示例：HTTP Request 请求体

场景：body 字段为必填项，但仅在某些情况下必填

规则：

body is required when:
  - sendBody = true AND
  - method IN (POST, PUT, PATCH, DELETE)

如何发现：

// Option 1: Read validation error
validate_node_operation({...});
// Error: "body required when sendBody=true"

// Option 2: Check dependencies
get_property_dependencies({
  nodeType: "nodes-base.httpRequest"
});
// Shows: body → shows_when: sendBody=[true], method=[POST,PUT,PATCH,DELETE]

// Option 3: Try minimal config and iterate
// Start without body, validation will tell you if needed

示例：IF 节点的 singleValue

场景：一元运算符会出现 singleValue 属性

规则：

singleValue should be true when:
  - operation IN (isEmpty, isNotEmpty, true, false)

好消息：自动清理会修复此问题！

手动检查：

get_property_dependencies({
  nodeType: "nodes-base.if"
});
// Shows operator-specific dependencies

---

配置反模式

❌ 不要：一开始就过度配置

错误示例：

// 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_operation({...});
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_essentials({
  nodeType: "nodes-base.slack"
});
// See what update operation needs (messageId, not channel)

---

最佳实践

✅ 应该做

1. 从 get_node_essentials 开始

   • 成功率为 91.7%
   • 比 get_node_info 更快
   • 足以满足大多数需求

2. 迭代验证

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

3. 遇到困难时使用属性依赖项

   • 如果字段似乎缺失，请检查依赖项
   • 了解哪些因素控制字段可见性
   • get_property_dependencies 会揭示相关规则

4. 遵循操作上下文

   • 不同操作 = 不同要求
   • 更改操作时，始终检查 essentials
   • 不要假设配置可以通用

5. 信任自动清理

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

❌ 不应该做

1. 立即转而使用 get_node_info

   • 先尝试 essentials
   • 仅在需要时升级
   • 完整架构会让人不知所措

2. 盲目配置

   • 部署前始终进行验证
   • 了解字段必填的原因
   • 检查条件字段的依赖项

3. 不理解就复制配置

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

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

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

---

详细参考资料

如需特定主题的完整指南，请参阅：

• DEPENDENCIES.md - 深入了解属性依赖项和 displayOptions
• OPERATION_PATTERNS.md - 按节点类型整理的常见配置模式

---

总结

配置策略：

1. 从 get_node_essentials 开始（成功率为 91.7%）
2. 配置该操作所需的字段
3. 验证配置
4. 遇到困难时检查依赖项
5. 持续迭代，直到配置有效（平均 2-3 轮）
6. 满怀信心地部署

核心原则：

• 感知操作：不同操作 = 不同要求
• 渐进式披露：从最少配置开始，按需添加
• 感知依赖项：了解字段可见性规则
• 验证驱动：让验证引导配置

相关技能：

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