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。