# https://github.com/apify/crawlee 项目说明书

生成时间：2026-06-20 16:26:57 UTC

## 目录

- [项目概览](#page-overview)
- [Src 模块](#page-website-src)
- [Src 模块](#page-packages-memory-storage-src)
- [Src 模块](#page-packages-browser-pool-src)

<a id='page-overview'></a>

## 项目概览

### 相关页面

相关主题：[Src 模块](#page-website-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/apify/crawlee/blob/main/package.json)
- [packages/stagehand-crawler/README.md](https://github.com/apify/crawlee/blob/main/packages/stagehand-crawler/README.md)
- [packages/http-crawler/package.json](https://github.com/apify/crawlee/blob/main/packages/http-crawler/package.json)
- [packages/browser-pool/src/browser-pool.ts](https://github.com/apify/crawlee/blob/main/packages/browser-pool/src/browser-pool.ts)
- [packages/browser-pool/src/abstract-classes/browser-controller.ts](https://github.com/apify/crawlee/blob/main/packages/browser-pool/src/abstract-classes/browser-controller.ts)
- [packages/browser-pool/src/launch-context.ts](https://github.com/apify/crawlee/blob/main/packages/browser-pool/src/launch-context.ts)
- [packages/playwright-crawler/src/internals/utils/playwright-utils.ts](https://github.com/apify/crawlee/blob/main/packages/playwright-crawler/src/internals/utils/playwright-utils.ts)
- [packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts](https://github.com/apify/crawlee/blob/main/packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts)
- [packages/utils/src/internals/open_graph_parser.ts](https://github.com/apify/crawlee/blob/main/packages/utils/src/internals/open_graph_parser.ts)
- [packages/templates/templates/cheerio-ts/README.md](https://github.com/apify/crawlee/blob/main/packages/templates/templates/cheerio-ts/README.md)
- [packages/templates/templates/playwright-ts/README.md](https://github.com/apify/crawlee/blob/main/packages/templates/templates/playwright-ts/README.md)
- [packages/templates/templates/puppeteer-ts/README.md](https://github.com/apify/crawlee/blob/main/packages/templates/templates/puppeteer-ts/README.md)
- [packages/templates/templates/camoufox-ts/README.md](https://github.com/apify/crawlee/blob/main/packages/templates/templates/camoufox-ts/README.md)
- [packages/templates/templates/empty-ts/package.json](https://github.com/apify/crawlee/blob/main/packages/templates/templates/empty-ts/package.json)
- [website/src/pages/js.js](https://github.com/apify/crawlee/blob/main/website/src/pages/js.js)
</details>

# 项目概览

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/http-crawler` | 包 | 基于 `got-scraping` 的 HTTP 抓取内核 |
| `@crawlee/browser-pool` | 包 | 浏览器/页面生命周期、Launch 上下文管理 |
| `@crawlee/stagehand-crawler` | 包 | 封装 Stagehand，支持自然语言 `act`/`extract`/`observe` |
| `cheerio-js` / `cheerio-ts` | 模板 | CheerioCrawler 起步项目 |
| `playwright-js` / `playwright-ts` | 模板 | PlaywrightCrawler 起步项目 |
| `puppeteer-js` / `puppeteer-ts` | 模板 | PuppeteerCrawler 起步项目 |
| `camoufox-ts` | 模板 | PlaywrightCrawler + Camoufox 反指纹浏览器 |

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

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]()）。

```mermaid
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` 固定 `yarn@4.10.3`，统一工程链路（资料来源：[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 渲染类型持久化等稳定性改进，体现了"抓取正确性 > 抓取速度"的持续投入。

## 参见

- [基础爬虫与请求生命周期](./basic-crawler.md)
- [浏览器池与 LaunchContext](./browser-pool.md)
- [Playwright / Puppeteer 集成](./browser-crawlers.md)
- [HTTP 抓取与 CheerioCrawler](./http-crawler.md)
- [Stagehand 与 AI 驱动爬虫](./stagehand-crawler.md)

---

<a id='page-website-src'></a>

## Src 模块

### 相关页面

相关主题：[项目概览](#page-overview), [Src 模块](#page-packages-memory-storage-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/browser-pool/src/browser-pool.ts](https://github.com/apify/crawlee/blob/main/packages/browser-pool/src/browser-pool.ts)
- [packages/browser-pool/src/launch-context.ts](https://github.com/apify/crawlee/blob/main/packages/browser-pool/src/launch-context.ts)
- [packages/browser-pool/src/abstract-classes/browser-controller.ts](https://github.com/apify/crawlee/blob/main/packages/browser-pool/src/abstract-classes/browser-controller.ts)
- [packages/playwright-crawler/src/internals/utils/playwright-utils.ts](https://github.com/apify/crawlee/blob/main/packages/playwright-crawler/src/internals/utils/playwright-utils.ts)
- [packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts](https://github.com/apify/crawlee/blob/main/packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts)
- [packages/utils/src/internals/open_graph_parser.ts](https://github.com/apify/crawlee/blob/main/packages/utils/src/internals/open_graph_parser.ts)
- [packages/crawlee/package.json](https://github.com/apify/crawlee/blob/main/packages/crawlee/package.json)
- [packages/utils/package.json](https://github.com/apify/crawlee/blob/main/packages/utils/package.json)
- [packages/http-crawler/package.json](https://github.com/apify/crawlee/blob/main/packages/http-crawler/package.json)
- [packages/stagehand-crawler/README.md](https://github.com/apify/crawlee/blob/main/packages/stagehand-crawler/README.md)
- [package.json](https://github.com/apify/crawlee/blob/main/package.json)
</details>

# Src 模块

## 概述与整体架构

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](https://github.com/apify/crawlee/issues/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 类可以无差别地操作不同浏览器实现。

```mermaid
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]()。

| 子包 | src 主要职责 | 典型文件 |
|------|--------------|----------|
| `@crawlee/browser-pool` | 浏览器生命周期管理 | `browser-pool.ts`, `launch-context.ts` |
| `@crawlee/playwright-crawler` | Playwright 封装与内部分析 | `internals/utils/playwright-utils.ts` |
| `@crawlee/puppeteer-crawler` | Puppeteer 封装与内部分析 | `internals/utils/puppeteer_utils.ts` |
| `@crawlee/utils` | 通用工具与解析器 | `internals/open_graph_parser.ts` |
| `@crawlee/stagehand-crawler` | AI 驱动浏览器自动化 | `README.md` (StagehandCrawler) |

## See Also

- [BrowserCrawler 概览](https://crawlee.dev/js/api/browser-crawler/class/BrowserCrawler)
- [PlaywrightCrawler 文档](https://crawlee.dev/js/api/playwright-crawler/class/PlaywrightCrawler)
- [PuppeteerCrawler 文档](https://crawlee.dev/js/api/puppeteer-crawler/class/PuppeteerCrawler)
- [CheerioCrawler 指南](https://crawlee.dev/js/docs/guides/cheerio-crawler-guide)
- [自适应爬虫指南](https://crawlee.dev/js/docs/guides/adaptive-crawler-guide)

---

<a id='page-packages-memory-storage-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-website-src), [Src 模块](#page-packages-browser-pool-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/apify/crawlee/blob/main/package.json)
- [packages/crawlee/package.json](https://github.com/apify/crawlee/blob/main/packages/crawlee/package.json)
- [packages/http-crawler/package.json](https://github.com/apify/crawlee/blob/main/packages/http-crawler/package.json)
- [packages/utils/package.json](https://github.com/apify/crawlee/blob/main/packages/utils/package.json)
- [packages/browser-pool/src/browser-pool.ts](https://github.com/apify/crawlee/blob/main/packages/browser-pool/src/browser-pool.ts)
- [packages/browser-pool/src/launch-context.ts](https://github.com/apify/crawlee/blob/main/packages/browser-pool/src/launch-context.ts)
- [packages/browser-pool/src/abstract-classes/browser-controller.ts](https://github.com/apify/crawlee/blob/main/packages/browser-pool/src/abstract-classes/browser-controller.ts)
- [packages/playwright-crawler/src/internals/utils/playwright-utils.ts](https://github.com/apify/crawlee/blob/main/packages/playwright-crawler/src/internals/utils/playwright-utils.ts)
- [packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts](https://github.com/apify/crawlee/blob/main/packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts)
- [packages/utils/src/internals/open_graph_parser.ts](https://github.com/apify/crawlee/blob/main/packages/utils/src/internals/open_graph_parser.ts)
- [packages/stagehand-crawler/README.md](https://github.com/apify/crawlee/blob/main/packages/stagehand-crawler/README.md)
- [packages/templates/templates/puppeteer-js/README.md](https://github.com/apify/crawlee/blob/main/packages/templates/templates/puppeteer-js/README.md)
- [packages/templates/templates/playwright-js/README.md](https://github.com/apify/crawlee/blob/main/packages/templates/templates/playwright-js/README.md)
- [packages/templates/templates/cheerio-ts/README.md](https://github.com/apify/crawlee/blob/main/packages/templates/templates/cheerio-ts/README.md)
</details>

# Src 模块

## 仓库与工作区总体结构

Crawlee 是一个基于 Lerna + Yarn workspaces 的 JavaScript/Node.js 单仓多包（monorepo）项目，根目录的 `package.json` 中通过 `workspaces` 字段声明了所有子包均位于 `packages/*` 目录下。资料来源：[package.json](https://github.com/apify/crawlee/blob/main/package.json) 的 `"workspaces": ["packages/*"]` 与 `description` 字段说明其为「可扩展的网页抓取与爬取库（不仅限于）使用无头 Chrome 与 Puppeteer」。

在 `packages/` 下分布着多个独立发布的 npm 包，每个包都遵循一致的目录布局：`src/` 存放 TypeScript 源码，`dist/` 存放编译产物，`package.json` 声明入口（`main` / `module` / `types`）与依赖。例如：

- `@crawlee/crawlee`：聚合元包，依赖 `basic`、`browser`、`browser-pool`、`cheerio`、`cli`、`core`、`http`、`jsdom`、`linkedom`、`playwright`、`puppeteer` 等子包。
- `@crawlee/utils`：提供跨爬虫共享的辅助函数。
- `@crawlee/http-crawler`：基于 `got-scraping` 的 HTTP 爬取实现。

资料来源：[packages/crawlee/package.json](https://github.com/apify/crawlee/blob/main/packages/crawlee/package.json) 的 `dependencies` 字段、 [packages/http-crawler/package.json](https://github.com/apify/crawlee/blob/main/packages/http-crawler/package.json) 中 `"got-scraping": "^4.2.1"` 依赖项，以及 [packages/utils/package.json](https://github.com/apify/crawlee/blob/main/packages/utils/package.json) 中 `"description": "A set of shared utilities that can be used by crawlers"`。

## 浏览器池核心模块

`packages/browser-pool/src/` 是管理浏览器与页面生命周期的核心子模块。其导出类型 `BrowserPool` 是整个模块最重要的类，构造选项支持 `preLaunchHooks`、`postLaunchHooks`、`prePageCreateHooks`、`postPageCreateHooks`、`prePageCloseHooks`、`postPageCloseHooks` 等多个生命周期钩子，用于在浏览器/页面的不同阶段顺序执行异步函数。资料来源：[packages/browser-pool/src/browser-pool.ts](https://github.com/apify/crawlee/blob/main/packages/browser-pool/src/browser-pool.ts) 中的 JSDoc 注释及 `lifecycle hooks` 字段说明。

`LaunchContext` 描述单次浏览器启动的配置与上下文，包含 `browserPlugin`、`launchOptions`、`browserPerProxy`、`useIncognitoPages`、`experimentalContainers`、`userDataDir`、`proxyUrl`、`proxyTier` 等字段。其中 `useIncognitoPages` 让每个页面使用独立浏览器上下文，`experimentalContainers`（实验性）则利用持久化上下文实现更快的二次加载（Chromium 上不稳定）。资料来源：[packages/browser-pool/src/launch-context.ts](https://github.com/apify/crawlee/blob/main/packages/browser-pool/src/launch-context.ts) 的字段 JSDoc。

`BrowserController` 位于 `abstract-classes/` 子目录下，是 `PlaywrightController` / `PuppeteerController` 等专用控制器的抽象基类，统一暴露 `id`、`browserPlugin`、`browser`、`launchContext`、`proxyTier` 等公共接口，便于在保持封装的前提下实现多库兼容。资料来源：[packages/browser-pool/src/abstract-classes/browser-controller.ts](https://github.com/apify/crawlee/blob/main/packages/browser-pool/src/abstract-classes/browser-controller.ts) 的类签名与 `id = nanoid()` 初始化逻辑。

## 爬虫实现与工具子模块

`packages/playwright-crawler/src/internals/utils/playwright-utils.ts` 提供 `compileScript(scriptString, context)`，将字符串形式的脚本体编译为 `async ({ page, request }) => {…}` 函数，并在 `vm.runInNewContext` 中执行以隔离 `process`、`require` 等全局变量；为缓解原型链攻击，建议传入经过安全清洗的自定义 `context`。资料来源：[packages/playwright-crawler/src/internals/utils/playwright-utils.ts](https://github.com/apify/crawlee/blob/main/packages/playwright-crawler/src/internals/utils/playwright-utils.ts) 的实现与安全说明注释。

`packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts` 提供 Puppeteer 场景的辅助函数（如 `enqueueLinksByClickingElements`），通过模拟鼠标移动与点击拦截后续导航请求并入队到 `RequestQueue`，适用于 JS 驱动跳转、链接触发在 `click` 处理器中的页面；该函数会修改页面元素 Z-index 与可见性，因此推荐作为页面上的最后一步操作。资料来源：[packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts](https://github.com/apify/crawlee/blob/main/packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts) 的 JSDoc 性能与使用约束说明。

`packages/stagehand-crawler/src/` 是基于 [Stagehand](https://github.com/browserbase/stagehand) 的 AI 驱动爬虫实现，其增强的 `page` 对象支持 `page.act()`（自然语言操作）、`page.extract()`（基于 Zod schema 的结构化抽取）以及 `page.observe()`（动作发现）。当目标站点结构频繁变化时可优先选用此类爬虫；若结构稳定，则推荐使用更快的 `PlaywrightCrawler` 而无需 AI API 密钥。资料来源：[packages/stagehand-crawler/README.md](https://github.com/apify/crawlee/blob/main/packages/stagehand-crawler/README.md) 的功能说明与适用场景段落。

## 共享工具与项目模板

`packages/utils/src/internals/open_graph_parser.ts` 暴露 `parseOpenGraph(item, additionalProperties)`，支持传入原始 HTML 字符串或 Cheerio 实例，并允许通过 `additionalProperties` 追加自定义 `OpenGraphProperty`。资料来源：[packages/utils/src/internals/open_graph_parser.ts](https://github.com/apify/crawlee/blob/main/packages/utils/src/internals/open_graph_parser.ts) 的函数重载与 `OPEN_GRAPH_PROPERTIES` 合并逻辑。

`packages/templates/templates/` 下提供开箱即用的项目骨架，例如 `puppeteer-js`（PuppeteerCrawler + JavaScript）、`puppeteer-ts`（PuppeteerCrawler + TypeScript）、`playwright-js`、`playwright-ts`、`cheerio-js`、`cheerio-ts` 与最小化的 `empty-ts`，分别对应不同的爬虫类型与语言偏好，每个模板自带 `start`、`build`、`test` 脚本及 `@apify/tsconfig`、`tsx` 等开发依赖。资料来源：[packages/templates/templates/puppeteer-js/README.md](https://github.com/apify/crawlee/blob/main/packages/templates/templates/puppeteer-js/README.md)、[packages/templates/templates/playwright-ts/README.md](https://github.com/apify/crawlee/blob/main/packages/templates/templates/playwright-ts/README.md) 与 [packages/templates/templates/cheerio-ts/README.md](https://github.com/apify/crawlee/blob/main/packages/templates/templates/cheerio-ts/README.md) 的模板说明。

下表汇总了主要 `src/` 子包及其核心职责：

| 子包 | 核心源码 | 主要职责 |
| --- | --- | --- |
| `@crawlee/browser-pool` | `src/browser-pool.ts`、`src/launch-context.ts`、`src/abstract-classes/browser-controller.ts` | 浏览器/页面生命周期与代理管理 |
| `@crawlee/playwright-crawler` | `src/internals/utils/playwright-utils.ts` | Playwright 专用工具与脚本编译沙箱 |
| `@crawlee/puppeteer-crawler` | `src/internals/utils/puppeteer_utils.ts` | Puppeteer 专用工具（点击入链、上下文脚本） |
| `@crawlee/stagehand-crawler` | `README.md`、包内 `src/` | 基于 LLM 的自然语言浏览器自动化 |
| `@crawlee/utils` | `src/internals/open_graph_parser.ts` 等 | 跨爬虫共享的 HTML 解析与辅助函数 |
| `templates/templates/*` | 各模板 `package.json` | 脚手架，绑定 `tsx` / `typescript` / `@apify/tsconfig` |

## 常见陷阱与社区关注点

在向 `crawler.run()` 传入畸形 `requestLike`（例如缺少 `url` 的对象）时，爬虫可能反复重试入队而长时间挂起而非快速失败；社区已在 issue #3764 中报告该行为，并建议在 `run()` 入口增加输入校验。资料来源：[community context issue #3764](https://github.com/apify/crawlee/issues/3764)。此外，针对 `ImpitHttpClient` 等 HTTP 客户端，issue #3769 提议暴露 `cacheClients` 选项以禁用客户端级连接缓存，可通过在 `getClient()` 中分支处理实现。

## 另请参阅

- [BrowserCrawler API](https://crawlee.dev/js/api/browser-crawler/class/BrowserCrawler)
- [PlaywrightCrawler API](https://crawlee.dev/js/api/playwright-crawler/class/PlaywrightCrawler)
- [PuppeteerCrawler API](https://crawlee.dev/js/api/puppeteer-crawler/class/PuppeteerCrawler)
- [CheerioCrawler 教程](https://crawlee.dev/js/docs/guides/cheerio-crawler-guide)
- [v3.17.0 发布说明](https://github.com/apify/crawlee/releases/tag/v3.17.0)

---

<a id='page-packages-browser-pool-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-packages-memory-storage-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/browser-pool/src/browser-pool.ts](https://github.com/apify/crawlee/blob/main/packages/browser-pool/src/browser-pool.ts)
- [packages/browser-pool/src/launch-context.ts](https://github.com/apify/crawlee/blob/main/packages/browser-pool/src/launch-context.ts)
- [packages/browser-pool/src/abstract-classes/browser-controller.ts](https://github.com/apify/crawlee/blob/main/packages/browser-pool/src/abstract-classes/browser-controller.ts)
- [packages/playwright-crawler/src/internals/utils/playwright-utils.ts](https://github.com/apify/crawlee/blob/main/packages/playwright-crawler/src/internals/utils/playwright-utils.ts)
- [packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts](https://github.com/apify/crawlee/blob/main/packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts)
- [packages/utils/src/internals/open_graph_parser.ts](https://github.com/apify/crawlee/blob/main/packages/utils/src/internals/open_graph_parser.ts)
- [packages/stagehand-crawler/README.md](https://github.com/apify/crawlee/blob/main/packages/stagehand-crawler/README.md)
- [packages/templates/templates/playwright-ts/README.md](https://github.com/apify/crawlee/blob/main/packages/templates/templates/playwright-ts/README.md)
- [package.json](https://github.com/apify/crawlee/blob/main/package.json)
- [packages/crawlee/package.json](https://github.com/apify/crawlee/blob/main/packages/crawlee/package.json)

</details>

# Src 模块

## 模块定位与范围

`Src 模块` 指的是 Crawlee monorepo 中各包（package）的 `src/` 源码目录，它承担着整个爬虫框架的核心实现职责。Crawlee 在仓库根目录的 `package.json` 中声明了 `workspaces: ["packages/*"]`，将所有功能划分为独立的包来协同工作（资料来源：[package.json:15-17]()）。每一个具体的爬虫实现、HTTP 客户端抽象、浏览器生命周期管理逻辑以及共享工具函数，均由对应包内的 `src/` 目录承载并对外导出。

整个 monorepo 涵盖从浏览器自动化（Playwright / Puppeteer / Stagehand）到 HTTP（HttpCrawler、CheerioCrawler）等多种抓取方式。`Src 模块` 既包括核心抽象类（如 `BrowserPool`、`BrowserController`），也包括面向用户的工具函数（如 Open Graph 解析、脚本编译）。这种组织方式使得用户可以按需引入子包，而不必加载全部依赖。

## 浏览器池源码组织（browser-pool）

`packages/browser-pool/src/` 是浏览器生命周期管理的核心目录，其内部按职责细分为多个子目录和文件。`BrowserPool` 类负责管理浏览器的打开与关闭，并允许通过生命周期钩子（lifecycle hooks）介入每个阶段（资料来源：[packages/browser-pool/src/browser-pool.ts:30-60]()）。`LaunchContext` 则记录了每次浏览器启动的实际配置，包括 `launchOptions`、`proxyUrl` 等字段，便于在同一浏览器实例内的多个页面间共享设置（资料来源：[packages/browser-pool/src/launch-context.ts:10-40]()）。

抽象类方面，`BrowserController` 提供了与底层自动化库解耦的统一接口，子类（如 PlaywrightController、PuppeteerController）通过实现这一接口来桥接不同浏览器 API（资料来源：[packages/browser-pool/src/abstract-classes/browser-controller.ts:10-30]()）。

下面的流程图展示了 `BrowserPool` 在启动一个新页面时各源码模块之间的协作关系：

```mermaid
sequenceDiagram
    participant User as 调用方
    participant Pool as BrowserPool
    participant LC as LaunchContext
    participant BC as BrowserController
    participant Lib as 自动化库
    User->>Pool: newPage()
    Pool->>LC: 读取/创建 launchContext
    LC-->>Pool: 返回配置
    Pool->>BC: 触发 preLaunchHooks / postLaunchHooks
    BC->>Lib: chromium.launch(launchOptions)
    Lib-->>BC: 返回 Browser 实例
    BC-->>Pool: 创建 Page 并执行 prePageCreateHooks
    Pool-->>User: 返回 Page
```

社区中曾反馈 `browser-pool` 在 Bun 运行时下存在兼容性问题（参考 [#2046](https://github.com/apify/crawlee/issues/2046)），主要体现在 `useIncognitoPages` 等选项与 Bun 的浏览器 API 不兼容；这正说明 `src/` 中的实现与运行时深度耦合。

## 爬虫工具源码

`packages/playwright-crawler/src/internals/utils/playwright-utils.ts` 暴露了 `compileScript` 等工具，它使用 `vm.runInNewContext` 在受限上下文中执行用户提供的字符串函数体，并返回异步结果（资料来源：[packages/playwright-crawler/src/internals/utils/playwright-utils.ts:15-25]()）。类似地，`packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts` 提供 `interceptClick` 等高阶交互工具，通过模拟鼠标移动和点击拦截导航请求，从而发现 JS 动态生成的链接（资料来源：[packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts:1-15]()）。

这些工具的源码组织遵循 "internals/utils" 命名约定，将仅供包内部使用、不作为稳定公共 API 的辅助函数收敛在同一目录下，便于与面向用户的导出 API 区分。

## 共享工具与模板源码

`packages/utils/src/internals/open_graph_parser.ts` 实现了对 Open Graph 元数据的解析，支持传入 HTML 字符串或 Cheerio 对象，并允许通过 `additionalProperties` 扩展识别范围（资料来源：[packages/utils/src/internals/open_graph_parser.ts:1-20]()）。

`packages/templates/templates/` 下提供多语言、多爬虫类型的脚手架模板，每个模板的 `package.json` 均以 `crawlee` 作为唯一依赖（如 `empty-ts` 模板，[packages/templates/templates/empty-ts/package.json:6-12]()），并通过 `start:dev` 脚本使用 `tsx` 直接执行 TypeScript 源码。这种轻量化的模板结构使得用户能够快速进入实际业务开发，而无需关心框架源码。

下表列出了 `Src 模块` 中最关键的几个目录及其承担职责：

| 源码目录 | 主要职责 |
| --- | --- |
| `packages/browser-pool/src/` | 浏览器与页面生命周期、代理、上下文管理 |
| `packages/playwright-crawler/src/internals/utils/` | Playwright 专属工具（脚本编译、注入等） |
| `packages/puppeteer-crawler/src/internals/utils/` | Puppeteer 专属工具（点击拦截等） |
| `packages/utils/src/internals/` | 跨包共享工具（Open Graph、正则等） |
| `packages/templates/templates/*/` | 各类脚手架模板（cheerio-js、playwright-ts 等） |

## 已知问题与演进方向

社区中针对 `Src 模块` 提出了若干演进建议，例如 [#3756](https://github.com/apify/crawlee/issues/3756) 提议将 `@crawlee/memory-storage` 合并进 `@crawlee/core`，理由是相关代码量不大且无额外依赖，应统一收敛到核心包的 `src/` 目录中。此外，v3.17.0 修复了 `discoverValidSitemaps` 中可能导致的无限挂起问题（[#3429](https://github.com/apify/crawlee/issues/3429)），以及 `PuppeteerPlugin` 中 `Browser.pages()` 绑定错误的问题——这两处修复均集中在 `src/` 内部源码侧，反映了核心模块稳定性是社区关注重点。

## See Also

- [BrowserPool 浏览器池](https://crawlee.dev/js/api/browser-pool/class/BrowserPool)
- [PlaywrightCrawler](https://crawlee.dev/js/api/playwright-crawler/class/PlaywrightCrawler)
- [PuppeteerCrawler](https://crawlee.dev/js/api/puppeteer-crawler/class/PuppeteerCrawler)
- [@crawlee/utils API 参考](https://crawlee.dev/js/api/utils)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: apify/crawlee; human_manual_source: deepwiki_human_wiki -->