Crawlee 是 Apify 開源的 Node.js 爬蟲框架,把「請求佇列、重試、並行調節、瀏覽器管理、資料落地」五件事包成同一套介面,換掉 parser 只要改一行。實測在 2 vCPU 主機上,純 HTTP 解析可跑到 711 req/min,同一頁換成瀏覽器渲染則降到大約 25 req/min——選錯 crawler 類型,速度差 28 倍。
大多數人寫爬蟲的起點是 requests 加 BeautifulSoup,或 fetch 加 cheerio。前 20 行很順,第 200 行開始全部是這些東西:去重、失敗重試、不要打爆對方站、瀏覽器開太多把記憶體吃光、抓到的資料存哪裡。Crawlee 就是把這 200 行變成框架層的事。
自己刻爬蟲會撞到的四件事
| 痛點 | 手刻的常見做法 | 上線後出的事 |
|---|---|---|
| 去重 | 一個 Set 記 URL | 換頁參數不同、?page=1 與 / 指向同頁 → 重複抓 |
| 重試 | try/catch 重跑一次 | 沒有退避、遇到 429 更惨;失敗原因沒有紀錄 |
| 並行 | Promise.all 一次爆 50 個 | 對方站直接封 IP,或本機記憶體被打滿 |
| 落地 | fs.writeFileSync 存 JSON | 程式中斷就全毀;無法增量、無法匯出 CSV |
Crawlee 的設計取向是:這些全部當框架內建,開發者只寫「這一頁要抓什麼」。它的官網首頁用一句話定位——可靠的爬蟲,而且要快。
專案概況(查證 2026-11-17)
| 項目 | 內容 |
|---|---|
| 倉庫 | apify/crawlee(GitHub API 查詢) |
| 星數/fork | 26,483 ★/1,773 |
| 授權 | Apache-2.0 |
| 最新版本 | crawlee@3.18.2(2026-09-29 發布) |
| npm 月下載 | 714,108 次(近 30 日) |
| 語言 | TypeScript,含完整型別與 generics |
| 建立時間 | 2016-08-26(前身是 Apify SDK 的爬蟲層) |
| Python 版 | apify/crawlee-python,9,677 ★,同為 Apache-2.0 |
有一個小矛盾值得先講:README 寫「Crawlee requires Node.js 22.13 or higher」,但 crawlee@3.18.2 與 @crawlee/core@3.18.2 的 package.json 裡 engines 是 >=16.0.0。實務上以 README 為準比較安全(本文在 Node v26.7.0 執行),npm 的 engines 欄位顯然沒有跟上文件。
七種 crawler,選錯就是白花錢
Crawlee 的 requestHandler 介面一致,差別在「用什麼方式取得頁面」:
| Crawler | 取得頁面方式 | 吃 JS 嗎 | 相對速度 | 適合 |
|---|---|---|---|---|
HttpCrawler | 純 HTTP,自己解析 | ✗ | 最快 | 打 JSON API |
CheerioCrawler | HTTP + Cheerio | ✗ | 快 | 靜態 HTML,90% 的部落格/電商列表頁 |
JSDOMCrawler | HTTP + JSDOM | 只有 DOM 模擬 | 中 | 需要 window/document 行為的頁 |
LinkedomCrawler | HTTP + linkedom | 只有 DOM 模擬 | 中快 | 想要 JSDOM 的功能但更省記憶體 |
BasicCrawler | 自己處理 | 看你自己 | — | 接非 HTML 來源(PDF、API、檔案) |
PlaywrightCrawler | 真瀏覽器 | ✓ | 慢 | 前端渲染、需要點擊/滾動 |
PuppeteerCrawler | 真瀏覽器 | ✓ | 慢 | 既有程式碼用 Puppeteer 生態 |
選型原則:先用 CheerioCrawler 寫,抓不到再換 PlaywrightCrawler。這句話不是風格建議,下面的實測數字會說明差距有多大。
安裝:兩條路
# 路徑 A:CLI 建一個完整專案(含 Dockerfile)
npx crawlee create my-crawler
cd my-crawler && npm start
# 路徑 B:加進既有專案(要瀏覽器才需要第二個套件)
npm install crawlee
npm install crawlee playwright # 用 PlaywrightCrawler 才要
Playwright 沒有被 bundle 進 Crawlee,是為了縮小安裝體積;官方 README 明確要求自己裝。若主機已有 Chrome,可以跳過 Playwright 的瀏覽器下載,直接用 executablePath 指過去——本文就是這樣跑的。
第一個爬蟲:抓書店列表與明細
測試對象是 books.toscrape.com(公開的爬蟲練習站,1,000 本書、靜態 HTML)。任務:從首頁進列表、進每本書的明細頁、抓標題/價格/星等/庫存。
import { CheerioCrawler, Dataset } from 'crawlee';
const crawler = new CheerioCrawler({
maxRequestsPerCrawl: 12,
maxConcurrency: 4,
async requestHandler({ request, $, enqueueLinks, pushData }) {
if (request.url.includes('/catalogue/')) {
await pushData({
url: request.url,
title: $('h1').first().text().trim(),
price: $('.price_color').first().text().trim(),
rating: ($('.star-rating').first().attr('class') || '').replace('star-rating', '').trim(),
stock: $('.instock.availability').first().text().trim().replace(/\s+/g, ' '),
});
}
await enqueueLinks({ selector: 'article.product_pod h3 a' });
await enqueueLinks({ selector: '.pager .next a' });
},
});
await crawler.run(['https://books.toscrape.com/']);
const data = await Dataset.getData();
console.log('items:', data.items.length);
實際執行輸出(節錄):
INFO CheerioCrawler: visited: https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html
INFO CheerioCrawler: Final request statistics:
{"requestsFinished":12,"requestsFailed":0,"retryHistogram":[12],
"requestAvgFinishedDurationMillis":126,"requestsFinishedPerMinute":711,
"requestTotalDurationMillis":1512,"crawlerRuntimeMillis":1013}
=== RESULT ===
items: 11
elapsed_ms: 1019
換算下來:12 個請求(1 個列表頁 + 11 個明細頁)在 1.02 秒內跑完,平均每個請求 126 毫秒,吞吐量 711 req/min。 這個數字是在 2 vCPU/7.9 GB RAM 的 Ubuntu 24.04 VPS 上測的,maxConcurrency: 4——並行度拉高會更快,但對方站的耐受度才是上限。
值得注意的是 retryHistogram: [12]:12 個請求全部「第一次就成功」,一次重試都沒用到。這個陣列是判斷穩定性的好工具,失敗重試的會落在後面的格子。
實測二:同一頁,Cheerio 抓 0 筆、Playwright 抓 10 筆
quotes.toscrape.com/js/ 是刻意設計成「內容由 JavaScript 產生」的頁面。先用 CheerioCrawler 打:
const crawler = new CheerioCrawler({
async requestHandler({ $, log }) {
log.info(`cheerio_quotes: ${$('.quote').length}, html_bytes: ${$.html().length}`);
},
});
await crawler.run(['https://quotes.toscrape.com/js/']);
INFO CheerioCrawler: cheerio_quotes: 0, html_bytes: 5815
INFO CheerioCrawler: requestAvgFinishedDurationMillis: 332
HTML 有拿到(5,815 bytes),但 .quote 是 0 筆——因為瀏覽器還沒執行 JS,DOM 裡只有空殼。換 PlaywrightCrawler,同一頁:
import { PlaywrightCrawler } from 'crawlee';
const crawler = new PlaywrightCrawler({
launchContext: { launchOptions: { executablePath: '/usr/bin/google-chrome' } },
async requestHandler({ page, pushData }) {
await page.waitForSelector('.quote');
const quotes = await page.$$eval('.quote', (els) =>
els.map((el) => ({
text: el.querySelector('.text')?.innerText?.trim(),
author: el.querySelector('.author')?.innerText?.trim(),
})),
);
await pushData({ count: quotes.length, first: quotes[0] });
},
});
await crawler.run(['https://quotes.toscrape.com/js/']);
INFO PlaywrightCrawler: rendered_quotes: 10
INFO PlaywrightCrawler: requestAvgFinishedDurationMillis: 1958
=== RESULT === items: 1 elapsed_ms: 2716
first: { text: "“The world as we have created it is a process of our thinking…”", author: "Albert Einstein" }
兩個數字放一起看:
| 方式 | 抓到筆數 | 單請求平均 | 相對速度 |
|---|---|---|---|
CheerioCrawler | 0 | 332 ms | 基準 |
PlaywrightCrawler | 10 | 1,958 ms | 慢 5.9 倍(每頁) |
再加上啟動瀏覽器的固定成本(整支程式 2.7 秒),單頁實際成本更高。這就是為什麼「先用 Cheerio,抓不到再換 Playwright」是成本決策而不是品味問題:10,000 頁的站,兩者差的是幾十分鐘與幾小時,以及一台記憶體 8 GB 夠不夠開 4 個瀏覽器。
資料落地:不用自己寫存檔
Crawlee 預設把資料存在工作目錄的 ./storage,而且分成兩層:
storage/
├── datasets/default/000000001.json # 表格型資料(pushData 進來的)
└── key_value_stores/default/
├── SDK_CRAWLER_STATISTICS_0.json # 每次執行的統計
├── SDK_SESSION_POOL_STATE.json # session 狀態(可續跑)
├── books.csv
└── books.json
要匯出成 CSV/JSON,兩行程式:
await Dataset.exportToCSV('books');
await Dataset.exportToJSON('books');
關鍵在 SDK_SESSION_POOL_STATE.json:session(含 cookie、proxy 對應)會落地,程式重啟後可以接著跑。這是「自己刻」最難補的一塊——不是難寫,是難寫對。
pushData 進 Dataset 的每筆資料都是獨立 JSON 檔,可以中途 Dataset.getData() 讀回來,也能直接餵給 Excel/Pandas。
佇列、重試,還有 v3 那個 label 陷阱
要控制「先抓哪些」,就得自己開 RequestQueue 並批次加任務:
const queue = await RequestQueue.open();
await queue.addRequests([
{ url: 'https://books.toscrape.com/catalogue/category/books/travel_2/index.html',
userData: { label: 'travel' } },
{ url: 'https://books.toscrape.com/catalogue/category/books/mystery_3/index.html',
userData: { label: 'mystery' } },
]);
這裡有一個實測踩到的坑:label 不能寫在 request 的頂層,一定要放在 userData 裡。
// ✗ 錯:requestHandler 裡拿到的是 undefined
await queue.addRequests([{ url, label: 'travel' }]);
// ✓ 對
await queue.addRequests([{ url, userData: { label: 'travel' } }]);
寫錯的症狀很隱晦:程式不會報錯、任務照跑,但 request.userData.label 一律是 undefined,所有「依 label 分流」的邏輯默默失效。實測第一輪就是這樣拿到 label=undefined 的——這種靜默失敗比 crash 難查得多。官方文件現在多半直接示範 userData,但舊教學與 v2 時代的範例還是隨處可見。
修正後同一支程式的執行統計:
{"requestsFinished":27,"requestsFailed":0,"retryHistogram":[27],
"requestAvgFinishedDurationMillis":105,"requestsFinishedPerMinute":1897,
"crawlerRuntimeMillis":854}
27 個請求、854 毫秒、1,897 req/min——比第一支快,因為這批頁面更小(分類頁只有 6 本書)。
從原始碼查到的預設值(比文件清楚)
@crawlee/basic/internals/basic-crawler.js 的解構賦值直接寫出所有預設:
| 選項 | 預設值 | 實務意義 |
|---|---|---|
maxRequestRetries | 3 | 失敗重試 3 次才進 failedRequestHandler |
respectRobotsTxtFile | false | 預設不檢查 robots.txt,要自己開 true |
retryOnBlocked | false | 被反爬擋下不會自動換 session 重試 |
useSessionPool | true | 預設有 session 池(Cookie 隔離) |
maxSessionRotations | 10 | 一個 session 最多輪替 10 次 |
sameDomainDelaySecs | 0 | 同網域請求之間不等待 |
respectRobotsTxtFile: false 這條最需要自己決定。框架把它留給使用者,但「預設不抓 robots.txt」在倫理與法律上都不是好預設——做商業爬蟲時,建議一開始就設 respectRobotsTxtFile: true,並用 onSkippedRequest 記錄被跳過的網址,才知道自己的資料集缺了哪一塊。
反封鎖:它做了什麼、沒做什麼
Crawlee 的 README 用了不小的篇幅講「看起來像人」:
- HTTP 端:自動產生瀏覽器風格的 headers、複製瀏覽器 TLS 指紋、零設定支援 HTTP/2(含代理)
- 瀏覽器端:零設定產生人類風格指紋、自動管理瀏覽器實例
- 兩端共用:session 池 + proxy 輪替
但要講清楚它不做什麼:它不內建「突破 Cloudflare 挑戰」這種能力,也不提供付費代理池(那是 Apify 平台的產品)。真正被強驗證擋住時,Crawlee 給的是「換 session、換 proxy、重試」的框架,不是魔法。
什麼時候不該用 Crawlee
- 只抓一頁、只要一次:
curl加cheerio就好,為了一個請求裝框架是反生產力。 - 目標站有嚴格反爬(Cloudflare Turnstile/Akamai):需要的是代理與瀏覽器指紋方案,Crawlee 只提供框架位置。
- 團隊是 Python 生態、不想多一套 Node 執行環境:可以直接用
crawlee-python,或留在 Scrapy。兩套並存代表兩份部署、兩套監控。 - 要的是「排程 + 監控 + 通知」:那是
changedetection.io這類產品的範疇,Crawlee 是寫程式的工具,不是 end-user 服務。
與其他方案的位置比較
| 方案 | 語言 | 佇列/重試/儲存 | JS 渲染 | 適合誰 |
|---|---|---|---|---|
| Crawlee | JS/TS | 內建(佇列、重試、Dataset、KV store) | 內建(Playwright/Puppeteer) | 要寫「會長大的」爬蟲 |
| Playwright 單用 | JS/Python | 自己寫 | 原生 | 一次性腳本、需要精細瀏覽器控制 |
| Scrapy | Python | 內建(Engine/Pipeline) | 需外掛 scrapy-playwright | Python 團隊、大型靜態站 |
| Puppeteer 單用 | JS | 自己寫 | 原生 | 既有 Puppeteer 專案 |
| 視覺化工具(如 changedetection.io) | 無 | 產品化 | 部分支援 | 不想寫程式、只需監控變化 |
Crawlee 的差異化不在「能不能抓」,而在把可靠性當成一等公民:重試直方圖、session 狀態落地、autoscaled pool(依系統資源自動調整並行)這些東西,單獨用 Playwright 要自己補,補得對的人不多。
五個可以直接帶走的實務建議
- 先 Cheerio、後 Playwright:本文實測兩者單頁差 5.9 倍,整支程式差更多。
maxRequestsPerCrawl一定要設:第一次跑就限制在二位數,確認選擇器正確再放大。本文第一支只設 12,避免練習站被自己打爆。retryHistogram是最快的健康檢查:全部落在第一格代表穩定;分岔代表對方站在擋你或選擇器有問題。respectRobotsTxtFile: true自己開:預設是 false,這是使用者的責任不是框架的。label放userData:v2 教學留下來的舊寫法會靜默失效。
站內延伸閱讀
- Python Playwright 爬蟲完整教學:定位器、等待機制與反偵測,跟本文的
PlaywrightCrawler是同一套底層。 - Trafilatura:開源網頁文字擷取工具:抓回 HTML 之後「只要正文」的那一步,常跟 Crawlee 串在一起。
- changedetection.io 完整教學 2026:不想寫程式、只要「網頁變了就通知」時的現成方案。
官方來源:Crawlee 官網、GitHub 倉庫、npm 套件頁、Python 版。本文所有數字皆在 2026-11-17 以 crawlee@3.18.2、Node v26.7.0、Ubuntu 24.04(2 vCPU/7.9 GB RAM)、Chrome 148 實測,測試站為 books.toscrape.com 與 quotes.toscrape.com/js/;星數與下載量以 API 查詢為準,倉庫頁面顯示的數字可能是快取。
