Crawlee 爬蟲框架完整教學:實測數據、反封鎖與 v3 陷阱(2026)

Crawlee 是 Apify 開源的 Node.js 爬蟲框架(26,483 星、Apache-2.0),內建請求佇列、重試、並行調節與資料落地。本文在 2 vCPU 主機實測:靜態站 711 req/min,換瀏覽器渲染慢近 6 倍,並整理從原始碼查到的預設值與 v3 的 label 陷阱。

  • Dennis
  • 8 分鐘閱讀
Crawlee 爬蟲框架完整教學:實測數據、反封鎖與 v3 陷阱(2026)

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 查詢)
星數/fork26,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
CheerioCrawlerHTTP + Cheerio✗快靜態 HTML,90% 的部落格/電商列表頁
JSDOMCrawlerHTTP + JSDOM只有 DOM 模擬中需要 window/document 行為的頁
LinkedomCrawlerHTTP + 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" }

兩個數字放一起看:

方式抓到筆數單請求平均相對速度
CheerioCrawler0332 ms基準
PlaywrightCrawler101,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 的解構賦值直接寫出所有預設:

選項預設值實務意義
maxRequestRetries3失敗重試 3 次才進 failedRequestHandler
respectRobotsTxtFilefalse預設不檢查 robots.txt,要自己開 true
retryOnBlockedfalse被反爬擋下不會自動換 session 重試
useSessionPooltrue預設有 session 池(Cookie 隔離)
maxSessionRotations10一個 session 最多輪替 10 次
sameDomainDelaySecs0同網域請求之間不等待

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 渲染適合誰
CrawleeJS/TS內建(佇列、重試、Dataset、KV store)內建(Playwright/Puppeteer)要寫「會長大的」爬蟲
Playwright 單用JS/Python自己寫原生一次性腳本、需要精細瀏覽器控制
ScrapyPython內建(Engine/Pipeline)需外掛 scrapy-playwrightPython 團隊、大型靜態站
Puppeteer 單用JS自己寫原生既有 Puppeteer 專案
視覺化工具(如 changedetection.io)無產品化部分支援不想寫程式、只需監控變化

Crawlee 的差異化不在「能不能抓」,而在把可靠性當成一等公民:重試直方圖、session 狀態落地、autoscaled pool(依系統資源自動調整並行)這些東西,單獨用 Playwright 要自己補,補得對的人不多。

五個可以直接帶走的實務建議

  1. 先 Cheerio、後 Playwright:本文實測兩者單頁差 5.9 倍,整支程式差更多。
  2. maxRequestsPerCrawl 一定要設:第一次跑就限制在二位數,確認選擇器正確再放大。本文第一支只設 12,避免練習站被自己打爆。
  3. retryHistogram 是最快的健康檢查:全部落在第一格代表穩定;分岔代表對方站在擋你或選擇器有問題。
  4. respectRobotsTxtFile: true 自己開:預設是 false,這是使用者的責任不是框架的。
  5. label 放 userData:v2 教學留下來的舊寫法會靜默失效。

站內延伸閱讀


官方來源: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 查詢為準,倉庫頁面顯示的數字可能是快取。

📬 訂閱 most.tw 電子報

每週精選 AI 工具教學與技術乾貨,直接送到你的信箱。免費、隨時可退訂。

訂閱即表示同意收到 most.tw 電子報,隨時可一鍵退訂。

💬 有問題想討論?加 LINE 聯絡我

歡迎透過 LINE 官方帳號直接留言,我會盡快回覆你的問題。

加入 LINE 好友