最完整Crawlee入门指南：5分钟搭建专业爬虫项目

你还在为复杂的网页抓取任务烦恼吗？想快速搭建一个稳定高效的爬虫却不知从何下手？本文将带你5分钟入门Crawlee，一个专为Node.js设计的网页抓取和浏览器自动化库，让你轻松构建专业级爬虫项目。读完本文，你将掌握Crawlee的安装配置、三种核心爬虫类型的使用、数据提取与存储的完整流程，并能独立运行你的第一个爬虫项目。

环境准备与快速安装

Crawlee需要Node.js 16或更高版本环境。首先确认你的开发环境是否满足要求：

node -v  # 检查Node.js版本
npm -v   # 检查npm版本

两种安装方式

1. 使用Crawlee CLI（推荐） 最快捷的方式是使用Crawlee命令行工具，它会自动创建项目结构并安装依赖：

npx crawlee create my-crawler
cd my-crawler && npm start

2. 手动安装 如果需要集成到现有Node.js项目，可根据爬虫类型手动安装：

CheerioCrawler（轻量级HTTP爬虫）

npm install crawlee

PlaywrightCrawler（多浏览器支持）

npm install crawlee playwright

PuppeteerCrawler（Chrome/Chromium专用）

npm install crawlee puppeteer

官方文档：docs/quick-start/index.mdx

核心爬虫类型与应用场景

Crawlee提供三种核心爬虫，满足不同场景需求：

1. CheerioCrawler：轻量级HTTP爬虫

基于Cheerio解析HTML，速度快、资源占用低，适合静态网页抓取。不支持JavaScript渲染，适用于服务器端渲染(SSR)网站。

import { CheerioCrawler } from 'crawlee';

const crawler = new CheerioCrawler({
    async requestHandler({ $, request }) {
        const title = $('title').text();
        console.log(`标题: ${title} (${request.url})`);
    }
});

await crawler.run(['https://crawlee.dev']);

2. PlaywrightCrawler：多浏览器自动化

支持Chromium、Firefox、WebKit等多种浏览器，功能全面，适合需要JavaScript渲染的动态网页。

import { PlaywrightCrawler } from 'crawlee';

const crawler = new PlaywrightCrawler({
    async requestHandler({ page, request }) {
        const title = await page.title();
        console.log(`标题: ${title} (${request.url})`);
    }
});

await crawler.run(['https://crawlee.dev']);

3. PuppeteerCrawler：Chrome专用爬虫

专注于Chrome/Chromium浏览器自动化，API成熟稳定，适合需要深度控制Chrome的场景。

三种爬虫对比：

爬虫类型	渲染能力	速度	资源占用	适用场景
CheerioCrawler	❌ 无	⚡ 最快	📉 低	静态网页、API数据
PlaywrightCrawler	✅ 全功能	🚀 快	📈 中	动态网页、多浏览器测试
PuppeteerCrawler	✅ Chrome渲染	🚀 快	📈 中	Chrome生态集成

技术文档：docs/introduction/02-first-crawler.mdx

实战：5分钟构建网页标题抓取器

下面以PlaywrightCrawler为例，构建一个抓取网页标题并保存的完整爬虫：

1. 创建基本爬虫结构

import { PlaywrightCrawler, Dataset } from 'crawlee';

const crawler = new PlaywrightCrawler({
    // 启用可视化模式（开发调试用）
    headless: false,
    async requestHandler({ page, request }) {
        // 提取页面标题
        const title = await page.title();
        console.log(`抓取成功: ${title} (${request.url})`);
        
        // 保存数据到数据集
        await Dataset.pushData({
            url: request.url,
            title,
            timestamp: new Date().toISOString()
        });
    }
});

// 启动爬虫，从指定URL开始
await crawler.run([
    'https://crawlee.dev',
    'https://crawlee.dev/js/docs/examples'
]);

2. 运行爬虫

node src/main.js

运行时会看到浏览器自动打开并访问目标网页，终端输出抓取进度：

INFO  PlaywrightCrawler: Starting the crawl
抓取成功: Crawlee · Build reliable crawlers. Fast. | Crawlee (https://crawlee.dev)
抓取成功: Examples | Crawlee (https://crawlee.dev/js/docs/examples)
INFO  PlaywrightCrawler: Crawling finished. Final request statistics:
INFO  PlaywrightCrawler: Requests processed: 2

3. 查看结果数据

Crawlee自动将数据保存在./storage/datasets/default目录下：

// storage/datasets/default/000000001.json
{
    "url": "https://crawlee.dev",
    "title": "Crawlee · Build reliable crawlers. Fast. | Crawlee",
    "timestamp": "2025-10-02T10:36:27.123Z"
}

完整示例：docs/introduction/07-example.ts

高级功能与最佳实践

1. 动态添加URL（递归爬取）

通过enqueueLinks自动发现并添加新URL：

import { PlaywrightCrawler } from 'crawlee';

const crawler = new PlaywrightCrawler({
    async requestHandler({ page, enqueueLinks }) {
        // 提取当前页面标题
        const title = await page.title();
        console.log(`标题: ${title}`);
        
        // 发现并添加新链接（仅同一域名）
        await enqueueLinks({
            selector: 'a',
            filter: ({ url }) => url.hostname === 'crawlee.dev'
        });
    }
});

await crawler.run(['https://crawlee.dev']);

2. 数据存储与导出

除默认文件存储外，可通过Dataset导出数据为CSV/JSON：

// 导出为CSV
await Dataset.exportToCSV('results');
// 导出为JSON
await Dataset.exportToJSON('results');

数据存储文档：docs/guides/result-storage.mdx

3. 反屏蔽策略

Crawlee内置多种反屏蔽机制，可通过配置增强爬取稳定性：

const crawler = new PlaywrightCrawler({
    // 随机用户代理
    useSessionPool: true,
    sessionPoolOptions: { sessionOptions: { maxUsageCount: 5 } },
    // 随机延迟
    minConcurrency: 1,
    maxConcurrency: 5,
    // 重试失败请求
    maxRequestRetries: 3,
});

反屏蔽指南：docs/guides/avoid_blocking.mdx

部署与扩展

本地开发调试

启用Headful模式查看浏览器操作过程：

const crawler = new PlaywrightCrawler({
    headless: false,  // 显示浏览器窗口
    slowMo: 500,      // 延迟500ms，便于观察
});

服务器部署

Crawlee支持多种部署方式：

• Docker容器化：docs/guides/docker_images.mdx
• 云平台部署：AWS、GCP等云服务部署指南 docs/deployment/
• Apify平台：一键部署到Apify云爬虫平台

总结与资源推荐

通过本文你已掌握Crawlee的核心使用方法，能够快速构建专业爬虫项目。关键要点：

1. 根据需求选择合适的爬虫类型（静态页用Cheerio，动态页用Playwright/Puppeteer）
2. 使用crawler.run()启动爬虫，传入起始URL列表
3. 通过Dataset.pushData()轻松保存抓取结果
4. 利用enqueueLinks实现递归爬取整站内容

进阶学习资源：

• 完整示例库：docs/examples/
• API参考文档：packages/core/src/
• 社区教程：README.md

现在就动手创建你的第一个Crawlee爬虫项目吧！遇到问题可查阅官方文档或提交Issue获取帮助。