API 分页：那个让你抓狂的“下一页”按钮
在 n8n 的世界里，笔者见过太多新手朋友在抓取 API 数据时，满怀信心地运行工作流，结果只拿到了前 20 条数据。明明 API 文档里写着有 1000 条，剩下的去哪儿了？
这就是 API 分页（Pagination）在作祟。很多 API 为了防止服务器被瞬间压垮，或者为了让你在前端显示更流畅，不会一次性把所有数据塞给你，而是像切香肠一样，一片一片地给。如果你不懂它的规律，你就永远只能在门口徘徊，拿不到完整的数据。
今天，N8N大学 就带你硬核拆解 API 分页，咱们不整虚的，直接上干货，教你如何在 n8n 里搞定这烦人的“下一页”，把数据一网打尽。
第一步：摸清 API 的“脾气”
在冲进 n8n 里连线之前，笔者必须提醒你：先读文档！每个 API 的分页逻辑都不一样，通常分为以下几种“流派”：
- 页码流 (Page-based)：最常见的。比如你请求
?page=1，返回第一页；?page=2，返回第二页。直到返回空数组为止。 - 游标流 (Cursor-based)：高性能 API 的首选（如 GitHub, Stripe）。它返回一个特殊的
next_token或cursor，你需要拿着这个“信物”去请求下一页。 - 偏移量流 (Offset-based)：类似页码，但用的是起始位置。比如
?offset=0, limit=100，然后?offset=100, limit=100。
搞清楚你的目标 API 属于哪一派，我们才能在 n8n 里对症下药。
核心实操：利用 n8n 的“分裂与聚合”魔法
n8n 处理分页的神器是 Split In Batches 节点。它的逻辑非常符合人类直觉：循环执行，直到数据跑完。
1. 搭建基础循环结构
在你的工作流中，你需要以下几个核心节点来构建一个完整的分页抓取循环：
- Start: 流程的起点，通常不需要特殊设置。
- Set (初始化计数器): 我们需要一个变量来控制页码。在 Set 节点里，新建一个字段，比如
page，值设为1。 - HTTP Request: 这是发起 API 请求的节点。在 URL 中，你需要动态引用页码。例如：`https://api.example.com/data?page={{ $json.page }}`。
- Split In Batches: 这是核心。它会接收上一步的数据，把它们分批处理。
2. 配置 Split In Batches 的关键参数
把 Split In Batches 节点拖入画布，连接在 HTTP Request 之后。这里有两个关键点：
- Batch Size (批大小): 这个参数其实不重要，通常设为 1 即可，因为我们是一次性处理一整页的数据。
- Wait For All Batches (等待所有批次): 千万不要勾选！ 如果勾选，n8n 会等所有请求都发完再往下走，这通常会导致逻辑错误或内存爆炸。我们要的是“请求一次，处理一次，再请求下一次”。
3. 完成闭环与停止条件
从 Split In Batches 出来，连回我们的 Set 节点（或者新建一个 Set 节点来增加页码）。在 Set 节点里，设置 page 为 {{ $json.page + 1 }}。
然后，从这个 Set 节点连回 Split In Batches 的左侧入口（注意：不要连回 HTTP Request，否则会跳过 Split In Batches 的判断逻辑）。
停止循环的机制： 当 API 返回的数据为空数组（[]）时，Split In Batches 就会自动停止循环，工作流继续向下执行。这正是我们要的！
进阶避坑：处理“游标”与“防死循环”
上面的流程能搞定 80% 的情况，但还有硬骨头。
应对 Cursor（游标）分页
如果 API 返回的是 next_cursor，逻辑稍有不同：
- 第一次请求时，URL 里可能没有 cursor 参数。
- 请求回来后，用 Set 节点提取响应里的
next_cursor。 - 下一次循环时，HTTP Request 的 URL 需要带上这个 cursor：
https://api.example.com/data?cursor={{ $json.next_cursor }}。
如果响应里没有 next_cursor 字段，或者该字段为空，Split In Batches 同样会停止循环。
防止无限循环的保险丝
如果你的 API 配置错误，或者数据异常，Split In Batches 可能会一直跑下去，直到 n8n 超时或内存耗尽。笔者建议你在循环里加一个“保险”。
在 Split In Batches 之前，加一个 IF 节点。判断条件是：page 是否小于 100（或者你预估的最大页数）。如果超过了，就直接结束流程，防止跑一整晚的“死循环”。
常见报错与解决方案
注意： API 分页最头疼的往往不是技术实现，而是限流（Rate Limiting）。
当你跑完一轮，发现中间有几页报错 429 Too Many Requests。这是因为你请求太快了。
解决方案：
- Wait 节点：在 Split In Batches 的循环回路中，或者在 HTTP Request 之后，加一个 Wait 节点。设置暂停 500ms 到 1秒。给 API 喘口气的时间。
- HTTP Request 的 Retry 设置：n8n 的 HTTP Request 节点自带重试机制。在 Settings 里开启 Retry On Fail，并设置重试次数（如 3 次），这能解决大部分网络抖动或临时限流问题。
FAQ 问答
1. 为什么我的工作流跑了一半就停了？
通常是因为 HTTP Request 返回了错误（如 401 认证失败），或者 API 返回的数据结构不符合预期，导致 Split In Batches 无法正确解析数据流。请检查 HTTP Request 的响应状态码和返回内容。
2. API 每次只给 10 条数据，但我需要 1000 条，岂不是要发 100 次请求？
是的，这就是分页的本质。但 n8n 处理这种循环效率很高。只要你不是每秒请求几十次（会被封 IP），通常几十次请求在几分钟内就能跑完。如果 API 支持，尽量在 URL 参数里加上 limit=100 之类的参数，减少请求次数。
3. 如何把所有分页的数据合并成一个数组输出？
n8n 默认会把每次循环的数据“透传”。如果你需要在流程最后把所有数据汇总成一个大数组，可以在流程的末端使用 Aggregate 节点，或者使用 Set 节点配合表达式收集数据。但在大多数场景下，直接把数据流导出到数据库或 Google Sheet 会更高效，不需要手动合并。
总结与资源
处理 API 分页是自动化工程师的基本功。核心就是利用 Split In Batches 构建循环，利用 Set 节点维护状态（页码或游标），并时刻警惕 API 的限流策略。
掌握了这个技巧，互联网上 90% 的 API 数据都任你差遣。N8N大学 建议你立刻找一个支持分页的公开 API（比如 GitHub API），动手复现一遍上述流程，只有亲手敲出来的代码，才是你真正的技能。
