很多真實工作負載要的不是一頁，而是一整站：文件站、產品目錄、部落格歸檔——當目標是把數千頁變成乾淨 Markdown 餵給訓練集或知識庫時，/v2/crawl 就是用武之地：給一個起始 URL，它回傳每個值得保留頁面的 Markdown。官方教學把它講得完整，本文濃縮成參數、交付模式與計費三個實戰維度。
先釐清兩個常被混用的詞。Web scraping 是從已知 URL 的單頁抽取內容；web crawling 是沿連結走訪、邊走邊發現頁面，重點在導覽與 URL 發現。做一個回答 Stripe 文件問題的 chatbot，兩者都要：crawling 發現並走遍文件站的所有頁面，scraping 從每個發現的頁面抽出內容。Firecrawl 的 crawl 把兩件事合成一個 job：URL 分析（sitemap 或頁面遍歷）→ 遞迴走訪 → 逐頁抽取 → 結構化回傳。可以用 REST API、Python/Node（另有 Go、Rust）SDK、MCP server 或 CLI 呼叫。
同步入門：一行爬一個站
以練習站 books.toscrape.com 為例，Python SDK 兩行就能跑：crawl(url=base_url, limit=20)。回傳的 result 帶 status、total、credits_used、completed 與 data 清單——每個元素含該頁 Markdown 與 metadata（title、description、url、language、robots 等）。傳統用 beautifulsoup4 或 lxml 要寫幾十行解析與分頁邏輯，這裡一行完成；官方實測抓 3 頁約 8 秒（依網路與目標站而異）。同步 crawl() 適合小工作直接等結果。
核心參數：limit、路徑過濾與 sitemap 模式
limit：抓取頁數上限。沒有它，crawler 可能沿著無盡連結鏈一直走、邊走邊燒 credits；大站或開啟外部連結時尤其關鍵。它同時直接決定帳單。include_paths/exclude_paths：用路徑模式圈定範圍——只爬/docs/下的頁面、排除/blog/，比事後過濾省 credits 也省時間。crawl_entire_domain：跨子網域爬整個 domain，適合結構分散的大型站。sitemap：改用 sitemap 模式做 URL 發現，比連結遍歷更快更完整，特別適合文件站。scrape_options：往下傳給每頁 scrape 的選項（格式、等待條件等），讓 crawl 與 scrape 的行為在一次 job 裡統一。
參數組合的思路是「先窄後寬」：先用 limit + include_paths 圈一小塊驗證輸出，確認格式與品質後再放寬範圍，避免大站直接開全網域爬到爆 credits。
大工作負載：三種非同步交付模式
同步等待在大 job 上不實際。start_crawl() 啟動非同步 job 後，三種取回方式各有場景：用 get_crawl_status() 輪詢，實作最簡單、適合腳本批次；用 watcher() 走 WebSocket 串流，頁面爬完即到，適合邊爬邊處理的管線；或讓 Firecrawl 推送 webhook 事件，適合把結果接進既有事件架構。選擇取決於你的下游：批次入庫用輪詢就夠，即時索引或進度回報用串流，企業級 pipeline 用 webhook。另一個值得留下的操作細節：status、total、completed、credits_used 這些欄位在同步與非同步介面都有，成本遙測不因模式而異——大 job 串流的當下就能看著 credits_used 累加，不會等到結束才發現爆預算。
計費公式：把成本寫進參數設計
計費規則很乾淨：每爬一頁 1 credit；JSON 抽取每頁加 4 credits；PDF 解析每個 PDF 頁加 1 credit。換句話說，總成本 ≈ 頁數 ×（1 + 選配加價）。這讓 limit 不只是防呆參數，而是成本控制的一等公民：先估算目標站的頁數量級（map 端點可以先只列 URL 不抓內容），再決定 limit 與是否開 JSON 抽取。全站幾千頁的站開 JSON 抽取，帳單是純 Markdown 的五倍——這個數字該在按下執行前就算好。
接進 RAG：與 LangChain 的直通管道
教學的最後一段示範把 crawl 結果直接餵進 LangChain 的文件載入器——Markdown 進、切塊、嵌入、入向量庫，一條管線到底。對 builder 的落地建議：用 include_paths 把爬取範圍對齊知識庫的主題邊界（爬整個站常常混入大量與問答無關的頁面）；用 metadata（url、language）保留溯源資訊，讓檢索結果能連回原文；增量更新時用 sitemap 模式比對新舊 URL 清單，只重爬變動頁，把週期性更新的成本壓在變動量而非全站。
參考來源
本文由 AI 協助自上述來源整理，經人工審核後發布。