【n8n教程】：Split Out节点，一键将列表分割成单个项目

什么是Split Out节点？

Split Out节点是n8n中用于处理列表数据的核心工具。它的作用很简单但强大：将一个包含列表的数据项分割成多个单独的数据项。想象你有一份包含100名客户的列表，Split Out节点能够将这份列表"解包"，让每个客户变成一个独立的项目，这样你就可以逐个处理他们。

这种分割能力在以下场景中特别有用：

• 发送个性化邮件：将客户列表分割后，为每个客户发送定制化邮件
• 调用外部API：每个项目分别调用API进行处理
• 处理表格数据：将电子表格中的行数据逐行处理
• 嵌套数组展开：处理API返回的复杂JSON结构中的嵌套数组

核心参数详解

Split Out节点配置虽然简洁，但每个参数都很关键。让我逐一讲解：

1. 要分割的字段（Field to Split Out）

这是最重要的设置——指定哪个字段包含你要分割的列表。

示例：如果你的数据看起来像这样：

{
  "customers": [
    { "name": "张三", "email": "zhangsan@example.com" },
    { "name": "李四", "email": "lisi@example.com" }
  ],
  "companyId": "COMP-001"
}

那么你应该在"要分割的字段"中填入 customers。

特殊提示：如果处理二进制数据，可以使用表达式 $binary 来设置要分割的字段。

2. 包含（Include）

这个参数控制分割后的每个项目是否保留原始数据中的其他字段。有四个选项：

选项	说明	应用场景
不包含其他字段	只保留分割出来的数据	只关心列表内容，不需要上下文信息
包含所有其他字段	每个项目都附带原始的其他所有字段	需要保留上下文（如公司ID、时间戳等）
仅包含选定字段	手工选择要保留的字段	需要特定的几个上下文字段
字段列表	用逗号分隔输入字段名称	精细控制保留哪些字段

3. 输出字段名称（Destination Field Name）

指定分割后数据应该放在哪个字段名下。默认情况下，分割出的数据会保留原始字段名。

示例：

• 原始字段名：customers
• 输出字段名：customer（单数形式）

分割后每个项目会变成：

{
  "customer": { "name": "张三", "email": "zhangsan@example.com" },
  "companyId": "COMP-001"
}

4. 节点选项

除了主要参数，还有几个高级选项：

禁用点号记法（Disable Dot Notation）：

• 默认情况下，n8n支持 parent.child 的点号记法来访问嵌套字段
• 如果你的字段名本身包含点号（如 user.name），可以打开此选项来禁用点号记法

包含二进制数据（Include Binary）：

• 当处理包含文件、图像等二进制数据的列表时，打开此选项确保二进制数据也被分割保留

实战示例：从API获取客户列表并逐个处理

现在通过一个完整的实例来看Split Out如何在真实场景中工作。

场景描述：你的公司系统通过API获取客户列表，需要：

1. 获取所有客户数据
2. 将列表分割成单个客户
3. 分别处理活跃客户和非活跃客户

工作流JSON代码（可直接导入到n8n）：

{
  "name": "Split Out - 客户列表处理示例",
  "nodes": [
    {
      "parameters": {},
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Start",
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [250, 300]
    },
    {
      "parameters": {
        "functionCode": "return {\n  \"json\": {\n    \"customers\": [\n      { \"id\": 1, \"name\": \"张三\", \"email\": \"zhangsan@example.com\", \"status\": \"active\" },\n      { \"id\": 2, \"name\": \"李四\", \"email\": \"lisi@example.com\", \"status\": \"active\" },\n      { \"id\": 3, \"name\": \"王五\", \"email\": \"wangwu@example.com\", \"status\": \"inactive\" }\n    ],\n    \"companyId\": \"COMP-001\",\n    \"fetchTime\": new Date().toISOString()\n  }\n};"
      },
      "id": "11111111-1111-1111-1111-111111111111",
      "name": "模拟API响应",
      "type": "n8n-nodes-base.code",
      "typeVersion": 1,
      "position": [450, 300]
    },
    {
      "parameters": {
        "fieldToSplitOut": "customers",
        "include": "allOtherFields",
        "destinationFieldName": "customer"
      },
      "id": "22222222-2222-2222-2222-222222222222",
      "name": "Split Out - 分割客户列表",
      "type": "n8n-nodes-base.splitOut",
      "typeVersion": 1,
      "position": [650, 300]
    },
    {
      "parameters": {
        "conditions": {
          "string": [
            {
              "value1": "{{ $json.customer.status }}",
              "operation": "equals",
              "value2": "active"
            }
          ]
        }
      },
      "id": "33333333-3333-3333-3333-333333333333",
      "name": "IF - 检查是否为活跃客户",
      "type": "n8n-nodes-base.if",
      "typeVersion": 1,
      "position": [850, 300]
    },
    {
      "parameters": {
        "fields": {
          "string": {
            "customer_id": "{{ $json.customer.id }}",
            "customer_name": "{{ $json.customer.name }}",
            "customer_email": "{{ $json.customer.email }}",
            "company_id": "{{ $json.companyId }}",
            "processed_at": "{{ $json.fetchTime }}"
          }
        }
      },
      "id": "44444444-4444-4444-4444-444444444444",
      "name": "处理活跃客户",
      "type": "n8n-nodes-base.set",
      "typeVersion": 1,
      "position": [1050, 200]
    },
    {
      "parameters": {
        "fields": {
          "string": {
            "customer_id": "{{ $json.customer.id }}",
            "customer_name": "{{ $json.customer.name }}",
            "status": "skipped",
            "reason": "非活跃客户"
          }
        }
      },
      "id": "55555555-5555-5555-5555-555555555555",
      "name": "处理非活跃客户",
      "type": "n8n-nodes-base.set",
      "typeVersion": 1,
      "position": [1050, 400]
    }
  ],
  "connections": {
    "Start": {
      "main": [
        [
          {
            "node": "模拟API响应",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "模拟API响应": {
      "main": [
        [
          {
            "node": "Split Out - 分割客户列表",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Split Out - 分割客户列表": {
      "main": [
        [
          {
            "node": "IF - 检查是否为活跃客户",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "IF - 检查是否为活跃客户": {
      "main": [
        [
          {
            "node": "处理活跃客户",
            "type": "main",
            "index": 0
          }
        ],
        [
          {
            "node": "处理非活跃客户",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}

工作流执行流程：

1. 模拟API响应：返回包含3个客户的列表
2. Split Out节点：将customers数组分割成3个独立项目，每个项目都保留companyId和fetchTime
3. IF节点：判断每个客户的状态
4. 分别处理：活跃客户和非活跃客户走不同的处理路径

执行结果：从1个包含3个客户的项目，变成3个独立项目，每个都可以独立处理！

常见误区与最佳实践

✅ 何时应该使用Split Out

• 列表中的每个元素都需要独立处理（如发送邮件）
• 需要对列表元素进行条件判断后采取不同行动
• API返回的数据是嵌套的列表结构，需要展开处理

❌ 何时不应该使用Split Out

• 只需要查看或统计列表中的数据
• 需要保留列表结构进行后续操作
• 数据量非常大（数千项以上），可能导致工作流执行变慢

💡 最佳实践

1. 始终检查"包含"设置：如果需要在处理每个项目时引用原始数据中的上下文信息（如用户ID、公司ID），务必选择"包含所有其他字段"或"仅包含选定字段"
2. 使用有意义的输出字段名：将customers改为customer（单数），让代码更易读
3. 在Split Out后添加调试节点：运行一次工作流，查看执行结果中分割后每个项目的结构，确保符合预期
4. 结合IF节点做条件处理：Split Out最强大的功能是与IF节点结合，实现按条件分别处理不同的项目

快速参考卡

Split Out节点配置速查表
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
要分割的字段: customers
包含: 包含所有其他字段
输出字段名: customer
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
输入: {"customers": [...], "id": "123"}
输出: {"customer": {...}, "id": "123"}
      {"customer": {...}, "id": "123"}
      {"customer": {...}, "id": "123"}

官方文档^[1]
n8n系列教程^[2]

引用链接

[1] 官方文档: https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.splitout/
[2] n8n系列教程: https://www.undsky.com/blog/?category=n8n%E6%95%99%E7%A8%8B#