介绍

在你连接首个真实工作流到 n8n 之前，需要理解一件几乎所有初学者都会被绊住的事情：n8n 不会在节点之间传递原始文件或流。它传递的是条目。无论是 webhook 载荷、数据库行、API 响应，都会在移动到下一个节点之前被包装成一个结构化的条目。尽早掌握这一心智模型，调试就会变得极其容易。

什么是一个条目？

条目是 n8n 数据的基本单元。每个节点接收一个条目数组并输出一个条目数组。每个条目是一个 JavaScript 对象，必需包含一个名为 json 的键，该键保存实际的载荷数据，作为一个 JSON 对象。可选地，条目还可以携带二进制数据（如文件、图像等），但这部分另行说明。

一个条目在本质上看起来是这样的：

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

当像 HTTP 请求这样的节点从 API 获取用户列表时，n8n 不会把下一节点接收一个大数组。它会将该数组拆分，为下一节点逐个提供一个条目。也就是说，如果你的 API 返回 10 个用户，随后节点将执行 10 次 — 每次处理一个条目。这个行为是 n8n 的根本思维方式。

JSON 如何在节点之间流动

当你引用上一个节点的数据时，你始终是在访问条目的 json 键中的数据。在表达式中，n8n 使用以下语法来访问前一个节点的输出：

{{ $json.fieldName }}

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

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

在实践中，如果你有一个 Set 节点，它会生成一个具有前面显示的结构的项目，那么下一个节点可以像这样引用用户的电子邮件：

{{ $json.email }}

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

执行模型

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

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

这有重要的含义：

首先，链中的每个节点默认对每个项目都运行一次。一个附加时间戳字段的节点对于 50 项将运行 50 次，产生 50 个输出项。

其次，一些节点会刻意合并或拆分项目计数。Merge 节点可以将流合并。SplitInBatches 节点可以对项目进行分组。如果需要，Code 节点可以重塑整个数组。了解工作流中项目计数如何变化，对避免意外行为至关重要。

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

实际示例

以下是进入 Code 节点时实际的 item 数组样子。你可以通过内置调试器查看任意节点的输出面板来检查。

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

如果你在这个之后放置一个 Code 节点并希望为每个项目添加一个 processed 标志，你可以写：

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

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

摘要

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