Lesson 1: n8n 如何组织数据 — Items、JSON 与执行模型

简介

在将你的第一个真实工作流连线之前，你需要理解几乎所有初学者都会犯的一点：n8n 不能在节点之间传递原始文件或数据流。它传递的是 items。无论是 webhook 载荷、数据库行、API 响应，都会被包装成一个结构化的 item 再传递到下一个节点。尽早掌握这个心智模型，调试将变得非常容易。

什么是一个 Item？

Item 是 n8n 中数据的基本单元。每个节点接收一个 items 数组并输出一个 items 数组。每个 item 都是一个具有必需的 json 键的 JavaScript 对象，json 键中存放你的实际载荷数据，以一个 JSON 对象的形式展现。可选地，item 还可以携带二进制数据（用于文件、图片等），但这部分内容单独介绍。

一个单独的 item 的核心结构如下：

json

{
  "json": {
    "id": 42,
    "name": "Alice",
    "email": "alice@example.com"
  }
}

当像 HTTP Request 这样的节点从 API 获取用户列表时，n8n 不会把一个大数组直接交给下一个节点。它会把该数组拆分为单独的 item，逐个传给下一个节点。这意味着如果你的 API 返回 10 个用户，下游节点将执行 10 次——每次处理一个 item。这种行为是 n8n 的基本工作方式。

显示一个流程图：HTTP Request 节点接收包含 3 个用户的 JSON 数组，然后拆分成 3 个单独的 item，进入下一个节点

JSON 在节点之间如何流动

当你引用来自上一个节点的数据时，你总是在访问一个 item 的 json 键。表达式中，n8n 使用下面的语法来访问上一个节点的输出：

javascript

{{ $json.fieldName }}

如果你想从一个特定命名节点而不是紧接着的前一个节点获取数据，你可以使用：

javascript

{{ $node["NodeName"].json.fieldName }}

在实际应用中，如果你有一个 Set 节点，它产生一个包含前面显示的结构的项，那么下一个节点可以这样引用用户的邮箱：

javascript

{{ $json.email }}

关键要点是要内化：你从来不是把原始的 HTTP 响应体作为字符串来处理。当数据到达你的表达式时，n8n 已经把它解析成 json 对象。你不需要自己调用 JSON.parse()。

执行模型

n8n 将项逐个通过每个节点处理，按顺序进行。当一个节点接收到多个项时，它会自动进行迭代——你不需要写循环。这被称为基于项的执行模型。

考虑一个工作流，从数据库读取 50 行数据，对每一行进行转换，并对每行发送一封邮件。你不需要写“为每行发送邮件”。你只需连接节点。n8n 会处理迭代。

这有重要的影响：

首先，链中的每个节点默认情况下对每个项只执行一次。一个向时间戳字段追加的节点将对 50 条目执行 50 次，输出 50 个项。

其次，有些节点会刻意地合并或拆分项的数量。Merge 节点可以把流合并。SplitInBatches 节点可以对项进行分组。Code 节点在需要时可以重塑整个数组。了解工作流中项数量如何变化，是避免意外行为的关键。

第三，如果任意节点在某个项上失败，默认情况下整个执行将停止。你可以按节点配置错误处理来改变这一点，但默认是快速失败。

显示执行模型的框图：节点 A 输出 4 条目，节点 B 针对每个条目单独处理，产生 4 个输出，节点 C（Merge）把它们合并回 1 条目

实践示例

以下是将进入 Code 节点时 item 数组实际样子。您可以通过内置调试器查看，方法是点击任意节点的输出面板进行检查。

json

[
  {
    "json": {
      "orderId": "ORD-001",
      "amount": 120.5,
      "status": "pending"
    }
  },
  {
    "json": {
      "orderId": "ORD-002",
      "amount": 89.0,
      "status": "shipped"
    }
  }
]

如果在这之后放置一个 Code 节点并希望为每个项添加一个 processed 标志，您需要编写：

javascript

for (const item of items) {
  item.json.processed = true;
}
return items;

请注意您在 Code 节点内对 items 进行遍历——这是关于“n8n 会为你处理循环”的唯一例外。Code 节点会将完整数组交给你，并期望你把完整数组返回。

摘要

n8n 中的每一条数据都被包装在带有 json 键的 item 中。节点接收并输出 items 数组，默认情况下每个节点对每个 item 运行一次——你不需要在 Code 节点之外管理循环。像 $json.fieldName 这样的表达式就是访问 item 数据的方式。理解这个执行模型是其他一切的基础：变换、分支、合并和错误处理都直接基于它构建。