HubSpot万条联系人同步：一个被10K限制卡住的经典坑

做HubSpot API集成的开发者，迟早会遇到这个坎：客户 portal 里的联系人超过1万条，怎么同步？

直接调搜索接口？HubSpot 文档写得明白："搜索端点任何查询最多返回1万条结果，尝试翻页到1万条之后会报400错误。"更麻烦的是，这个接口每秒限流5次。但它是唯一支持按 lastmodifieddate 筛选的端点——增量同步全靠它。

那换列表接口？没上限，但没筛选能力。全量拉取意味着每次运行都要重新下载全部数据，客户数据量一上来就是灾难。

HubSpot 社区论坛里堆满了400错误的帖子，开发者们以为代码写崩了，其实是踩了同一个设计陷阱。

解法是把同步拆成两阶段，用 Nango checkpoint 共享状态：第一阶段用搜索接口抓最近修改的记录（增量），第二阶段用列表接口补全历史数据（全量兜底）。两阶段配合，既绕过1万条硬限制，又保证不重复拉取未变更数据。

但骨架搭好了，基础设施才是苦活：管理几百个用户的 OAuth token、存记录、接 webhook 实时更新、处理限流重试——这些没有现成方案，通常要数周开发。

Nango 把这堆脏活封装成五个积木：统一 OAuth 托管、自动 token 刷新、内置持久化、webhook 路由、限流队列。配合 Claude Code、Cursor、Codex 这类 AI Coding Agent，能把数周工作量压到几分钟。

具体实现需要 Nango 账号（免费 tier 够用），注册 HubSpot OAuth app 并开通 crm.objects.contacts.read 权限，回调地址设为 https://api.nango.dev/oauth/callback。没自己的 OAuth app 也可以先用 Nango 的预配置开发凭证跑起来，上线前再切自己的。

接着装 CLI 初始化项目：npm install -g nango，nango init，cd nango-integrations。最后装 AI Function Builder skill：npx skills add NangoHQ/skills -s building-nango-functions-locally，让 coding agent 获得写 Nango 函数的上下文。

完整 demo 含 Nango sync、Express 后端、HTML 联系人浏览面板，代码在 GitHub NangoHQ/blog-demos/how-to-sync-large-amounts-of-contacts-from-hubspot-api。这套流程同样适用于 HubSpot 公司、交易、工单，以及 Nango 支持的其他 CRM。