Crawlee for Python：Apify 出品的开源爬虫/浏览器自动化库｜部署与使用全指南

Crawlee for Python 是 Apify 团队用 Python 重写的 Crawlee 爬虫框架，把 HTTP 抓取、无头浏览器（Playwright）、自动重试、代理轮换、请求队列、断点续爬与数据存储全部封装成一套统一 API。它既不是「一个脚本跑到底」的玩具，也不是 Scrapy 那样重的工程框架，而是一个可以直接 asyncio.run() 嵌入到任意 Python 应用里的库。

1. 项目简介与定位

官方 README 一句话：Crawlee covers your crawling and scraping end-to-end and helps you build reliable scrapers. Fast. 它的目标是让你的爬虫默认行为就「像真人」，在现代反爬系统下也能低调跑过去。

1.1 核心信息一览

1.2 适用场景

• 想用现代 asyncio + 类型注解写爬虫，而不是维护一堆 requests + 正则脚本。
• 需要同时处理「静态 HTML 站」和「JS 渲染站」，但不想维护两套抓取代码。
• 想要自动重试、自动限速、自动代理轮换、断点续爬这些「工程化默认值」。
• 想把爬虫作为模块嵌进 FastAPI / 数据流水线，而不是跑一个独立 Scrapy 工程。

1.3 能力边界（官方口径）

• 它是库，不是服务：没有 Web UI、没有默认端口、不自带反打码。
• PlaywrightCrawler 依赖本地/容器里的 Chromium；服务器要跑浏览器就需要装 Playwright 系统依赖。
• Apify 云部署是可选路径，但库本身完全开源、可本地跑。

2. 开源协议

Apache License 2.0（仓库根目录 LICENSE）。商用友好，允许闭源衍生作品；保留版权声明即可。

3. 官方仓库与链接

• 仓库：https://github.com/apify/crawlee-python
• 文档站：https://crawlee.dev/python/
• 入门教程：https://crawlee.dev/python/docs/introduction
• 安装说明：https://crawlee.dev/python/docs/introduction/setting-up
• Guides：https://crawlee.dev/python/docs/guides
• TypeScript 姊妹版：https://github.com/apify/crawlee
• Apify 云 SDK（Python）：https://docs.apify.com/sdk/python/
• Discord：https://discord.com/invite/jyEM2PRvMU
• Issues：https://github.com/apify/crawlee-python/issues

4. 前置要求

来自 README 与 badge：

• Python 3.10 或更高版本。
• 操作系统：Linux / macOS / Windows（Windows 推荐用 WSL2 跑 Playwright）。
• 若用 PlaywrightCrawler：需要能跑无头 Chromium 的环境（Linux 服务器要装 playwright install --with-deps）。
• 推荐包管理器：uv，用于 `uvx crawlee[cli]` 一键起模板。
• 不需要数据库；运行数据默认落在本地 storage/ 目录。

5. 安装部署

5.1 方式一：pip 安装完整功能（推荐）

README 原文：

python -m pip install 'crawlee[all]'

然后装 Playwright 浏览器：

playwright install

验证安装：

python -c 'import crawlee; print(crawlee.__version__)'

如果只想装 HTTP 抓取能力，把 [all] 换成 [beautifulsoup]；只用浏览器就换成 [playwright]。可选 extras 列表见官方文档 Setting up 页。

5.2 方式二：用 CLI 模板脚手架起新项目

确保 uv 已装：

uv --help

然后：

uvx 'crawlee[cli]' create my-crawler

如果已经 pip install crawlee，直接：

crawlee create my-crawler

CLI 会让你选一个预置模板（HTTP / Playwright），生成可直接 python main.py 运行的项目骨架。

5.3 方式三：部署到 Apify 云

Crawlee 是 Apify 自家项目，可以很方便地打包成 Actor 丢到 Apify 平台跑。具体步骤见 Apify SDK for Python 文档。本地跑通后再上云。

6. 最小示例代码

6.1 BeautifulSoupCrawler（纯 HTTP，不启浏览器）

直接抄自官方 README：

import asyncio

from crawlee.crawlers import BeautifulSoupCrawler, BeautifulSoupCrawlingContext


async def main() -> None:
    crawler = BeautifulSoupCrawler(
        # Limit the crawl to max requests. Remove or increase it for crawling all links.
        max_requests_per_crawl=10,
    )

    # Define the default request handler, which will be called for every request.
    @crawler.router.default_handler
    async def request_handler(context: BeautifulSoupCrawlingContext) -> None:
        context.log.info(f'Processing {context.request.url} ...')

        # Extract data from the page.
        data = {
            'url': context.request.url,
            'title': context.soup.title.string if context.soup.title else None,
        }

        # Push the extracted data to the default dataset.
        await context.push_data(data)

        # Enqueue all links found on the page.
        await context.enqueue_links()

    # Run the crawler with the initial list of URLs.
    await crawler.run(['https://crawlee.dev'])


if __name__ == '__main__':
    asyncio.run(main())

运行后会在当前目录生成 storage/，里面有 datasets/（抓下来的数据）、request_queues/（待抓队列）、key_value_stores/（缓存）。

6.2 PlaywrightCrawler（无头浏览器，适合 JS 渲染站）

import asyncio

from crawlee.crawlers import PlaywrightCrawler, PlaywrightCrawlingContext


async def main() -> None:
    crawler = PlaywrightCrawler(
        max_requests_per_crawl=10,
    )

    @crawler.router.default_handler
    async def request_handler(context: PlaywrightCrawlingContext) -> None:
        context.log.info(f'Processing {context.request.url} ...')

        data = {
            'url': context.request.url,
            'title': await context.page.title(),
        }

        await context.push_data(data)
        await context.enqueue_links()

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


if __name__ == '__main__':
    asyncio.run(main())

区别：context.page 就是一个 Playwright Page 对象，可以直接 await context.page.click(...)、await context.page.fill(...) 做交互。

7. 配置项说明

7.1 构造器常用参数（README + 文档）

7.2 在 handler 里常用的 context 方法

7.3 存储布局

• storage/datasets/default/：JSON 行数据，每行一条记录。
• storage/request_queues/default/：待抓与已抓队列，断点续爬靠它。
• storage/key_value_stores/default/：任意 KV 缓存（响应 HTML、截图等）。

8. 常见问题

Q1：和 Scrapy 选哪个？ README 自己列了对比：Crawlee 是 asyncio 原生、全类型注解、普通 Python 脚本即可（不需要 scrapy crawl 命令）、支持断点续爬、多类型存储并存；Scrapy 生态更老、中间件更全，但基于 Twisted 且需要项目骨架。

Q2：为什么我抓的页面是空的？ 多半是 SPA，用 BeautifulSoupCrawler 抓不到 JS 渲染后的内容。换成 PlaywrightCrawler，或在 HTTP 模式下改用 API 接口。

Q3：Linux 服务器跑 Playwright 报缺库？

playwright install --with-deps chromium

会把 Chromium 需要的系统依赖一次装好。

Q4：怎么限速 / 加延时？ 在 Crawler 构造器里设 max_concurrency，或在 handler 里 await asyncio.sleep(...)。代理与 session 池也会自动做节流。

Q5：数据存哪？ 默认 ./storage/。要换路径或对接外部存储（S3、数据库）见文档 Storage 章节。

9. 与同类工具对比

10. 许可

Apache License 2.0。允许商用、修改、闭源分发；保留原始版权与许可证声明即可。衍生作品不能用 Apify 官方名号做背书。

11. 责任使用声明

使用 Crawlee 抓取网站时，请遵守：

1. 尊重目标站点 robots.txt 与服务条款，不要为了绕开限制去关闭 Crawlee 的礼貌性默认值。
2. 控制并发与延时，默认配置之外不要盲目拉高 max_concurrency，避免给目标站点造成压力。
3. 不绕过登录墙、付费墙与验证码，不要用代理池做未授权的批量账号操作。
4. 不批量抓取个人隐私信息（通讯录、订单、身份证件等）。
5. 仅将抓取到的公开数据用于合法的研究、产品功能与个人学习。
6. 二次发布内容时遵守原网站版权要求，注明来源。