n8n 中处理多条目数据、分页…

在 n8n 工作流中处理多条目数据、分页 API、限流、批处理或需要「对每一项执行」时，判断该用默认迭代、executeOnce、Loop Over Items 还是 HTTP 分页。

适用场景

解决思路

1. 先理解模型：数据在节点间以条目数组流动，每个条目形如 { json: {...}, binary?: {...} }，50 个条目就是 50 项数组；默认情况下节点对每个条目运行一次，输入数组就是循环本身，通过控制数组来控制迭代。
2. 区分「循环」的三种含义并对应三种机制：1) 对每个条目运行该节点——默认行为，大多数节点自动循环，无需操作；2) 用所有条目只运行一次该节点——使用 executeOnce 设置（单个布尔值）；3) 以显式批次处理并在迭代间控制流程——使用 Loop Over Items 节点（原 Split In Batches）。
3. 当节点应当每次运行只触发一次而非每条目一次时，设置 executeOnce: true，包括：通过 $input.all() / $('Node').all() 配合 .map() / .filter() / .reduce() 跨数据集聚合的表达式、单次通知、聚合写入、汇总消息。
4. 反例：.all() 与另一节点的 .item 结合做逐条目查找（例如 $('Get Tags').all().filter(tag => $('Search Posts').item.json.tag_ids.includes(tag.json.id))）属于真正的逐条目工作，应保持 executeOnce 关闭。
5. 不要在本该用默认迭代时构建循环：大多数节点（HTTP Request、原生服务节点、Set、IF/Switch）会自动对每个输入条目运行一次，N 个条目进就 N 次运行；要让 N 次 HTTP 调用或创建 N 条记录，直接把源连到节点即可，除非需要逐迭代控制，否则不要用 Loop Over Items。注意 Execute Workflow 是例外，它默认单批处理所有条目，逐条目调用需在该节点上设 mode: 'each'。
6. 对于分页 API，使用 HTTP Request 内置的分页功能，不要用 Loop Over Items + 手动 $pageCount 重新发明，除非 API 确实特殊。
7. Loop Over Items 用于显式批处理或逐迭代控制（限流、逐批错误恢复、有状态分块、轮询）。
8. 注意逐条目迭代是顺序的而非并行的：即使分支看起来并行，每个条目也会在下一个开始前完成；真正的并发模式需参考子工作流方案。
9. 按决策树选择机制：默认逐条目迭代够用就直接连接节点；节点应总共运行一次而非每条目一次就设 executeOnce: true；分页 API 用 HTTP Request 的 Pagination 选项；需要显式批处理（限流、块大小、逐批错误处理）用 Loop Over Items 节点；需要带状态递归/重复直到满足条件则用带 Reset 的 Loop Over Items 或自调用子工作流。
10. executeOnce 的设置方式：每个节点的 Settings 标签有 Execute Once 开关，开启后节点只用第一个输入条目运行一次；在 SDK 代码中设 executeOnce: true；在已有工作流上通过 update_workflow 的 setNodeSettings 应用（n8n 2.24.0+）。
11. executeOnce 适用场景：通知与聚合写入（汇总消息不应因 100 个条目触发 100 次）、计数器/总计/报告（任何计算 $input.all().length 等的都应只运行一次）、通过 $input.all() / $('Node').all() 跨整个数组聚合的表达式（否则聚合会按上游条目数运行多次）。
12. executeOnce 不适用场景：逐条目操作（每个条目一条通知是默认且通常正确的）、逐条目扇出的 HTTP 请求（你希望每个条目一次调用）。
13. 避免常见错误：在扇出后忘记给聚合节点设 executeOnce，导致同一条消息触发 50 次。
14. 识别隐式循环的坑：扇出后的 Set 节点会逐条目运行产生 N 份相同常量（把 Set 移到扇出之前或设 executeOnce: true）；读取 $input.all() 计算求和的 Code 节点未设 executeOnce 会逐条目运行产生 N 个相同条目（设 executeOnce: true）；Respond-to-Webhook 逐条目触发且两条分支汇合未合并会响应两次（先合并或确保只有一条分支到达响应器）；带 $input.all() 的 LLM 节点未设 executeOnce 会做 N 次相同调用、花 N 倍 token（设 executeOnce: true）。
15. 使用 Loop Over Items 的场景：限流（一次处理 10 个，批次间等待 1 秒）、带数组体的批量 API 调用（向 /bulk 发送 50 项块）、逐批错误处理（某批失败则记录并继续）、有状态迭代（每次迭代依赖上一次输出）、轮询长时间运行的任务（启动后每 30 秒检查状态直到完成或达到上限，用 reset: true 加 $runIndex 上限）、逐条目多分支并聚合（对每个输入并行运行转换、合并、再聚合，done 输出即索引 0 携带结果）。
16. 不要因为「需要等所有条目完成再进入下一步」而使用 Loop Over Items：默认逐条目迭代已经会等待，每个条目会先流经完整下游链再开始下一个，循环后节点不会提前触发；这种错误几乎总是通过删除 Loop Over Items 节点、其他不变、直接发布来解决。
17. 按四个独立场景决策：场景 1（默认逐条目迭代，最常见）——源发出 N 个条目，逐条目处理器运行 N 次，下游链跟随，不用 Loop Over Items、不用 executeOnce、不用 Aggregate，直接连接节点；若此处加了 Loop Over Items + done「为了等待所有条目」或「让下一节点对每个条目运行」，删除 Loop Over Items 并把源直连处理器，不要用任何东西替代。
18. 场景 2（下游节点应总共只触发一次）——仅当存在特定下游节点其职责是每次运行一次时触发（如 20 篇论文处理后发一封摘要邮件、循环后写一次汇总、最后发一条 Slack 通知），在该节点上设 executeOnce: true，它接收所有上游条目但只运行一次；这是逐节点设置，不是 Loop 替代，场景 1 的逐条目处理器仍运行 N 次。
19. 场景 3（节点需要条目作为单个数组）——仅当下游节点的输入契约是列表而非逐条目调用时触发（如接收 JSON 数组体的节点、需要整个列表的 LLM 提示），用 Aggregate 节点把逐条目流折叠成一个包含数组的条目；同样不是 Loop 替代。
20. 场景 4（真正的批处理，Loop Over Items 唯一该用的地方）——限流（一次处理 N 个、批次间 Wait）、分块批量 API 调用（向 /bulk POST 50 项数组）、逐批错误处理、用 reset: true 加 $runIndex 上限轮询长任务、每批依赖上一批输出的有状态迭代；「等待条目完成」不算。
21. 快速消歧：如果使用 Loop 的唯一理由是「等待条目/对每个条目运行」，你处于场景 1，删除 Loop，不要用 executeOnce 或 Aggregate 替代，它们解决不同问题，仅当各自场景适用时才添加。
22. HTTP 分页的三种常见页面形态：响应中含 next URL；页码/游标参数（每次调用递增 ?page=N 或 ?cursor=...）；遇到空页或特定状态停止。HTTP Request 通过 Pagination 选项原生处理全部三种：设置模式、给出下一页表达式，节点内部循环并返回所有页面条目的单个输出数组。
23. 对于真正的递归工作（树遍历、带退避重试、「处理此节点及其子节点」），自调用子工作流比带 Reset 的 Loop Over Items 更清晰，输入参数携带递归状态（如子工作流 Walk Tree，输入 { node_id, depth }，处理节点、查找子节点、对每个子节点以 depth+1 调用自身）；注意递归深度，n8n 有嵌套执行限制，深递归时用队列 + 扁平循环优于真正递归。
24. 避免反模式：默认迭代已能做时还加 Loop Over Items「让它循环」——工作流更难读且 loop 输出与 done 输出易接错，直接连接节点让默认迭代处理；Aggregate Code 节点未设 executeOnce——同一聚合算 N 次、输出 N 个相同条目，设 executeOnce: true；用 Loop Over Items + $pageCount 手动分页——重新发明 HTTP Request 原生功能且停止条件脆弱，用 HTTP Request 的 Pagination 选项；想要汇总却逐条目发 Slack 消息——频道被刷屏、触发限流，在 Slack 节点设 executeOnce: true 并在上游构建汇总；两条分支都到达 Respond to Webhook——响应两次、下游调用方看到错误，在响应器前合并或确保只有一条分支到达；带 Reset 的 Loop Over Items 无明确终止条件——无限循环、n8n 吃内存直到执行被杀，始终要有明确终止条件，分页 API 优先用 HTTP 分页；在同一工作流中嵌套一个 Loop Over Items 于另一个内——运行时出错但校验通过，把内层循环移到按外层迭代调用的子工作流中（mode: 'each'）。

适用边界 · 注意事项

• 不要用 Loop Over Items 来「等待所有条目完成」或「让下一节点对每个条目运行」——默认逐条目迭代已经会等待并逐条目运行，这种情况应删除 Loop 并直连节点。
• 不要用 Loop Over Items + 手动 $pageCount 重新实现分页，除非 API 的行为内置分页模式无法表达。
• 不要在同一工作流中嵌套 Loop Over Items，运行时会出现问题；应把内层循环移到子工作流中按外层迭代调用。