n8n Code Node 数据访问模式完全指南:JavaScript 中的 `$input`、`$node` 与 Webhook 数据结构

原创2026-10-08 22:07:282,539 阅读
文章标签:AI 技能AI 插件工作流自动化MCP Clients提示工程人工智能

n8n Code Node 数据访问模式完全指南:JavaScript 中的 $input、$node 与 Webhook 数据结构

导读

本篇技术指南围绕 n8n(开源工作流自动化平台)Code node 中 JavaScript 数据访问的核心议题展开,系统讲解 $input.all()、$input.first()、$input.item、$node<a href="https://link.gitcode.com/i/8883e7d370080d962d2da2dfb724cfd6" target="_blank">"NodeName"] 四类访问方式的选择与实战,并深入剖析最容易踩坑的 Webhook .body 嵌套结构、执行模式(All Items / Each Item)的性能差异,以及 SplitInBatches 循环、pairedItem、浮点精度等生产级注意事项。读完本文,你将掌握一套可复制、可运行的 n8n Code node 数据访问决策框架,能够在批量聚合、单条处理、跨节点组合数据等场景中写出高效且不易出错的 JavaScript 代码。本文主体内容源自仓库 [DATA_ACCESS.md,并结合 SKILL.md、ERROR_PATTERNS.md、COMMON_PATTERNS.md、BUILTIN_FUNCTIONS.md 及评估用例(eval-001-webhook-body-gotcha.json、eval-002-return-format-error.json、eval-004-aggregation-pattern.json)做了源码级佐证与扩充。


一、Overview:理解 n8n Code node 的数据访问体系

在 n8n 的 Code node 中,你可以通过一组内置变量与方法读取上游节点的数据。选择哪种访问方式,直接决定工作流能否正确执行。n8n-skills 仓库对 Code node 数据访问的使用频率做了统计排序,形成如下优先级:

优先级 访问方式 使用频率 典型场景
1 $input.all() 最常用 批量操作、聚合、过滤、排序
2 $input.first() 很常用 单条对象操作、API 响应
3 $input.item 常用 仅在 "Run Once for Each Item" 模式下可用
4 $node["NodeName"].json 较少 引用指定命名节点的数据
5 $json 遗留 直接访问当前条目(建议改用 $input)

从 README.md 的文件结构说明可知,DATA_ACCESS.md 是这套 skill 的"数据访问主文档",与 COMMON_PATTERNS.md(生产模式库)、ERROR_PATTERNS.md(错误规避)、BUILTIN_FUNCTIONS.md(内置函数参考)共同构成完整的知识体系。本文聚焦数据访问,但会交叉引用这些文件中的相关证据。

一个贯穿全文的核心原则:所有条目对象的数据都位于 .json 属性下。$input.all() 返回的是形如 {json: {...}, pairedItem: {...}} 的条目数组,直接访问 item.name 会得到 undefined,必须写 item.json.name。


二、Pattern 1:$input.all()——批量处理所有条目

使用场景(来自 DATA_ACCESS.md):

  • 处理多条记录(多行数据)
  • 聚合计算(求和、计数、平均值)
  • 过滤数组
  • 数据集转换
  • 条目间相互比较
  • 排序或排名

2.1 基本用法

// 获取上游节点的所有条目
const allItems = $input.all();

// allItems 是形如下方的对象数组:
// [
//   {json: {id: 1, name: "Alice"}},
//   {json: {id: 2, name: "Bob"}}
// ]

console.log(`Received ${allItems.length} items`);

return allItems;

$input.all() 返回的数组可以直接作为返回值——因为条目本身已携带 json 属性,原样返回即为合法的透传(该行为在 SKILL.md 与 ERROR_PATTERNS.md 的 Return Shape 章节均有说明)。

2.2 示例 1:过滤活动条目

const allItems = $input.all();

// 仅保留 status 为 'active' 的条目
const activeItems = allItems.filter(item => item.json.status === 'active');

return activeItems;

2.3 示例 2:转换所有条目

const allItems = $input.all();

// 映射为新的结构
const transformed = allItems.map(item => ({
  json: {
    id: item.json.id,
    fullName: `${item.json.firstName} ${item.json.lastName}`,
    email: item.json.email,
    processedAt: new Date().toISOString()
  }
}));

return transformed;

2.4 示例 3:聚合数据(求和 / 计数 / 平均)

const allItems = $input.all();

// 计算总额
const total = allItems.reduce((sum, item) => {
  return sum + (item.json.amount || 0);
}, 0);

return [{
  json: {
    total,
    count: allItems.length,
    average: total / allItems.length
  }
}];

这一模式与 eval-004-aggregation-pattern.json 评估用例高度吻合:聚合场景要求使用 $input.all() + reduce(),并强调 item.json.amount || 0 的空值兜底与 "Run Once for All Items" 模式。注意 total / allItems.length 在空数组下会产生 NaN,生产代码应先做长度判断(见第六节 Mistake 4)。

2.5 示例 4:排序并截取 Top N

const allItems = $input.all();

// 按 score 降序取前 5 条
const topFive = allItems
  .sort((a, b) => (b.json.score || 0) - (a.json.score || 0))
  .slice(0, 5);

return topFive.map(item => ({json: item.json}));

2.6 示例 5:按类别分组

const allItems = $input.all();

// 按 category 分组
const grouped = {};

for (const item of allItems) {
  const category = item.json.category || 'Uncategorized';

  if (!grouped[category]) {
    grouped[category] = [];
  }

  grouped[category].push(item.json);
}

// 转换为数组格式
return Object.entries(grouped).map(([category, items]) => ({
  json: {
    category,
    items,
    count: items.length
  }
}));

2.7 示例 6:按 ID 去重

const allItems = $input.all();

// 通过 Set 按 id 去重
const seen = new Set();
const unique = [];

for (const item of allItems) {
  const id = item.json.id;

  if (!seen.has(id)) {
    seen.add(id);
    unique.push(item);
  }
}

return unique;

实现层面的补充:以上六个示例演示的 filter / map / reduce / sort / slice 正是 COMMON_PATTERNS.md 中"Best Practices"一节推荐的函数式数组方法。仓库明确指出:优先使用数组方法而非手写循环(filter→map→reduce 链式写法比 for 循环更清晰、更不易出错),并且要 先过滤、后转换——先缩小数据集,再执行昂贵的转换逻辑,避免对无用数据浪费 CPU。


三、Pattern 2:$input.first()——获取第一个条目

使用场景:

  • 上游节点只返回单个对象
  • 处理 API 响应
  • 获取初始 / 首个数据点
  • 读取配置或元数据

3.1 基本用法

// 获取上游节点的第一个条目
const firstItem = $input.first();

// 访问其 JSON 数据
const data = firstItem.json;

console.log('First item:', data);

return [{json: data}];

3.2 示例 1:处理单个 API 响应

// 获取 API 响应(通常是单个对象)
const response = $input.first().json;

// 提取所需字段
return [{
  json: {
    userId: response.data.user.id,
    userName: response.data.user.name,
    status: response.status,
    fetchedAt: new Date().toISOString()
  }
}];

3.3 示例 2:转换单个对象

const data = $input.first().json;

// 重组结构
return [{
  json: {
    id: data.id,
    contact: {
      email: data.email,
      phone: data.phone
    },
    address: {
      street: data.street,
      city: data.city,
      zip: data.zip
    }
  }
}];

3.4 示例 3:校验单条数据

const item = $input.first().json;

// 校验逻辑
const isValid = item.email && item.email.includes('@');

return [{
  json: {
    ...item,
    valid: isValid,
    validatedAt: new Date().toISOString()
  }
}];

3.5 示例 4:提取嵌套数据

const response = $input.first().json;

// 导航嵌套结构(可选链 + 默认值兜底)
const users = response.data?.users || [];

return users.map(user => ({
  json: {
    id: user.id,
    name: user.profile?.name || 'Unknown',
    email: user.contact?.email || 'no-email'
  }
}));

3.6 示例 5:与其他方法组合

// 取第一个条目的数据
const firstData = $input.first().json;

// 用它过滤全部条目
const allItems = $input.all();
const matching = allItems.filter(item =>
  item.json.category === firstData.targetCategory
);

return matching;

为什么 $input.first() 是安全的:当输入为空时,$input.all()[0] 会因 undefined[0] 抛错,而 $input.first() 内置了空值保护(见 ERROR_PATTERNS.md Error #5 的"Array Safety"小节)。因此对于"取首条"的需求,优先使用 $input.first() 而不是手写索引访问。


四、Pattern 3:$input.item——当前条目(Each Item 模式专用)

使用场景:

  • 节点模式设置为 "Run Once for Each Item"
  • 需要独立处理每个条目
  • 逐条目 API 调用或校验
  • 条目级错误处理

重要约束:$input.item 仅在 "Run Once for Each Item" 模式下可用。在 "Run Once for All Items" 模式下它是 undefined,直接访问 .json 会抛错。

4.1 基本用法

// 在 "Run Once for Each Item" 模式下
const currentItem = $input.item;
const data = currentItem.json;

console.log('Processing item:', data.id);

return [{
  json: {
    ...data,
    processed: true
  }
}];

4.2 示例 1:添加处理元数据

const item = $input.item;

return [{
  json: {
    ...item.json,
    processed: true,
    processedAt: new Date().toISOString(),
    processingDuration: Math.random() * 1000  // 模拟耗时
  }
}];

4.3 示例 2:逐条目校验

const item = $input.item;
const data = item.json;

// 校验当前条目
const errors = [];

if (!data.email) errors.push('Email required');
if (!data.name) errors.push('Name required');
if (data.age && data.age < 18) errors.push('Must be 18+');

return [{
  json: {
    ...data,
    valid: errors.length === 0,
    errors: errors.length > 0 ? errors : undefined
  }
}];

4.4 示例 3:条目级 API 调用(含沙箱重要警告)

const item = $input.item;
const userId = item.json.userId;

// 针对该条目发起 API 调用
const response = await this.helpers.httpRequest({
  method: 'GET',
  url: `https://api.example.com/users/${userId}/details`
});

return [{
  json: {
    ...item.json,
    details: response
  }
}];

⚠️ 必须使用 this.helpers.httpRequest,而不是 $helpers。 自 n8n v2.0 起,Code node 默认运行在 task-runner 沙箱中,裸的 $helpers 全局变量是 undefined——$helpers.httpRequest() 会抛出 ReferenceError: $helpers is not defined(该细节在 DATA_ACCESS.md 与 BUILTIN_FUNCTIONS.md 中均被明确标注为"accessor gotcha")。

⚠️ 带认证的 API 不要沿用此模式。 this.helpers.httpRequestWithAuthentication 在 task-runner 沙箱中是被编译进 deny-list 的(会抛 UnsupportedFunctionError,详见 ERROR_PATTERNS.md Error #6)。正确的做法是:使用挂载了凭证的 HTTP Request 节点,或委托给一个由 HTTP Request 节点持有凭证的子工作流。对于任何超出"简单无认证 GET"的调用,优先使用 HTTP Request 节点而非 Code node。

4.5 示例 4:条件处理

const item = $input.item;
const data = item.json;

// 按条目类型处理
if (data.type === 'premium') {
  return [{
    json: {
      ...data,
      discount: 0.20,
      tier: 'premium'
    }
  }];
} else {
  return [{
    json: {
      ...data,
      discount: 0.05,
      tier: 'standard'
    }
  }];
}

五、Pattern 4:$node——引用指定命名节点

使用场景:

  • 需要特定命名节点的数据
  • 组合多个节点的数据
  • 访问工作流执行的元数据

5.1 基本用法

// 获取指定节点的输出
const webhookData = $node["Webhook"].json;
const apiData = $node["HTTP Request"].json;

return [{
  json: {
    fromWebhook: webhookData,
    fromAPI: apiData
  }
}];

5.2 示例 1:组合多数据源

// 引用多个节点
const webhook = $node["Webhook"].json;
const database = $node["Postgres"].json;
const api = $node["HTTP Request"].json;

return [{
  json: {
    combined: {
      webhook: webhook.body,
      dbRecords: database.length,
      apiResponse: api.status
    },
    processedAt: new Date().toISOString()
  }
}];

5.3 示例 2:跨节点对比

const oldData = $node["Get Old Data"].json;
const newData = $node["Get New Data"].json;

// 对比差异
const changes = {
  added: newData.filter(n => !oldData.find(o => o.id === n.id)),
  removed: oldData.filter(o => !newData.find(n => n.id === o.id)),
  modified: newData.filter(n => {
    const old = oldData.find(o => o.id === n.id);
    return old && JSON.stringify(old) !== JSON.stringify(n);
  })
};

return [{
  json: {
    changes,
    summary: {
      added: changes.added.length,
      removed: changes.removed.length,
      modified: changes.modified.length
    }
  }
}];

5.4 示例 3:访问分支节点数据

// 从特定执行路径获取数据
const ifTrueBranch = $node["IF True"].json;
const ifFalseBranch = $node["IF False"].json;

// 使用实际执行的分支
const result = ifTrueBranch || ifFalseBranch || {};

return [{json: result}];

关于 $node 与 $('NodeName') 的语法陷阱:仓库在 SKILL.md 的"Data Access Patterns"和 DATA_ACCESS.md 的"Production Gotchas"中特别强调:$('NodeName').json 是错误的写法——$('NodeName') 返回的是一个条目引用对象,必须调用 .first().json 或 .all() 后才能取到数据:

// ❌ 错误 - 直接对节点引用取 .json
const data = $('HTTP Request').json;

// ✅ 正确 - 先调用 .first() 再取 .json
const data = $('HTTP Request').first().json;

// ✅ 同样正确 - 取全部条目
const allData = $('HTTP Request').all();

另外,访问可选节点时配合可选链是安全的:$node["Accumulator"]?.json.accumulated || [](见下节高级模式)。


六、关键警示:Webhook 数据结构(最常见的错误)

最常见错误:忘记 webhook 的所有入站数据都被嵌套在 .body 属性下。这令大量开发者措手不及,也是仓库评估体系中优先级最高的用例(见 eval-001-webhook-body-gotcha.json)。

6.1 结构剖析

// Webhook 节点的输出结构:
{
  "headers": {
    "content-type": "application/json",
    "user-agent": "...",
    // ... 其他请求头
  },
  "params": {},
  "query": {},
  "body": {
    // ← 你的数据在这里
    "name": "Alice",
    "email": "alice@example.com",
    "message": "Hello!"
  }
}

6.2 错误写法 vs 正确写法

// ❌ 错误:直接访问(得到 undefined)
const name = $json.name;  // undefined
const email = $json.email;  // undefined

// ✅ 正确:通过 .body 访问
const name = $json.body.name;  // "Alice"
const email = $json.body.email;  // "alice@example.com"

// ✅ 正确:先提取 body 再访问
const webhookData = $json.body;
const name = webhookData.name;  // "Alice"
const email = webhookData.email;  // "alice@example.com"

6.3 完整 Webhook 处理示例

// 获取上游节点的 webhook 输出
const webhookOutput = $input.first().json;

// 访问实际负载
const payload = webhookOutput.body;

// 按需访问请求头
const contentType = webhookOutput.headers['content-type'];

// 按需访问查询参数
const apiKey = webhookOutput.query.api_key;

// 处理实际数据
return [{
  json: {
    // 来自 webhook body 的数据
    userName: payload.name,
    userEmail: payload.email,
    message: payload.message,

    // 元数据
    receivedAt: new Date().toISOString(),
    contentType: contentType,
    authenticated: !!apiKey
  }
}];

6.4 POST 数据、查询参数与请求头

const webhook = $input.first().json;

return [{
  json: {
    // POST body 数据
    formData: webhook.body,

    // 查询参数(?key=value)
    queryParams: webhook.query,

    // HTTP 请求头
    userAgent: webhook.headers['user-agent'],
    contentType: webhook.headers['content-type'],

    // 请求元数据
    method: webhook.method,  // POST、GET 等
    url: webhook.url
  }
}];

6.5 常见 Webhook 场景速查

// 场景 1:表单提交
const formData = $json.body;
const name = formData.name;
const email = formData.email;

// 场景 2:JSON API webhook
const apiPayload = $json.body;
const eventType = apiPayload.event;
const data = apiPayload.data;

// 场景 3:查询参数
const apiKey = $json.query.api_key;
const userId = $json.query.user_id;

// 场景 4:请求头
const authorization = $json.headers['authorization'];
const signature = $json.headers['x-signature'];

安全访问建议:webhook 数据层级较深,访问前建议逐层兜底或使用可选链,例如 $json.body?.user?.name || 'Unknown'(详见 ERROR_PATTERNS.md Error #5 的"Webhook Data Safety"小节)。


七、如何选择正确的访问模式

7.1 决策树

需要上游节点的所有条目吗?
├─ 是 → 使用 $input.all()
│
└─ 否 → 只需要第一个条目吗?
    ├─ 是 → 使用 $input.first()
    │
    └─ 否 → 当前处于 "Each Item" 模式吗?
        ├─ 是 → 使用 $input.item
        │
        └─ 否 → 需要指定节点的数据吗?
            ├─ 是 → 使用 $node["NodeName"]
            └─ 否 → 使用 $input.first()(默认)

7.2 快速参考表

场景 使用方式 示例
汇总所有金额 $input.all() allItems.reduce((sum, i) => sum + i.json.amount, 0)
获取 API 响应 $input.first() $input.first().json.data
独立处理每条数据 $input.item $input.item.json(Each Item 模式)
组合两个节点 $node["Name"] $node["API"].json
过滤数组 $input.all() allItems.filter(i => i.json.active)
转换单个对象 $input.first() {...input.first().json, new: true}
Webhook 数据 $input.first() $input.first().json.body

八、常见错误与规避(含返回格式要点)

8.1 Mistake 1:脱离上下文使用 $json

// ❌ 错误:$json 语义不明确
const value = $json.field;

// ✅ 正确:显式表达
const value = $input.first().json.field;

8.2 Mistake 2:忘记 .json 属性

// ❌ 错误:直接访问条目对象的字段(得到 undefined)
const items = $input.all();
const names = items.map(item => item.name);  // undefined

// ✅ 正确:通过 .json 访问
const names = items.map(item => item.json.name);

8.3 Mistake 3:在 All Items 模式下使用 $input.item

// ❌ 错误:$input.item 在 "All Items" 模式下是 undefined
const data = $input.item.json;  // Error!

// ✅ 正确:使用合适的方法
const data = $input.first().json;  // 或 $input.all()

8.4 Mistake 4:未处理空数组

// ❌ 错误:无条目时直接崩溃
const first = $input.all()[0].json;

// ✅ 正确:先检查长度
const items = $input.all();
if (items.length === 0) {
  return [];
}
const first = items[0].json;

// ✅ 同样正确:使用 $input.first()(内置空值保护)
const first = $input.first().json;

8.5 Mistake 5:修改原始数据

// ❌ 有风险:就地修改原始数据
const items = $input.all();
items[0].json.modified = true;  // 修改了原始对象
return items;

// ✅ 安全:创建新对象
const items = $input.all();
return items.map(item => ({
  json: {
    ...item.json,
    modified: true
  }
}));

8.6 返回格式(与数据访问密切相关的强制约束)

无论采用哪种数据访问方式,返回值都遵循同一契约。推荐规范形式是 [{json: {...}}]——由带 json 属性的对象组成的数组,它在两种执行模式下行为完全一致:

// ✅ 单条结果
return [{json: {field1: value1, field2: value2}}];

// ✅ 多条结果
return [
  {json: {id: 1, data: 'first'}},
  {json: {id: 2, data: 'second'}}
];

// ✅ 空结果(无数据可返回时)
return [];

关于宽松写法的真实行为(来自 ERROR_PATTERNS.md Error #3 的澄清):在 "Run Once for All Items" 模式下,n8n 会把单个裸对象或裸对象数组自动包一层 json,所以 return {json: {result: 'success'}} 也能运行;真正会失败的是返回原始值(字符串 / 数字 / 布尔)或 null / undefined——它们没有任何可包装的东西,运行时抛出 "Code doesn't return items properly"。这一点与 eval-002-return-format-error.json 的期望行为一致:务必用方括号包裹对象数组,多个条目同理。为稳妥起见,任何分支路径都应返回 [{json: {...}}] 或 []。


九、高级模式

9.1 分页处理

const currentPage = $input.all();
const pageNumber = $node["Set Page"].json.page || 1;

// 与历史页合并
const allPreviousPages = $node["Accumulator"]?.json.accumulated || [];

return [{
  json: {
    accumulated: [...allPreviousPages, ...currentPage],
    currentPage: pageNumber,
    totalItems: allPreviousPages.length + currentPage.length
  }
}];

9.2 条件节点引用

// 按条件访问不同节点
const condition = $input.first().json.type;

let data;
if (condition === 'api') {
  data = $node["API Response"].json;
} else if (condition === 'database') {
  data = $node["Database"].json;
} else {
  data = $node["Default"].json;
}

return [{json: data}];

9.3 多节点聚合

// 从多个命名节点收集数据
const sources = ['Source1', 'Source2', 'Source3'];
const allData = [];

for (const source of sources) {
  const nodeData = $node[source]?.json;
  if (nodeData) {
    allData.push({
      source,
      data: nodeData
    });
  }
}

return allData.map(item => ({json: item}));

十、模式性能:为什么 "Run Once for All Items" 更快

执行模式的选择是 Code node 中最大的单个性能杠杆,该结论对工作流其余部分同样适用。每次 n8n 将条目交给"逐条目执行上下文"(per-item execution context)都要付出一次环境搭建成本。仓库在 DATA_ACCESS.md 的"Mode Performance"章节给出了在 n8n 2.x 实例上、小记录 ~10k 条目的实测量级:

每条目执行的内容 近似成本 原因
Code All Items(整个数据集只运行一次) ~0.02 ms/条目 只搭建一次上下文,然后跑纯 JS——循环是免费的
任意节点中的表达式(IF / Set 等) ~0.2 ms/条目 每个条目一个轻量 eval 上下文
Code Each Item ~0.6 ms/条目 每个条目一个完整的代码沙箱——约为表达式的 3 倍、All Items 的 25~30 倍

换算下来:10k 条目使用 "Run Once for Each Item" 约有 6 秒纯开销,而同样的逻辑放在 "Run Once for All Items" 只需约 0.2 秒。因此只有在条目确实需要隔离时才使用 Each Item(例如独立的错误处理、无法批处理的逐条 API 调用);否则应在单个 All Items 节点内部循环。

两个随时会遇到的推论:

  • 表达式复杂度几乎免费。 一个复杂的 {{ }} 表达式与一个简单的测得相同成本——约 90% 的开销来自 n8n 为每个条目构建上下文,而不是运行你的代码。不要为了速度简化表达式,而应减少逐条目边界的数量。
  • 每次节点到节点的跳转都会重新复制所有条目(每次跳转约 ~0.05 ms/条目)。六个串联的 All Items Code 节点,成本约为在单个节点中完成同样六步的 7 倍——所以应把热点转换链合并进一个 All Items 节点,绝不要构建由 Each Item Code 节点组成的链条(6 节点 Each Item 链处理 2k 条目 ≈ 7 秒)。

规模检查:几百条目以下,所有这些开销都低于 100ms,不值得考虑;大多数真实工作流由 I/O(HTTP / DB / Sheets 往返)主导,远大于节点开销。只有在热路径(条目量大、I/O 少)上才需要应用上述规则。

该性能分析在 SKILL.md 的"Mode Selection Guide"中有摘要版(含同一张成本表),并注明完整推论(跳转成本、规模检查)参见 DATA_ACCESS.md。


十一、生产注意事项(Production Gotchas)

以下是从真实 n8n 工作流部署中总结的经验教训,对应 DATA_ACCESS.md 的"Production Gotchas"章节。

11.1 SplitInBatches 循环语义

SplitInBatches 节点有两个输出,命名具有反直觉性:

  • main[0] = done——所有批次处理完后只触发一次
  • main[1] = each batch——每个批次触发一次(这才是循环体)

建议始终在 done 输出之后、下游处理之前添加一个 Limit 1 节点,作为 done 在边缘情况下可能携带多余条目的安全兜底。

11.2 SplitInBatches:迭代次数即成本

每次循环迭代都会让整个循环体重新经过工作流引擎——每迭代约 ~0.8 ms 纯开销,外加循环体本身的工作。总成本 ≈ ⌈items / batchSize⌉ × (~0.8 ms + body cost):

  • batchSize: 1 处理 N 条数据要付出 N 次成本——这就是"循环版的 Run Once for Each Item"(若循环体有多个节点,每次迭代都要为它们全部重新付费)。
  • 提高 batchSize 会按比例削减迭代次数,而循环体仍然能看到每条数据。使用你的真实约束(API 限流、页面大小、内存)允许的最大批次。如果根本不需要批处理,就不要循环——在一个 All Items 节点中处理整个数据集。

11.3 跨迭代数据累积(关键)

SplitInBatches 循环结束后,$('Node Inside Loop').all() 只返回最后一次迭代的条目,而不是累计结果。这会静默丢弃除最后一批以外的所有数据。

修复方案:使用工作流静态数据跨迭代累积:

// 循环开始前(重置累加器):
const staticData = $getWorkflowStaticData('global');
staticData.results = [];
return $input.all();

// 循环体内部(累积):
const staticData = $getWorkflowStaticData('global');
const results = [];
for (const item of $input.all()) {
  const processed = { /* ... */ };
  results.push({ json: processed });
  staticData.results.push(processed);
}
return results;

// 循环结束后(读取累积数据):
const staticData = $getWorkflowStaticData('global');
const allResults = staticData.results || [];
// 现在可以跨所有迭代聚合了

11.4 新输出条目的 pairedItem

当生成的新条目与输入条目不构成 1:1 映射时,必须带上 pairedItem——否则下游 Set 节点会报 paired_item_no_info:

const results = [];
for (let i = 0; i < $input.all().length; i++) {
  const item = $input.all()[i];
  results.push({
    json: { /* 新数据 */ },
    pairedItem: { item: i }
  });
}
return results;

11.5 正确的节点引用语法

// ❌ 错误 - 直接在节点引用上取 .json
const data = $('HTTP Request').json;

// ✅ 正确 - 先调用 .first() 再取 .json
const data = $('HTTP Request').first().json;

// ✅ 同样正确 - 获取全部条目
const allData = $('HTTP Request').all();

11.6 价格 / 货币比较的浮点精度

比较价格或货币时,浮点噪声会造成误报。应四舍五入到"分"再比较:

// ❌ 不可靠 - 浮点比较
if (newPrice !== oldPrice) { /* 会被噪声触发 */ }

// ✅ 可靠 - 在分级别比较
if (Math.round(newPrice * 100) !== Math.round(oldPrice * 100)) {
  // 检测到真实的价格变化
}

十二、总结与速查

最常用的三种模式:

  1. $input.all()——处理多条数据、批量操作
  2. $input.first()——单条数据、API 响应
  3. $input.item——Each Item 模式下的逐条处理

关键规则:

  • Webhook 数据位于 .body 属性下

最佳实践:

  • 显式表达:用 $input.first().json.field 而不是 $json.field
  • 始终检查 null / undefined(可选链 ?. + 默认值)
  • 根据模式选择合适方法(All Items vs Each Item)
  • 返回规范形式 [{json: {...}}],绝不返回原始值或 null
  • 循环内聚合用 $getWorkflowStaticData('global') 跨迭代累积

延伸阅读(仓库内文件)

注意事项:本文涉及的性能数值(~0.02 / 0.2 / 0.6 ms 每条目等)来自仓库在 n8n 2.x 实例上的实测量级,仅作选型参考,实际数值会随硬件、条目结构与沙箱版本浮动;关键的结论(All Items 明显快于 Each Item、表达式复杂度免费、节点跳转复制条目)是稳定的架构性事实。涉及 n8n 版本与沙箱行为(v2.0 起 task-runner、deny-list)的表述以当前仓库文档为准。

登录后查看全文
n8n-skills