n8n-node-configuration-official

n8n 节点配置

每个 n8n 节点都有自己的参数结构，且通常包含条件字段（只有参数 Y 的值为 Z 时，参数 X 才会生效）。不同版本的结构会有所变化。猜测会导致难以理解的验证错误。

不要猜测，使用 get_node_types 工具。

不容妥协

**配置节点之前，必须使用判别参数（resource、operation、mode）调用 get_node_types。**不带判别参数会返回通用结构，缺少特定操作的参数和必填字段。请根据确切结构进行配置。不要凭记忆猜测。

**实时的 get_node_types 输出是规范的参数结构。**本技能中的参考资料介绍了模式、易错点、安全规则和决策方法（何时使用哪种操作、为什么使用凭据而不是文本字段、引擎重试上限等），而不是参数名称或字段结构。如果参考示例与 get_node_types 返回的内容冲突，请以工具为准。Markdown 文档可能过时；类型定义是根据实时源代码生成的。

**绝不要猜测资源定位器或加载选项的值。**当 get_node_types 显示某个参数带有 @searchListMethod 或 @loadOptionsMethod（Slack 频道、Sheets 标签页／文档、数据库表／列、模型列表、标签）时，请使用 explore_node_resources 查找实际值（传入 list_credentials 返回的 credentialId），并使用返回的 value。如果你已经知道确切 ID，就使用它；如果有多个匹配项且意图不明确，请询问用户。虚构的 ID 虽然能通过验证，但实际并不存在。例外：toolWorkflow.workflowId 没有搜索方法，请通过 search_workflows 查找，并使用 mode: 'id'。

强烈建议

• **优先配置操作。**先设置 resource 和 operation，这样条件参数才会显示。多数“字段不存在”错误，实际上是因为“尚未设置父级操作”。
• **切换操作时，不要沿用参数。**切换 operation 后，请根据新结构重新推导参数。上一个操作遗留的参数会导致验证失败。

新建节点的流程

1. search_nodes(['<capability keyword>'])
   → returns matching node IDs + discriminators
2. Pick the right (resource, operation) for the task.
3. get_node_types([{ name: '...', resource: '...', operation: '...' }])
   → returns exact parameter shape including conditional fields
4. For any RLC / load-options param in that shape, ground the real value:
   explore_node_resources({ nodeType, version, methodName, methodType, credentialType, credentialId, currentNodeParameters? })
   → use a returned `value`. Don't invent IDs.
5. Build the node config from that shape.
6. validate_workflow → fix errors.
7. get_workflow_details → inspect the saved config; confirm parameters landed.
8. test_workflow with pinned data → confirm runtime behavior.

跳过任何一步都会导致后续步骤的问题层层累积。最常被跳过的是第 3 步，继而出现“Cannot read property X”错误；其真正原因其实是“没有传入判别参数”。

validate_node_config 作为旁路检查

validate_node_config([{ type, typeVersion, parameters, isToolNode? }]) 会在隔离的节点配置上运行与 validate_workflow 相同的 Zod schema。它只检查 schema 层面，不能替代 validate_workflow（发布前仍需通过完整验证）。适用于：

• **构建过程中迭代单个节点。**比每次修改都重新运行 validate_workflow 更快。
• **小幅修改现有工作流。**连线未变？检查你修改的那个节点；发布前再进行完整验证。
• **调试配置错误的节点。**提供逐参数的错误信息，不受图结构噪声干扰。

对于工具子节点（通过 ai_tool 连线），请设置 isToolNode: true，以便评估正确的 displayOptions 分支。

根据操作配置

大多数节点的顶层结构如下：

{
  resource: '<thing being operated on>',   // 'message', 'spreadsheet', 'user', etc.
  operation: '<verb>',                      // 'send', 'append', 'lookup', etc.
  // ...operation-specific parameters
}

(resource, operation) 组合决定了其他参数的存在与否（例如，Slack 的 (message, send) 与 (user, info) 不同）。

模式：

1. 先设置 resource 和 operation。
2. 如果一开始没有传入这些判别参数，请使用它们重新获取 get_node_types。
3. 根据特定操作的结构配置其余参数。

属性依赖：容易忽略的陷阱

某些参数之间存在不明显的依赖关系：

• 仅当另一个字段具有特定值时，某个字段才是必填项。
• 某个字段会根据模式接受不同类型的值。
• 某个字段的选项取决于另一个字段的值。

示例：

• HTTP Request 的 authentication: 'genericCredentialType' 要求提供 genericAuthType 和 credentials，而 'predefinedCredentialType' 要求使用不同的结构。
• Postgres 的 operation: 'executeQuery' 要求提供 query，而 operation: 'select' 要求提供 table 和 columns。
• Slack 的 messageType: 'block' 会启用区块构建器字段，而 messageType: 'text' 中没有这些字段。

对于具体操作，始终通过 get_node_types 检查。不要复用其他操作的配置并期待它通过验证。

来自其他字段的选项由 @loadOptionsMethod 提供：使用 explore_node_resources（methodType: 'loadOptions'）解析实时选项；如果该方法依赖先前的选择，请通过 currentNodeParameters 传入（例如，列出电子表格中的工作表需要 documentId）。

参考文件

各类别常见问题。配置节点类型时，请阅读对应文件：

文件	阅读时机
references/HTTP_NODES.md	配置 HTTP Request：身份验证、分页、查询参数／正文参数、重试
references/WEBHOOK_NODES.md	配置 Webhook trigger 或 Respond to Webhook：正文解析、响应结构、异步模式
references/COMMS_NODES.md	Slack、Gmail、Discord、电子邮件：凭据类型、消息结构、附件
references/DATABASE_NODES.md	Postgres、MySQL、Mongo、Supabase：查询与操作、参数绑定、错误处理
references/AI_NODES.md	AI Agent 节点配置项：流式传输、视觉、maxIterations、模型子节点上的重试。提示词、工具、记忆、结构化输出等设计请参阅 n8n-ai-nodes-official
references/TRIGGER_NODES.md	Webhook、Schedule、Manual、Execute Workflow Trigger：输入架构、轮询与实时触发
references/SWITCH_FALLBACK.md	配置 Switch 节点：未命名的输出／缺少 fallback 会静默丢弃不匹配的条目
references/MERGE_NODE.md	配置 Merge 节点，或遇到 useDataOfInput、numberOfInputs 或分支汇合的情况

反模式

反模式	问题	修复方法
凭记忆中节点去年的样子来构建节点配置	参数结构已有变化，验证会因晦涩的错误而失败	每次会话中都对每个节点调用 get_node_types
在 get_node_types 中省略区分参数	获取到通用结构，遗漏特定操作的必填字段	始终传入 resource 和 operation（存在 mode 时也要传入）
将一个操作的节点配置复制到另一个操作并稍作修改	过时的参数会导致验证失败，条件字段也不适用	根据新操作的结构重新推导配置
在节点文本字段中硬编码令牌／凭据	导出时会泄露。请参阅 n8n-credentials-and-security-official	始终使用凭据
配置后不使用 test_workflow 测试节点	运行时错误只有在真实数据上才会显现	发布前始终使用固定数据进行测试