Crawlee 是一个用于构建可靠网络爬虫与浏览器自动化的 TypeScript/JavaScript 框架，定位是为开发者提供一套统一的 API，覆盖纯 HTTP 抓取、Headless 浏览器抓取以及 AI 驱动的自然语言交互等多条抓取路径。框架同时强调可观测的浏览器生命周期、代理轮换、请求队列以及与 Cheerio、Playwright、Puppeteer、Camoufox、Stagehand 等生态工具的深度集成。

一、定位与核心能力

Crawlee 通过对抓取过程中重复、易错的环节（请求调度、重试、代理、并发、存储、浏览器池等）进行抽象，让用户只关注 requestHandler 中的业务逻辑。website/src/pages/js.js 的营销文案直接指出 "One API for headless and HTTP" —— 即同一套 API 既能驱动 HTTP 请求也能驱动无头浏览器，并且支持 Adaptive Crawler 自动判断页面是否需要 JS 渲染。框架还强调 Auto Scaling、内建代理轮换、浏览器指纹伪装以及统一的存储抽象。

对于以传统 HTML 抓取为主的场景，StagehandCrawler 文档建议优先使用 PlaywrightCrawler，而将 Stagehand 留给"复杂或经常变化布局"的网站 —— 这体现了"先用最稳的工具，再考虑 AI 增强"的取舍哲学（资料来源：packages/stagehand-crawler/README.md）。

二、仓库结构与核心包

仓库根目录使用 Yarn 4 + Lerna 9 + Turborepo 的 monorepo 模式，统一管理子包与模板（资料来源：package.json）。http-crawler 包通过 got-scraping 拿到 HTTP 抓取栈，并集成 iconv-lite、mime-types、ow 等编码与校验工具（资料来源：packages/http-crawler/package.json）。templates/ 目录提供开箱即用的脚手架，覆盖 Cheerio、Playwright、Puppeteer、Camoufox 等多种爬虫形态，并区分 JavaScript 与 TypeScript 两套版本，模板里只列出 crawlee: ^3.0.0 这一个统一依赖（资料来源：packages/templates/templates/empty-ts/package.json）。

下表汇总了仓库中具有代表性的子包与模板：

三、浏览器池与抓取双轨架构

Crawlee 的核心抽象是 BrowserPool，它把"何时启动浏览器、是否复用上下文、是否在请求粒度上切换代理"等复杂策略抽成统一的 LaunchContext（资料来源：packages/browser-pool/src/launch-context.ts）。BrowserController 抽象基类暴露浏览器实例、LaunchContext、proxyTier、proxyUrl 等状态，由 PuppeteerController/PlaywrightController 等具体实现继承，避免重复维护（资料来源：packages/browser-pool/src/abstract-classes/browser-controller.ts）。

PlaywrightCrawler 与 PuppeteerCrawler 都基于 BrowserPool，并提供各自的工具方法，例如 Playwright 的 compileScript() 用 vm.runInNewContext 在隔离上下文中执行用户脚本（资料来源：packages/playwright-crawler/src/internals/utils/playwright-utils.ts），Puppeteer 工具则提供 enqueueLinksByClickingElements() 之类的点击驱动抓取辅助（资料来源：packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts）。共享工具方面，@crawlee/utils 提供 parseOpenGraph() 这样的内容解析函数，HTML 与 Cheerio 对象两种签名可重载（资料来源：packages/utils/src/internals/open_graph_parser.ts）。

flowchart LR
  A[RequestQueue] --> B[BasicCrawler]
  B --> C{HTTP 抓取?}
  C -- 是 --> D[HttpCrawler / CheerioCrawler]
  C -- 否 --> E[BrowserCrawler]
  E --> F[BrowserPool]
  F --> G[Puppeteer / Playwright / Camoufox]
  E --> H[StagehandCrawler + LLM]
  D --> I[Dataset / KeyValueStore]
  G --> I
  H --> I

四、运行时、版本与社区关注点

当前仓库主推 Node.js 24，并通过 volta 固定 [email protected]，统一工程链路（资料来源：package.json）。社区中关于 Bun 运行时的兼容请求（#2046）以及把 @crawlee/memory-storage 合并进 @crawlee/core（#3756）反映出"减少冗余依赖、扩展支持范围"的方向。

最新版本 v3.17.0（2026-06-04）修复了 discoverValidSitemaps 可能挂起的问题（#3429）并修正了 PuppeteerPlugin 中 Browser.pages() 的 this 绑定。最近几个版本还涵盖了 ImpitHttpClient 超时支持、Playwright launchOptions 与 useIncognitoPages 的协作、Adaptive Crawler 渲染类型持久化等稳定性改进，体现了"抓取正确性 > 抓取速度"的持续投入。

参见

• 基础爬虫与请求生命周期
• 浏览器池与 LaunchContext
• Playwright / Puppeteer 集成
• HTTP 抓取与 CheerioCrawler
• Stagehand 与 AI 驱动爬虫

概述与整体架构

Crawlee 是一个使用 Lerna 管理多包结构的 JavaScript/TypeScript 爬虫与抓取库，采用 monorepo 形式组织代码 package.json:1-25。各功能模块均以独立包形式发布，例如 @crawlee/browser-pool、@crawlee/utils、@crawlee/http-crawler 等，并在各自包内使用 src/ 目录存放源代码。这种结构允许用户只安装需要的子包，从而减小打包体积。

packages/crawlee/package.json 文件揭示了主入口包 @crawlee/root 依赖了几乎所有子包，包括 @crawlee/basic、@crawlee/browser、@crawlee/browser-pool、@crawlee/cheerio、@crawlee/cli、@crawlee/core、@crawlee/http、@crawlee/jsdom、@crawlee/linkedom、@crawlee/playwright、@crawlee/puppeteer 等 packages/crawlee/package.json:39-50。每个子包都遵循统一的 src/ 目录布局，便于跨包复用与版本对齐。

社区已多次提出跨包整合建议，例如 #3756 希望将 @crawlee/memory-storage 合并到 @crawlee/core，这反映出 src/ 模块之间的边界划分正在持续演进。

浏览器池（Browser Pool）src 模块

packages/browser-pool/src/ 是整个爬虫体系浏览器管理的核心入口。其中 browser-pool.ts 定义了 BrowserPool 类，是浏览器生命周期最重要的管理器，支持多种生命周期钩子（preLaunchHooks、postLaunchHooks、prePageCreateHooks 等）packages/browser-pool/src/browser-pool.ts:1-50。这些钩子使得开发者能够在浏览器启动、页面创建、关闭等各阶段插入自定义逻辑。

launch-context.ts 定义了 LaunchContext 类，封装了一次浏览器启动所需的全部配置，包括 browserPlugin、launchOptions、proxyUrl、useIncognitoPages、experimentalContainers、userDataDir 等关键字段 packages/browser-pool/src/launch-context.ts:1-30。值得注意的是，experimentalContainers 选项虽然能借助持久化上下文加速加载，但官方标注"Works best with Firefox. Unstable on Chromium"，提醒用户在 Chromium 中谨慎使用 packages/browser-pool/src/launch-context.ts:18-22。

abstract-classes/browser-controller.ts 定义了浏览器控制器的抽象基类 BrowserController，通过 TypeScript 泛型同时支持 Playwright 和 Puppeteer 两套底层库，并暴露了 browserPlugin、browser、launchContext、proxyTier、proxyUrl 等公共属性 packages/browser-pool/src/abstract-classes/browser-controller.ts:1-35。这种抽象设计使得上层 Crawler 类可以无差别地操作不同浏览器实现。

graph TD
    A[BrowserPool 浏览器池] --> B[LaunchContext 启动上下文]
    A --> C[BrowserController 浏览器控制器]
    B --> D[BrowserPlugin 浏览器插件]
    C --> D
    D --> E[Playwright 底层库]
    D --> F[Puppeteer 底层库]
    C --> G[Page 页面实例]

爬虫内部分析（Internals）src 模块

各 Crawler 子包均将内部实现统一收敛到 src/internals/ 目录下，以便对外暴露稳定 API。例如 packages/playwright-crawler/src/internals/utils/playwright-utils.ts 提供了 compileScript 工具函数，使用 vm.runInNewContext 在隔离上下文中执行脚本字符串，并显式构造无原型链的 Object.create(null) 作为默认上下文以增强安全性 packages/playwright-crawler/src/internals/utils/playwright-utils.ts:1-30。该函数被编译为接收 { page, request } 的异步函数并返回其执行结果。

类似地，packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts 提供了诸如点击元素并拦截导航请求的工具方法，在注释中明确指出"USING HEADFUL BROWSER: When using a headful browser, this function will only be able to click elements in the focused tab, effectively limiting concurrency to 1"，表明无头模式才能发挥完整并发性能 packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts:1-30。

社区讨论中曾出现 #3764 关于"畸形 userData 导致 Crawler 永久挂起"的问题，其根本原因就在于 requestLike 在进入 RequestQueue 之前未能在 src/internals/ 中进行严格的形状校验，这一缺陷提示了内部分析模块仍需加强输入校验。

通用工具（Utils）src 模块

packages/utils/src/ 提供了跨 Crawler 复用的纯函数与解析器。internals/open_graph_parser.ts 中的 parseOpenGraph 函数支持字符串或 Cheerio CheerioAPI 两种入参形式，并将 OpenGraph 属性与用户自定义 additionalProperties 合并后归约为 Dictionary<OpenGraphResult> packages/utils/src/internals/open_graph_parser.ts:1-30。

packages/utils/package.json 明确了该包的版本、入口（./dist/index.js、./dist/index.mjs）、engines.node >=16.0.0 等元数据，并使用 gen-esm-wrapper 生成 ESM 入口 packages/utils/package.json:1-30。这种 ESM/CJS 双发布模式已被 @crawlee/* 全系采用，便于在 Node.js 与现代构建工具下消费。

高级 Crawler 与模板入口

packages/stagehand-crawler/README.md 描述了基于 Stagehand 的 AI 驱动爬虫，扩展了 BrowserCrawler，并通过 page.act()、page.extract()、page.observe() 三个自然语言接口操作页面 packages/stagehand-crawler/README.md:1-10。其 apiKey 选项根据 env 设置解释为本地 LLM Key 或 Browserbase Key。

packages/http-crawler/package.json 显示 HTTP 爬虫包依赖了 got-scraping、iconv-lite、content-type、mime-types 等 HTTP 处理库，奠定了与底层网络请求库解耦的设计 packages/http-crawler/package.json:1-25。

See Also

• BrowserCrawler 概览
• PlaywrightCrawler 文档
• PuppeteerCrawler 文档
• CheerioCrawler 指南
• 自适应爬虫指南

Pitfall Log / 踩坑日志

项目：apify/crawlee

摘要：发现 22 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：维护坑 - 来源证据：Add support for Bun runtime - Issue with browser-pool and memory-storage packages。

1. 维护坑 · 来源证据：Add support for Bun runtime - Issue with `browser-pool` and `memory-storage` packages

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Add support for Bun runtime - Issue with browser-pool and memory-storage packages
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/apify/crawlee/issues/2046 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 配置坑 · 失败模式：configuration: v3.15.1

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v3.15.1
• 对用户的影响：Upgrade or migration may change expected behavior: v3.15.1
• 证据：failure_mode_cluster:github_release | https://github.com/apify/crawlee/releases/tag/v3.15.1 | v3.15.1

3. 配置坑 · 失败模式：configuration: v3.16.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v3.16.0
• 对用户的影响：Upgrade or migration may change expected behavior: v3.16.0
• 证据：failure_mode_cluster:github_release | https://github.com/apify/crawlee/releases/tag/v3.16.0 | v3.16.0

4. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/apify/crawlee | README/documentation is current enough for a first validation pass.

5. 运行坑 · 失败模式：runtime: v3.15.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: v3.15.0
• 对用户的影响：Upgrade or migration may change expected behavior: v3.15.0
• 证据：failure_mode_cluster:github_release | https://github.com/apify/crawlee/releases/tag/v3.15.0 | v3.15.0

6. 运行坑 · 失败模式：runtime: v3.15.3

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: v3.15.3
• 对用户的影响：Upgrade or migration may change expected behavior: v3.15.3
• 证据：failure_mode_cluster:github_release | https://github.com/apify/crawlee/releases/tag/v3.15.3 | v3.15.3

7. 运行坑 · 失败模式：runtime: v3.17.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: v3.17.0
• 对用户的影响：Upgrade or migration may change expected behavior: v3.17.0
• 证据：failure_mode_cluster:github_release | https://github.com/apify/crawlee/releases/tag/v3.17.0 | v3.17.0

8. 运行坑 · 来源证据：Crawler hangs forever when given malformed request input (e.g. invalid `userData` shape)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Crawler hangs forever when given malformed request input (e.g. invalid userData shape)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/apify/crawlee/issues/3764 | 来源类型 github_issue 暴露的待验证使用条件。

9. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/apify/crawlee | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/apify/crawlee | no_demo; severity=medium

11. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/apify/crawlee | no_demo; severity=medium

12. 能力坑 · 失败模式：capability: Allow disabling ImpitHttpClient client cache

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Allow disabling ImpitHttpClient client cache
• 对用户的影响：Developers may hit a documented source-backed failure mode: Allow disabling ImpitHttpClient client cache
• 证据：failure_mode_cluster:github_issue | https://github.com/apify/crawlee/issues/3769 | Allow disabling ImpitHttpClient client cache

13. 能力坑 · 失败模式：capability: Crawler hangs forever when given malformed request input (e.g. invalid `userData` shape)

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Crawler hangs forever when given malformed request input (e.g. invalid userData shape)
• 对用户的影响：Developers may hit a documented source-backed failure mode: Crawler hangs forever when given malformed request input (e.g. invalid userData shape)
• 证据：failure_mode_cluster:github_issue | https://github.com/apify/crawlee/issues/3764 | Crawler hangs forever when given malformed request input (e.g. invalid userData shape)

14. 运行坑 · 失败模式：performance: Add support for Bun runtime - Issue with `browser-pool` and `memory-storage` packages

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: Add support for Bun runtime - Issue with browser-pool and memory-storage packages
• 对用户的影响：Developers may hit a documented source-backed failure mode: Add support for Bun runtime - Issue with browser-pool and memory-storage packages
• 证据：failure_mode_cluster:github_issue | https://github.com/apify/crawlee/issues/2046 | Add support for Bun runtime - Issue with browser-pool and memory-storage packages

15. 运行坑 · 失败模式：performance: Merge @crawlee/memory-storage package into @crawlee/core

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: Merge @crawlee/memory-storage package into @crawlee/core
• 对用户的影响：Developers may hit a documented source-backed failure mode: Merge @crawlee/memory-storage package into @crawlee/core
• 证据：failure_mode_cluster:github_issue | https://github.com/apify/crawlee/issues/3756 | Merge @crawlee/memory-storage package into @crawlee/core

16. 运行坑 · 失败模式：performance: v3.15.2

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: v3.15.2
• 对用户的影响：Upgrade or migration may change expected behavior: v3.15.2
• 证据：failure_mode_cluster:github_release | https://github.com/apify/crawlee/releases/tag/v3.15.2 | v3.15.2

17. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/apify/crawlee | issue_or_pr_quality=unknown

18. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/apify/crawlee | release_recency=unknown

19. 维护坑 · 失败模式：maintenance: v3.13.10

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v3.13.10
• 对用户的影响：Upgrade or migration may change expected behavior: v3.13.10
• 证据：failure_mode_cluster:github_release | https://github.com/apify/crawlee/releases/tag/v3.13.10 | v3.13.10

20. 维护坑 · 失败模式：maintenance: v3.13.9

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v3.13.9
• 对用户的影响：Upgrade or migration may change expected behavior: v3.13.9
• 证据：failure_mode_cluster:github_release | https://github.com/apify/crawlee/releases/tag/v3.13.9 | v3.13.9

21. 维护坑 · 失败模式：maintenance: v3.14.0

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v3.14.0
• 对用户的影响：Upgrade or migration may change expected behavior: v3.14.0
• 证据：failure_mode_cluster:github_release | https://github.com/apify/crawlee/releases/tag/v3.14.0 | v3.14.0

22. 维护坑 · 失败模式：maintenance: v3.14.1

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v3.14.1
• 对用户的影响：Upgrade or migration may change expected behavior: v3.14.1
• 证据：failure_mode_cluster:github_release | https://github.com/apify/crawlee/releases/tag/v3.14.1 | v3.14.1