Crawlee-Python 升级指南：从零版本到 v0.x 的技术迁移

Crawlee-Python 升级指南：从零版本到 v0.x 的技术迁移

crawlee-python Crawlee—A web scraping and browser automation library for Python to build reliable crawlers. Extract data for AI, LLMs, RAG, or GPTs. Download HTML, PDF, JPG, PNG, and other files from websites. Works with BeautifulSoup, Playwright, and raw HTTP. Both headful and headless mode. With proxy rotation. 项目地址: https://gitcode.com/gh_mirrors/cr/crawlee-python

前言

对于使用 Crawlee-Python 进行网络爬虫开发的开发者来说，版本升级是不可避免的过程。本文将详细介绍从零版本升级到 v0.x 系列版本中的关键变化和迁移策略，帮助开发者顺利完成版本过渡。

版本升级概览

Crawlee-Python 在 v0.x 系列版本中进行了多项架构调整和功能优化，主要包括：

1. 核心类结构调整
2. 接口规范化
3. 功能增强与优化
4. 废弃功能的移除

升级到 v0.6 的重要变更

HttpClient 重构

HttpClient 类经历了重大重构：

• 移除了构造函数参数 additional_http_error_status_codes 和 ignore_http_error_status_codes
• 这些参数现在仅通过 BasicCrawlerOptions 提供
• 移除了 _raise_for_error_status_code 方法，其逻辑已迁移到 BasicCrawler 类

迁移建议：检查项目中所有 HttpClient 实例化代码，移除相关参数，改为在 BasicCrawler 配置中设置。

会话 Cookie 管理改进

SessionCookies 类取代了原有的字典实现：

• 使用 CookieJar 作为底层存储
• 支持多域名场景
• 提供更完善的 Cookie 管理功能

示例代码：

# 旧版本
session.cookies = {'name': 'value'}

# 新版本
session.cookies.set_cookie('name', 'value', domain='example.com')

Playwright 增强

PlaywrightCrawler 和 PlaywrightBrowserPlugin 的改进：

• 默认使用持久化浏览器上下文
• 新增 user_data_dir 参数指定持久化目录
• 未指定时自动创建临时目录

最佳实践：对于需要保持登录状态的爬取任务，建议显式设置 user_data_dir。

配置简化

移除了以下配置项：

• chrome_executable_path（未使用）
• xvfb（未使用）
• verbose_log（改用 log_level=DEBUG）

抽象类命名规范化

从匈牙利命名法迁移：

• BaseStorageClient → StorageClient
• BaseBrowserController → BrowserController
• BaseBrowserPlugin → BrowserPlugin

升级到 v0.5 的关键变化

模块结构调整

1. 爬虫类重组：

   • 所有爬虫和上下文类移至 crawlers 子包
   • 统一导入路径，提高代码组织性

2. 存储客户端整合：

   • 存储相关类移至 storage_clients 子包
   • 包括 MemoryStorageClient 和 BaseStorageClient

导入更新示例：

# 旧版本
from crawlee.beautifulsoup_crawler import BeautifulSoupCrawler

# 新版本
from crawlee.crawlers import BeautifulSoupCrawler

请求管理重构

1. 术语变更：

   • request_provider → request_manager
   • RequestProvider 接口 → RequestManager
   • 相关方法同步更名

2. 功能调整：

   • RequestList 移除了部分方法（.drop(), .reclaim_request() 等）
   • 引入 RequestLoader 接口和 RequestManagerTandem

迁移策略：

# 旧用法
request_list.drop()

# 新用法
tandem = await request_list.to_tandem()
await tandem.drop()

Playwright 相关变更

1. 类名更新：

   • PlaywrightPreNavigationContext → PlaywrightPreNavCrawlingContext

2. 参数重命名：

   • browser_options → browser_launch_options
   • page_options → browser_new_context_options

升级到 v0.4 的注意事项

请求模型简化

1. 移除 Request.query_params：

   • 现在需直接将查询参数拼接到 URL 中
   • 这是更符合 HTTP 标准的设计

2. 合并 Request.payload 和 Request.data：

   • 统一使用 Request.payload 字段
   • 简化了请求体数据处理方式

唯一键计算增强

extended_unique_key 现在包含 HTTP 头信息：

• 影响请求去重逻辑
• 接口保持不变，但行为更精确

升级到 v0.3 的接口调整

公共接口规范化

明确区分公共和私有接口：

• 许多内部实现细节被标记为私有
• 公共接口导入路径变更

常见导入更新：

# 旧版本
from crawlee.enqueue_strategy import EnqueueStrategy

# 新版本
from crawlee import EnqueueStrategy

请求队列内部优化

1. 移除未使用的方法：

   • BaseRequestQueueClient.list_requests()

2. 实现与 JS 版对齐：

   • 采用 "Request Queue V2" 架构
   • 提升性能和稳定性

升级策略与最佳实践

1. 逐步迁移：

   • 建议按版本顺序逐步升级
   • 先升级到 v0.3，再逐步到 v0.6

2. 测试覆盖：

   • 确保有完善的测试用例
   • 特别关注爬虫去重和请求处理逻辑

3. 依赖管理：

   • CLI 功能现在是可选依赖
   • 需要时安装 crawlee[cli]

4. 配置检查：

   • 移除废弃的配置项
   • 更新日志级别设置方式

结语

Crawlee-Python 在 v0.x 系列版本中的改进使框架更加规范、稳定和易用。虽然升级过程可能需要一些调整，但这些变化为后续的功能扩展和性能优化奠定了坚实基础。建议开发者根据项目实际情况制定升级计划，充分利用新版本提供的改进特性。

crawlee-python Crawlee—A web scraping and browser automation library for Python to build reliable crawlers. Extract data for AI, LLMs, RAG, or GPTs. Download HTML, PDF, JPG, PNG, and other files from websites. Works with BeautifulSoup, Playwright, and raw HTTP. Both headful and headless mode. With proxy rotation. 项目地址: https://gitcode.com/gh_mirrors/cr/crawlee-python