n8n-connections

n8n 连接

n8n 的 SDK 采用简洁的连接语法。其中两种写法会悄悄生成无法正常工作的工作流，但验证却能通过。这项技能主要讲如何避免这些陷阱。

不容妥协：.to() 陷阱

.to() 必须放在 .add() 内部，不能放在外面。

.add(node.output(0)).to(target)      // ❌ connection silently dropped
.add(node.output(0).to(target))      // ✅

validate_workflow 无法发现这个问题。工作流会验证通过、发布并运行，但连接线并不存在。这个错误看起来和节点配置错误或“未触发”完全一样。

如果你把 .add(...).to(...) 写在括号外面，那就是有问题。没有例外。

通用连接模式

一种写法适用于 IF/Switch 分支、错误输出、合并输入以及任何通用的多输入/输出：

.add(source.output(n).to(target))

• source.output(n)：选择输出（从 0 开始索引）
• .to(target)：选择目标（默认输入为 0）
• .to(target.input(m))：选择目标上的特定输入（从 0 开始索引）

每条连接线调用一次 .add()。要分流，就重复调用 .add()。

决策树

Wiring a connection?
├── Linear (one source → one target, single output, single input)?
│   └── .add(source).to(target). The simple case; .to() outside is fine here
│       because there's no .output(n) selector inside .add()
│
├── Selector involved (.output(n) or composite handlers)?
│   └── .to() MUST go inside .add(). See "the trap" above
│
├── Targeting a specific input slot on a multi-input node (Merge)?
│   └── .add(source.output(n).to(target.input(m)))
│       AND check useDataOfInput. See references/MERGE_INDEX_RULES.md
│
├── Error branch?
│   └── .add(node.output(1).to(handler))
│       AND set onError: 'continueErrorOutput' on the node config.
│       See references/ERROR_OUTPUTS.md
│
└── Fan-out (one source → many targets) or fan-in (many sources → one target)?
    └── See references/FAN_OUT_FAN_IN.md

组合处理器（.onTrue、.onFalse、.onCase、.onError）

SDK 为 IF、Switch 以及任何带有错误输出的节点提供了便捷处理器：

.add(ifNode.onTrue(targetA))     // same as .add(ifNode.output(0).to(targetA))
.add(ifNode.onFalse(targetB))    // same as .add(ifNode.output(1).to(targetB))
.add(sw.onCase(2, target))       // same as .add(sw.output(2).to(target))
.add(node.onError(handler))      // same as .add(node.output(1).to(handler))

这些处理器可以与 .output(n) 调用组合使用，互不冲突。

.add(ifNode.onTrue(targetA))
.add(ifNode.output(0).to(targetB))
// Result: BOTH targetA and targetB on IF's main[0]. Composite + .output(n) merge.

唯一需要避免的写法是上文的 .add(selector).to(target) 陷阱。无论之前是否运行过组合处理器，这种写法始终是错误的。

每次创建或更新后：验证

即使缺少连接线，validate_workflow 仍会报告有效。在调用 create_workflow_from_code 或 update_workflow 后，请使用 get_workflow_details 拉取工作流并检查 connections 对象：

• 每个 main[i] 都应包含预期的目标集合（保留分流，不要合并）。
• 合并输入应连接到正确的索引，并且 useDataOfInput 要与连接方式一致。
• 错误输出节点应设置 onError: 'continueErrorOutput'，并且 main[1] 应连接到处理器。

如果任何一项检查未通过，即使工作流通过了验证，它仍然存在问题。请修复并重新更新。

完整的创建后检查清单见 references/VERIFICATION.md。

参考文件

根据情况阅读匹配的文件。不要全部阅读：

文件	阅读时机
references/FAN_OUT_FAN_IN.md	一个来源连接到多个目标，或多个来源连接到一个目标
references/MERGE_INDEX_RULES.md	连接 Merge 节点，或在节点配置中看到 useDataOfInput
references/ERROR_OUTPUTS.md	为单个节点添加错误处理（不是错误工作流；错误工作流见 n8n-error-handling）
references/VERIFICATION.md	刚创建或更新了具有复杂连接的工作流

反模式

反模式	问题所在	修复方法
.add(node.output(0)).to(target)	连接线被悄悄丢弃，但验证仍会通过	将 .to() 移到 .add() 内部
将 useDataOfInput: "2" 与 .input(2) 混用	索引偏移，连接线会接入错误的输入	当 useDataOfInput: "N" 时，使用 .input(N - 1)。参见 MERGE_INDEX_RULES.md
连接错误分支，但未设置 onError: 'continueErrorOutput'	分支无法触达，节点出错时会导致整个工作流失败	在节点配置中设置 onError: 'continueErrorOutput'
创建后跳过 get_workflow_details	有问题的工作流会在无人察觉的情况下交付	创建或更新后务必拉取并检查
连接一条线之前就阅读全部四个参考文件	浪费上下文	只阅读与当前情况匹配的文件