n8n Code Node 数据访问模式完全指南:JavaScript 中的 `$input`、`$node` 与 Webhook 数据结构
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)) {
// 检测到真实的价格变化
}
十二、总结与速查
最常用的三种模式:
$input.all()——处理多条数据、批量操作$input.first()——单条数据、API 响应$input.item——Each Item 模式下的逐条处理
关键规则:
- Webhook 数据位于
.body属性下
最佳实践:
- 显式表达:用
$input.first().json.field而不是$json.field - 始终检查 null / undefined(可选链
?.+ 默认值) - 根据模式选择合适方法(All Items vs Each Item)
- 返回规范形式
[{json: {...}}],绝不返回原始值或null - 循环内聚合用
$getWorkflowStaticData('global')跨迭代累积
延伸阅读(仓库内文件)
- SKILL.md——Code node 概述、模式选择指南与快速入门
- COMMON_PATTERNS.md——10 个经过生产验证的模式(多源聚合、正则过滤、Markdown 解析、JSON 对比、CRM 转换、发布处理、数组转换、Slack Block Kit、Top N 排名、字符串聚合报告)及最佳实践
- ERROR_PATTERNS.md——7 大错误模式、预防清单与快速错误参考表
- BUILTIN_FUNCTIONS.md——
this.helpers.httpRequest()完整参数、DateTime(Luxon)、$jmespath()、$getWorkflowStaticData()与沙箱限制参考 - README.md——skill 元数据、覆盖范围与文件结构
- 评估用例:eval-001-webhook-body-gotcha.json、eval-002-return-format-error.json、eval-004-aggregation-pattern.json
注意事项:本文涉及的性能数值(~0.02 / 0.2 / 0.6 ms 每条目等)来自仓库在 n8n 2.x 实例上的实测量级,仅作选型参考,实际数值会随硬件、条目结构与沙箱版本浮动;关键的结论(All Items 明显快于 Each Item、表达式复杂度免费、节点跳转复制条目)是稳定的架构性事实。涉及 n8n 版本与沙箱行为(v2.0 起 task-runner、deny-list)的表述以当前仓库文档为准。