一个用于网络爬取和浏览器自动化的小程序库

Crawlee 覆盖了您的爬取和数据抓取全流程，并且帮助您快速构建可靠的爬虫。

即使使用默认配置，您的爬虫也会表现得几乎像真人一样，轻松躲过现代反爬机制的检测。Crawlee 提供了丰富的工具，让您能够抓取网页上的链接、提取数据并以机器可读的格式持久化存储，而无需担心底层的技术细节。同时，借助其强大的配置选项，您可以根据项目需求调整 Crawlee 的几乎所有方面，以满足特定场景的要求。

👉 请访问 Crawlee 项目官网 查看完整的文档、指南和示例 👈

我们还提供了 TypeScript 版本的 Crawlee，您也可以将其用于自己的项目中。更多信息请访问我们的 GitHub 仓库：Crawlee for JS/TS on GitHub。

安装

建议您阅读 Crawlee 文档中的入门教程，以获取更多详细信息。

Crawlee 作为 crawlee 包发布在 PyPI 上。该包包含了核心功能，而其他附加特性则以可选扩展的形式提供，以便保持依赖项和包体积的最小化。

要安装包含所有功能的 Crawlee，请运行以下命令：

python -m pip install 'crawlee[all]'

然后安装 Playwright 的依赖项：

playwright install

验证 Crawlee 是否成功安装：

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

详细的安装步骤请参阅设置文档页面。

使用 Crawlee CLI

开始使用 Crawlee 最快捷的方式是通过 Crawlee CLI 并选择一个预设模板。首先确保您已安装 uv：

uv --help

如果尚未安装 uv，请按照官方安装指南进行安装。

然后运行 CLI 并从可用模板中选择：

uvx 'crawlee[cli]' create my-crawler

如果您已经安装了 crawlee，可以直接运行以下命令启动：

crawlee create my-crawler

示例

以下是一些实用示例，帮助您快速上手 Crawlee 中不同类型的爬虫。每个示例都展示了如何针对特定用例设置和运行爬虫，无论您是需要处理简单的 HTML 页面，还是与大量 JavaScript 的网站交互。运行爬虫后，会在当前工作目录下创建一个 storage/ 目录。

BeautifulSoupCrawler

BeautifulSoupCrawler 使用 HTTP 库下载网页，并将解析后的 HTML 内容提供给用户。默认情况下，它使用 HttpxHttpClient 进行 HTTP 通信，并用 BeautifulSoup 解析 HTML。它非常适合需要高效提取 HTML 内容的项目。由于不使用浏览器，这种爬虫性能非常出色。然而，如果您需要执行客户端 JavaScript 才能获取内容，则此方法无法满足需求，这时就需要使用 PlaywrightCrawler。另外，如果您打算使用此爬虫，请务必安装带有 beautifulsoup 扩展的 crawlee。

import asyncio

from crawlee.crawlers import BeautifulSoupCrawler, BeautifulSoupCrawlingContext


async def main() -> None:
    crawler = BeautifulSoupCrawler(
        # 限制爬取的最大请求数。移除或增加此值可爬取所有链接。
        max_requests_per_crawl=10,
    )

    # 定义默认请求处理器，它将被调用以处理每一条请求。
    @crawler.router.default_handler
    async def request_handler(context: BeautifulSoupCrawlingContext) -> None:
        context.log.info(f'正在处理 {context.request.url} ...')

        # 从页面中提取数据。
        data = {
            'url': context.request.url,
            'title': context.soup.title.string if context.soup.title else None,
        }

        # 将提取的数据推送到默认数据集中。
        await context.push_data(data)

        # 将页面中找到的所有链接加入队列。
        await context.enqueue_links()

    # 使用初始 URL 列表运行爬虫。
    await crawler.run(['https://crawlee.dev'])


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

PlaywrightCrawler

PlaywrightCrawler 使用无头浏览器下载网页，并提供用于数据提取的 API。它基于 Playwright 构建，Playwright 是一个专为管理无头浏览器而设计的自动化库。该爬虫特别擅长抓取那些依赖客户端 JavaScript 生成内容的页面，或需要与 JavaScript 驱动内容交互的任务。如果在某些场景中无需执行 JavaScript 或需要更高性能，则可以考虑使用 BeautifulSoupCrawler。此外，若要使用此爬虫，请确保安装 crawlee 时带有 playwright 附加组件。

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'正在处理 {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())

更多示例

请访问 Crawlee 文档中的 示例 页面，了解更广泛的使用场景和演示。

功能特性

为什么 Crawlee 是网络爬取和抓取任务的首选工具？

为什么选择 Crawlee 而不是简单的 HTTP 库结合 HTML 解析器？

• 统一的 HTTP 和无头浏览器 抓取接口。
• 基于系统可用资源的自动 并行抓取。
• 使用 Python 编写并配备 类型提示，提升开发体验（IDE 自动补全）并减少错误（静态类型检查）。
• 在遇到错误或被封禁时自动进行 重试。
• 集成 代理轮换 和会话管理功能。
• 可配置的 请求路由，可将不同 URL 路由到相应的处理器。
• 持久化的待抓取 URL 队列。
• 可插拔的 存储系统，支持表格数据和文件的存储。
• 强大的 错误处理机制。

为什么选择 Crawlee 而不是 Scrapy？

• 基于 Asyncio —— Crawlee 利用标准的 Asyncio 库，提供了更好的性能，并与其他现代异步库无缝兼容。
• 类型提示 —— 新项目采用现代 Python 编写，全面覆盖类型提示，从而提升开发者体验。
• 简单集成 —— Crawlee 爬虫是普通的 Python 脚本，无需额外的启动器或执行器。这种灵活性使得爬虫可以直接集成到其他应用程序中。
• 状态持久化 —— 支持在中断后恢复状态，避免因问题导致爬取流程需要从头开始，从而节省时间和成本。
• 结构化的数据存储 —— 允许在一次爬取过程中保存多种类型的结果。提供多种存储选项（参见 数据集 和 键值存储）。

在 Apify 平台上的运行

Crawlee 是开源的，可以在任何地方运行，但由于它由 Apify 开发，因此在 Apify 平台上设置并云端运行非常方便。请访问 Apify SDK 官网 了解更多关于将 Crawlee 部署到 Apify 平台的信息。

支持

如果您发现 Crawlee 中存在任何 bug 或问题，请在 GitHub 上提交 issue。如有疑问，您可以在 Stack Overflow、GitHub 讨论区提问，或者加入我们的 Discord 社区。

贡献

我们欢迎您的代码贡献，您的努力将永载史册！如果您有任何改进建议，可以提交 issue 或创建 pull request。有关贡献指南和行为准则，请参阅 CONTRIBUTING.md。

许可证

本项目采用 Apache License 2.0 许可证授权——详情请参阅 LICENSE 文件。

Crawlee-Python 快速上手指南

Crawlee 是一个专为 Python 打造的网页爬虫和浏览器自动化库。它能帮助你快速构建稳定、高效的爬虫，自动处理反爬机制、代理轮换、请求重试和数据持久化，让爬虫行为更像真实用户。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Windows, macOS 或 Linux
• Python 版本：Python 3.9 或更高版本
• 包管理工具：推荐使用 pip 或现代化的 uv (用于 CLI 快速初始化)
• 网络环境：能够访问 PyPI 和 GitHub（若下载 Playwright 浏览器内核较慢，建议配置国内镜像或代理）

安装步骤

方式一：使用 pip 安装（推荐）

1. 安装 Crawlee 核心库及所有功能组件：

   python -m pip install 'crawlee[all]'
   

   提示：国内用户若下载缓慢，可添加清华或阿里镜像源： python -m pip install 'crawlee[all]' -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装 Playwright 浏览器内核： Crawlee 依赖 Playwright 进行浏览器自动化，需单独下载浏览器二进制文件：

   playwright install
   

   注意：此步骤会下载 Chrome、Firefox 等浏览器内核，请确保网络连接通畅。

3. 验证安装：

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

方式二：使用 CLI 快速创建项目

如果你已安装 uv 工具，可以使用官方 CLI 一键生成项目模板：

uvx 'crawlee[cli]' create my-crawler

或者在已安装 crawlee 的情况下运行：

crawlee create my-crawler

基本使用

Crawlee 提供了多种爬虫类型，最常用的是 BeautifulSoupCrawler（高性能，适合静态页面）和 PlaywrightCrawler（支持 JavaScript 渲染，适合动态页面）。

示例 1：使用 BeautifulSoupCrawler 抓取静态页面

此模式不启动浏览器，通过 HTTP 请求获取 HTML 并解析，速度极快。

import asyncio

from crawlee.crawlers import BeautifulSoupCrawler, BeautifulSoupCrawlingContext


async def main() -> None:
    crawler = BeautifulSoupCrawler(
        # 限制最大请求数，生产环境中可移除或调大此参数
        max_requests_per_crawl=10,
    )

    # 定义默认请求处理器，每个请求都会触发此函数
    @crawler.router.default_handler
    async def request_handler(context: BeautifulSoupCrawlingContext) -> None:
        context.log.info(f'Processing {context.request.url} ...')

        # 提取数据
        data = {
            'url': context.request.url,
            'title': context.soup.title.string if context.soup.title else None,
        }

        # 将数据保存到默认数据集
        await context.push_data(data)

        # 将页面中发现的所有链接加入队列
        await context.enqueue_links()

    # 启动爬虫，传入初始 URL 列表
    await crawler.run(['https://crawlee.dev'])


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

示例 2：使用 PlaywrightCrawler 抓取动态页面

如果目标网站依赖 JavaScript 加载内容（如 React/Vue 应用），请使用此模式。它会启动无头浏览器进行渲染。

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} ...')

        # 提取数据（此时页面已完成 JS 渲染）
        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())

运行结果

执行上述脚本后，Crawlee 会在当前工作目录下自动生成一个 storage/ 文件夹。抓取到的数据将以机器可读的格式（如 JSON/CSV）保存在 storage/datasets/default/ 目录中。