Crawlee 版本演进全解析从 Apify SDK 到 v3.18 的核心变更与技术脉络【免费下载链接】crawleeCrawlee—A web scraping and browser automation library for Node.js to build reliable crawlers. In JavaScript and TypeScript. Extract data for AI, LLMs, RAG, or GPTs. Download HTML, PDF, JPG, PNG, and other files from websites. Works with Puppeteer, Playwright, Cheerio, JSDOM, and raw HTTP. Both headful and headless mode. With proxy rotation.项目地址: https://gitcode.com/GitHub_Trending/cr/crawleeCrawlee 是面向 Node.js 的 Web 爬取与浏览器自动化库支持 Cheerio、JSDOM、LinkeDOM、Puppeteer、Playwright 与原生 HTTP 等多种执行环境。本篇基于仓库根目录的 CHANGELOG.md记录了 v2.0.0 至 v3.18.1 的完整变更历史展开梳理 Crawlee 从 Apify SDK 中独立、完成 v3 大版本重构再到后续持续迭代的演进脉络。读者将理解 Crawlee 的包体系设计、关键 API 的命名与语义变化、请求队列/链接入队/会话代理等核心机制的演进以及如何结合 MIGRATIONS.md 与 docs/upgrading/ 目录完成版本升级。一、项目背景Crawlee 与 Apify SDK 的分家Crawlee 是 Apify SDKapify包在爬取与浏览器自动化方向上的精神继承者。正如 CHANGELOG 在 v3.0.0 一节中说明的v3 之前apify包同时包含爬取工具与 Apify 平台辅助方法v3 起将整个项目拆分为两部分Crawlee新的 Web 爬取库以crawlee包在 NPM 发布Apify SDKApify 平台辅助工具以apify包发布。拆分后Crawlee 以crawlee命名空间发布多个子包。从当前仓库 packages/ 目录可以确认这套体系至今仍在沿用并且已经进一步细化为包名职责crawlee/core所有爬虫实现的基础包含Request、RequestQueue、RequestList、Dataset等核心类crawlee/basic导出BasicCrawler即 packages/basic-crawlercrawlee/cheerio导出CheerioCrawlerpackages/cheerio-crawlercrawlee/browser导出BrowserCrawler是crawlee/playwright与crawlee/puppeteer的基类crawlee/playwright/crawlee/puppeteer导出PlaywrightCrawler/PuppeteerCrawlercrawlee/jsdom/crawlee/linkedom导出JSDOMCrawler/LinkeDOMCrawlercrawlee/http导出HttpCrawlerpackages/http-crawlercrawlee/memory-storage/crawlee/fs-storage存储实现packages/fs-storagecrawlee/browser-pool浏览器池packages/browser-poolcrawlee/utils工具方法packages/utilscrawlee/types主要存放StorageClient相关 TS 接口crawlee/stagehandAI 驱动的浏览器自动化v3.16 新增packages/stagehand-crawlercrawlee/otelOpenTelemetry 可观测性集成packages/otel各包之间相互扩展并重导出因此只需安装你实际使用的那个包即可。例如安装crawlee/playwright会自动带上crawlee/browser进而带上crawlee/basic与crawlee/core。同时crawlee元包packages/crawlee会重导出大多数crawlee/*内容方便一站式使用。值得注意的是当前仓库 lerna.json 中的发布版本为3.18.1而各子包 package.json 中已标记为4.0.0说明仓库正处在 v4 开发分支上CHANGELOG 记录的最新正式版本是 2026-08-12 发布的v3.18.1。二、v3.0 里程碑一次彻底的重构v3.0.02022-07-13是 CHANGELOG 中篇幅最大、信息量最高的一节它实质上是一份完整的从 v2 迁移到 v3指南以下要点必须掌握。2.1 安装方式v3 时代crawlee/*包尚未标记为latest需要从next分发标签安装npm install crawleenext # 仅需 Cheerio 支持时 npm install crawlee/cheerionext # 使用 Playwright / Puppeteer 时需显式安装浏览器驱动 npm install crawleenext playwright # 或 npm install crawlee/playwrightnext playwright这一显式安装浏览器依赖的设计一直延续到今天库本身不捆绑 Playwright/Puppeteer 版本由使用者自行控制。2.2 全量 TypeScript 支持Crawlee 与 Apify SDK 均为完全 TypeScript 重写类型随包发布。CHANGELOG 推荐使用apify/tsconfig预设并给出完整配置示例{ extends: apify/tsconfig, compilerOptions: { module: ES2022, target: ES2022, outDir: dist, lib: [DOM] }, include: [./src/**/*] }注意module/target需为ES2022及以上以支持顶层 awaitnoImplicitAny默认开启初期开发可能需临时关闭。2.3 Docker 多阶段构建CHANGELOG 给出了推荐的 Dockerfile 模式先用带开发依赖的基础镜像构建 TypeScript再拷贝产物到仅含生产依赖的最终镜像避免 TypeScript 等开发依赖进入运行镜像。2.4 浏览器指纹替代 stealthv2 中 Puppeteer 爬虫有一个魔法般的stealth选项v3 将其替换为动态生成的浏览器指纹。若想关闭动态指纹通过browserPoolOptions设置const crawler new PlaywrightCrawler({ browserPoolOptions: { useFingerprints: false, }, });v3.0 还说明指纹缓存选项从useFingerprintPerProxyCache更名为useFingerprintCache缓存不再绑定代理 URL而是绑定会话。对应实现位于 packages/browser-pool/src/fingerprinting/。2.5 会话 Cookie 方法重命名session.getPuppeteerCookies()/session.setPuppeteerCookies()更名为session.getCookies()/session.setCookies()因为该方法适用于所有爬虫而不仅是 Puppeteer。相关实现见 packages/core/src/session_pool/session.ts。2.6 存储memory-storage 与自动清理v3 默认使用crawlee/memory-storage内存存储 落盘 dump尊重 KVS 中已有的INPUT.json替代基于 SQLite 的apify/storage-local在 Apify 平台上运行时通过Actor.init/Actor.main自动切换到ApifyClient本地运行默认自动清理存储purge可通过Actor.init({ purge: false })关闭--purge参数不再是必须的。当前仓库中存储相关实现分布在 packages/core/src/storages/抽象与核心逻辑与 packages/fs-storage文件系统实现。2.7 爬虫选项与上下文接口重命名v3 统一了命名规范旧名仍被支持但不在 TS 层暴露旧名称新名称handleRequestFunction/handlePageFunctionrequestHandlerhandleRequestTimeoutSecs/handlePageTimeoutSecsrequestHandlerTimeoutSecsrequestTimeoutSecsnavigationTimeoutSecshandleFailedRequestFunctionfailedRequestHandler上下文接口同步更名CheerioHandlePageInputs→CheerioCrawlingContext、PlaywrightHandlePageFunction→PlaywrightCrawlingContext、PuppeteerHandlePageFunction→PuppeteerCrawlingContext。2.8 上下文感知的 enqueueLinks 与三种入队策略enqueueLinks从Apify.utils迁移到爬取上下文context aware不再需要手动传入requestQueue、page或$。同时提供三种策略EnqueueStrategy.Allall匹配页面上发现的任何 URLEnqueueStrategy.SameHostnamesame-hostname仅匹配与基准 URL 相同子域的链接默认EnqueueStrategy.SameDomainsame-domain匹配相同域名的链接例如基准 URL 为https://example.com时https://wow.an.example.com也会被匹配。无需任何参数即可调用enqueueLinks()默认过滤同子域链接还可用 glob 模式筛选const crawler new PlaywrightCrawler({ async requestHandler({ enqueueLinks }) { await enqueueLinks({ globs: [https://apify.com/*/*], // 也可使用 regexps 与 pseudoUrls }); }, });后续版本持续增强该助手exclude选项v3.3、所有变体支持forefrontv3.2、SameOrigin策略与协议匹配放宽v3.2、enqueueLinksByClickingElementsv3.1Playwright、waitForAllRequestsToBeAddedv3.10.4等。当前实现位于 packages/core/src/enqueue_links/。2.9 隐式 RequestQueue 与 crawler.addRequests()所有爬虫现在通过crawler.getRequestQueue()自动获得RequestQueue实例仍可显式传入方法会尊重传入实例。crawler.addRequests()则以 1000 个为一组批量入队先入队首批 1000 个并立即 resolve其余在后台继续避免触发 API 限流// 首批 1000 个请求入队后即 resolve const result await crawler.addRequests([/* 可以是数百万个 */]); // 如需等待全部入队完成 await result.waitForAllRequestsToBeAdded;从源码看packages/basic-crawler/src/internals/basic-crawler.ts 中addRequests是隐式RequestQueue.addRequestsBatched()的别名批量入队的底层实现在 packages/core/src/storages/batched_adds.ts 与 packages/core/src/storages/request_queue.ts。v3.10 还专门优化了crawler.addRequests()大批量入队性能v3.18 则修复了addRequestsBatched重复提交已入队请求与重试上限问题。2.10 requestAsBrowser 的移除与 sendRequestv3 移除requestAsBrowser改为直接使用got-scraping并新增上下文助手context.sendRequest()const crawler new BasicCrawler({ async requestHandler({ sendRequest, log }) { const res await sendRequest({ responseType: json }); log.info(received body, res.body); }, });同时整理了一批选项迁移payload→body/jsonignoreSslErrors→https.rejectUnauthorized语义相反默认falseuseMobileVersion/languageCode/countryCode→headerGeneratorOptionstimeoutSecs→timeout.request毫秒throwOnHttpErrors→throwHttpErrorsdecodeBody→decompressabortFunction被取消方案取代。当前仓库对应的 HTTP 客户端实现见 packages/http-client、packages/got-scraping-client 与 packages/impit-client。2.11 其他 v3 行为变化浏览器池禁止混合插件同一池中混用 Puppeteer 与 Playwright 插件将直接抛错跳过导航可用Request.skipNavigationcontext.sendRequest()在浏览器外处理请求对应示例 docs/examples/skip-navigation.mdx日志crawlee默认导出log实例上下文内提供带爬虫名前缀的log请求处理器内应优先使用自动保存状态每个爬虫都有crawler.useState()返回可自动持久化的状态对象persistState事件触发保存值有缓存const crawler new CheerioCrawler({ async requestHandler({ crawler }) { const state await crawler.useState({ foo: [] as number[] }); state.foo.push(123); // 无需手动保存 }, });Apify SDK 侧平台辅助方法Actor.init/exit/main、getInput、pushData、openDataset等归入apify包事件系统由EventManager管理packages/core/src/events/Actor.on/off替代Apify.events.on内部破坏性变更Request.handledAt改为 ISO 字符串Request.inProgress/reclaimed改为SetAPIFY_MEMORY_MBYTES由CRAWLEE_AVAILABLE_MEMORY_RATIO取代AutoscaledPool的部分选项上移至顶层配置等。三、v3.1 → v3.18 版本时间线关键新增特性CHANGELOG 记录了 v3 后续约两年半的迭代以下按主题提炼每个版本值得关注的能力括号内为对应源码/文档位置。3.1 请求来源与队列体系v3.5.5引入Request Queue v2RQv2此后 v3.10 将 RQv2 设为默认队列v3.13 进一步简化其实现v3.16 移除对RequestQueueV1的弃用标记v3.10.2支持从字符串加载 sitemapv3.11.0新增Sitemap 驱动的请求列表SitemapRequestListv3.11.2 为其加入globs/regexps过滤与弹性加载v3.13.3 支持周期性持久化状态对应实现 packages/core/src/storages/sitemap_request_loader.tsv3.13.9addRequests系列接受(Async)Iterablesv3.15.0新增TandemRequestProvider支持RequestList与RequestQueue组合使用packages/core/src/storages/request_manager_tandem.ts对应指南 docs/guides/request_loaders.mdx。3.2 入队与抓取控制v3.14.0新增maxCrawlDepth爬虫选项限制抓取深度v3.15.0 修复其与自定义transformRequestFunction的兼容v3.18.1 修复 JSDOM/LinkeDOM 上下文中对其的尊重v3.13.2新增onSkippedRequest回调用于报告因过滤条件被跳过的链接v3.13.9 完善v3.13.8不入队超过爬虫处理能力的链接数量v3.18.0enqueueLinksByClickingElements允许任意clickOptions。3.3 反检测与浏览器能力v3.13.0Playwright 新增handleCloudflareChallenge助手v3.16 使其更可配置v3.18.1 适配新的 Cloudflare 挑战标记v3.13.0新增Camoufox 爬虫模板packages/templates/templates/camoufox-ts/v3.13.3 默认关闭其指纹v3.6.1Puppeteer 启用新的 headless 模式v3.8.0 支持puppeteerv22v3.18.0 支持puppeteer25v3.9.1新增browserPerProxy浏览器启动选项v3.15.2默认启用systemInfoV2v3.17 新增动态内存快照v3.18 修复其 CPU tick 基线。3.4 代理与会话v3.9.0ProxyConfiguration新增tieredProxyUrls分层代理与更好的newUrlFunctionv3.12.1 支持传入null关闭代理v3.5.0新增sameDomainDelay、closeCookieModals上下文助手、代理错误自动退休会话v3.3.1 修复会话轮换问题v3.1.1concurrency选项覆盖顺序修复、会话标记为 bad 等相关实现见 packages/core/src/session_pool/ 与 packages/core/src/proxy_configuration.ts。3.5 爬虫家族扩张v3.0.3新增HttpCrawler与JSDOMCrawlerv3.4.0新增LinkeDOMCrawlerpackages/linkedom-crawlerv3.8.0新增AdaptivePlaywrightCrawler自适应渲染类型检测的爬虫后续持续完善持久化与结果比较器v3.13.5、v3.16.0v3.10.0新增FileDownload文件下载器v3.13.3 向streamHandler传入responsev3.17 新增abortDownload助手对应示例 docs/examples/file_download.mdxv3.16.0新增crawlee/stagehand支持 AI 驱动的浏览器自动化docs/guides/stagehand_crawler.mdx。3.6 存储、统计与可观测性v3.3.0新增setStatusMessage基础支持v3.5.0 支持配置自动状态消息v3.18.0 确保终止状态消息可靠送达v3.7.0新增 robots.txt 与 sitemap.xml 工具集packages/utils/src/internals/v3.13.1 将RobotsFile更名为RobotsTxtFilev3.15.3 支持自定义userAgentv3.10.0实现ErrorSnapshotter错误上下文快照packages/core/src/error_snapshotter.ts与 RQv2 默认化v3.12.0允许使用其他 HTTP 客户端v3.12.2 新增 impit 客户端v3.13.0 使用原生 impit 流式传输当前模板默认使用ImpitHttpClientv3.17v3.13.8 / v3.15.0Dataset 新增collectAllKeys全量 CSV 导出选项crawler.exportData()助手v3.6.0。四、源码级印证关键机制在今天仓库中的样子以 packages/basic-crawler/src/internals/basic-crawler.ts 为入口可以印证 CHANGELOG 中多项特性在 v4 分支上的延续skipNavigation、onSkippedRequest、sameDomainDelaySecs默认 0大于 0 时为每个站点建立独立节流时钟、maxCrawlDepth、respectRobotsTxtFile布尔或{ userAgent }默认false均作为构造选项存在与 CHANGELOG 中 v3.13.1/v3.13.2/v3.14.0/v3.15.3 的记载一一对应useState()实现了匿名索引去重与共享状态告警呼应 v3.0 的自动保存爬虫状态addRequests注释明确它是隐式RequestQueue.addRequestsBatched()的别名对应 v3.4.2 引入的批量入队 API。存储层面packages/core/src/storages/ 中request_queue.tsRQv2、request_manager_tandem.tsTandem、sitemap_request_loader.tsSitemapRequestList、batched_adds.ts批量入队等文件直接对应 CHANGELOG 中关于请求队列体系的一系列迭代。测试方面test/core/ 下的request_manager_tandem.test.ts、sitemap_request_loader.test.ts、test/core/storages/ 下的request_queue.test.ts等用例为这些机制提供了可执行佐证。五、升级路径与文档索引各版本完整变更细节均记录在 CHANGELOG.md当前最新记录 v3.18.1跨大版本升级指南位于 docs/upgrading/upgrading_v3.md 与 docs/upgrading/upgrading_v4.md仓库根目录 MIGRATIONS.md 提供整体迁移说明各子包也维护独立 CHANGELOG如 packages/core/CHANGELOG.md、packages/browser-pool/CHANGELOG.md便于聚焦单个模块的变更特性用法可参考 docs/guides/ 与 docs/examples/ 中的对应指南与示例。结语从 v2 到 v3 的拆分重构到 v3.18 为止的持续打磨Crawlee 的版本历史本身就是一部爬虫框架的工程进化史包粒度更细、API 命名更统一、请求来源更多元队列 v2、Sitemap、Tandem、反检测手段更现代指纹、Cloudflare 挑战处理、Camoufox、爬虫类型更丰富HTTP、JSDOM、LinkeDOM、Adaptive、Stagehand。理解这份 CHANGELOG等于同时理解了 Crawlee 的设计取舍与迁移路径无论你是初次选型还是从旧版本升级都能据此做出有依据的决策。【免费下载链接】crawleeCrawlee—A web scraping and browser automation library for Node.js to build reliable crawlers. In JavaScript and TypeScript. Extract data for AI, LLMs, RAG, or GPTs. Download HTML, PDF, JPG, PNG, and other files from websites. Works with Puppeteer, Playwright, Cheerio, JSDOM, and raw HTTP. Both headful and headless mode. With proxy rotation.项目地址: https://gitcode.com/GitHub_Trending/cr/crawlee创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Crawlee 版本演进全解析：从 Apify SDK 到 v3.18 的核心变更与技术脉络
Crawlee 版本演进全解析从 Apify SDK 到 v3.18 的核心变更与技术脉络【免费下载链接】crawleeCrawlee—A web scraping and browser automation library for Node.js to build reliable crawlers. In JavaScript and TypeScript. Extract data for AI, LLMs, RAG, or GPTs. Download HTML, PDF, JPG, PNG, and other files from websites. Works with Puppeteer, Playwright, Cheerio, JSDOM, and raw HTTP. Both headful and headless mode. With proxy rotation.项目地址: https://gitcode.com/GitHub_Trending/cr/crawleeCrawlee 是面向 Node.js 的 Web 爬取与浏览器自动化库支持 Cheerio、JSDOM、LinkeDOM、Puppeteer、Playwright 与原生 HTTP 等多种执行环境。本篇基于仓库根目录的 CHANGELOG.md记录了 v2.0.0 至 v3.18.1 的完整变更历史展开梳理 Crawlee 从 Apify SDK 中独立、完成 v3 大版本重构再到后续持续迭代的演进脉络。读者将理解 Crawlee 的包体系设计、关键 API 的命名与语义变化、请求队列/链接入队/会话代理等核心机制的演进以及如何结合 MIGRATIONS.md 与 docs/upgrading/ 目录完成版本升级。一、项目背景Crawlee 与 Apify SDK 的分家Crawlee 是 Apify SDKapify包在爬取与浏览器自动化方向上的精神继承者。正如 CHANGELOG 在 v3.0.0 一节中说明的v3 之前apify包同时包含爬取工具与 Apify 平台辅助方法v3 起将整个项目拆分为两部分Crawlee新的 Web 爬取库以crawlee包在 NPM 发布Apify SDKApify 平台辅助工具以apify包发布。拆分后Crawlee 以crawlee命名空间发布多个子包。从当前仓库 packages/ 目录可以确认这套体系至今仍在沿用并且已经进一步细化为包名职责crawlee/core所有爬虫实现的基础包含Request、RequestQueue、RequestList、Dataset等核心类crawlee/basic导出BasicCrawler即 packages/basic-crawlercrawlee/cheerio导出CheerioCrawlerpackages/cheerio-crawlercrawlee/browser导出BrowserCrawler是crawlee/playwright与crawlee/puppeteer的基类crawlee/playwright/crawlee/puppeteer导出PlaywrightCrawler/PuppeteerCrawlercrawlee/jsdom/crawlee/linkedom导出JSDOMCrawler/LinkeDOMCrawlercrawlee/http导出HttpCrawlerpackages/http-crawlercrawlee/memory-storage/crawlee/fs-storage存储实现packages/fs-storagecrawlee/browser-pool浏览器池packages/browser-poolcrawlee/utils工具方法packages/utilscrawlee/types主要存放StorageClient相关 TS 接口crawlee/stagehandAI 驱动的浏览器自动化v3.16 新增packages/stagehand-crawlercrawlee/otelOpenTelemetry 可观测性集成packages/otel各包之间相互扩展并重导出因此只需安装你实际使用的那个包即可。例如安装crawlee/playwright会自动带上crawlee/browser进而带上crawlee/basic与crawlee/core。同时crawlee元包packages/crawlee会重导出大多数crawlee/*内容方便一站式使用。值得注意的是当前仓库 lerna.json 中的发布版本为3.18.1而各子包 package.json 中已标记为4.0.0说明仓库正处在 v4 开发分支上CHANGELOG 记录的最新正式版本是 2026-08-12 发布的v3.18.1。二、v3.0 里程碑一次彻底的重构v3.0.02022-07-13是 CHANGELOG 中篇幅最大、信息量最高的一节它实质上是一份完整的从 v2 迁移到 v3指南以下要点必须掌握。2.1 安装方式v3 时代crawlee/*包尚未标记为latest需要从next分发标签安装npm install crawleenext # 仅需 Cheerio 支持时 npm install crawlee/cheerionext # 使用 Playwright / Puppeteer 时需显式安装浏览器驱动 npm install crawleenext playwright # 或 npm install crawlee/playwrightnext playwright这一显式安装浏览器依赖的设计一直延续到今天库本身不捆绑 Playwright/Puppeteer 版本由使用者自行控制。2.2 全量 TypeScript 支持Crawlee 与 Apify SDK 均为完全 TypeScript 重写类型随包发布。CHANGELOG 推荐使用apify/tsconfig预设并给出完整配置示例{ extends: apify/tsconfig, compilerOptions: { module: ES2022, target: ES2022, outDir: dist, lib: [DOM] }, include: [./src/**/*] }注意module/target需为ES2022及以上以支持顶层 awaitnoImplicitAny默认开启初期开发可能需临时关闭。2.3 Docker 多阶段构建CHANGELOG 给出了推荐的 Dockerfile 模式先用带开发依赖的基础镜像构建 TypeScript再拷贝产物到仅含生产依赖的最终镜像避免 TypeScript 等开发依赖进入运行镜像。2.4 浏览器指纹替代 stealthv2 中 Puppeteer 爬虫有一个魔法般的stealth选项v3 将其替换为动态生成的浏览器指纹。若想关闭动态指纹通过browserPoolOptions设置const crawler new PlaywrightCrawler({ browserPoolOptions: { useFingerprints: false, }, });v3.0 还说明指纹缓存选项从useFingerprintPerProxyCache更名为useFingerprintCache缓存不再绑定代理 URL而是绑定会话。对应实现位于 packages/browser-pool/src/fingerprinting/。2.5 会话 Cookie 方法重命名session.getPuppeteerCookies()/session.setPuppeteerCookies()更名为session.getCookies()/session.setCookies()因为该方法适用于所有爬虫而不仅是 Puppeteer。相关实现见 packages/core/src/session_pool/session.ts。2.6 存储memory-storage 与自动清理v3 默认使用crawlee/memory-storage内存存储 落盘 dump尊重 KVS 中已有的INPUT.json替代基于 SQLite 的apify/storage-local在 Apify 平台上运行时通过Actor.init/Actor.main自动切换到ApifyClient本地运行默认自动清理存储purge可通过Actor.init({ purge: false })关闭--purge参数不再是必须的。当前仓库中存储相关实现分布在 packages/core/src/storages/抽象与核心逻辑与 packages/fs-storage文件系统实现。2.7 爬虫选项与上下文接口重命名v3 统一了命名规范旧名仍被支持但不在 TS 层暴露旧名称新名称handleRequestFunction/handlePageFunctionrequestHandlerhandleRequestTimeoutSecs/handlePageTimeoutSecsrequestHandlerTimeoutSecsrequestTimeoutSecsnavigationTimeoutSecshandleFailedRequestFunctionfailedRequestHandler上下文接口同步更名CheerioHandlePageInputs→CheerioCrawlingContext、PlaywrightHandlePageFunction→PlaywrightCrawlingContext、PuppeteerHandlePageFunction→PuppeteerCrawlingContext。2.8 上下文感知的 enqueueLinks 与三种入队策略enqueueLinks从Apify.utils迁移到爬取上下文context aware不再需要手动传入requestQueue、page或$。同时提供三种策略EnqueueStrategy.Allall匹配页面上发现的任何 URLEnqueueStrategy.SameHostnamesame-hostname仅匹配与基准 URL 相同子域的链接默认EnqueueStrategy.SameDomainsame-domain匹配相同域名的链接例如基准 URL 为https://example.com时https://wow.an.example.com也会被匹配。无需任何参数即可调用enqueueLinks()默认过滤同子域链接还可用 glob 模式筛选const crawler new PlaywrightCrawler({ async requestHandler({ enqueueLinks }) { await enqueueLinks({ globs: [https://apify.com/*/*], // 也可使用 regexps 与 pseudoUrls }); }, });后续版本持续增强该助手exclude选项v3.3、所有变体支持forefrontv3.2、SameOrigin策略与协议匹配放宽v3.2、enqueueLinksByClickingElementsv3.1Playwright、waitForAllRequestsToBeAddedv3.10.4等。当前实现位于 packages/core/src/enqueue_links/。2.9 隐式 RequestQueue 与 crawler.addRequests()所有爬虫现在通过crawler.getRequestQueue()自动获得RequestQueue实例仍可显式传入方法会尊重传入实例。crawler.addRequests()则以 1000 个为一组批量入队先入队首批 1000 个并立即 resolve其余在后台继续避免触发 API 限流// 首批 1000 个请求入队后即 resolve const result await crawler.addRequests([/* 可以是数百万个 */]); // 如需等待全部入队完成 await result.waitForAllRequestsToBeAdded;从源码看packages/basic-crawler/src/internals/basic-crawler.ts 中addRequests是隐式RequestQueue.addRequestsBatched()的别名批量入队的底层实现在 packages/core/src/storages/batched_adds.ts 与 packages/core/src/storages/request_queue.ts。v3.10 还专门优化了crawler.addRequests()大批量入队性能v3.18 则修复了addRequestsBatched重复提交已入队请求与重试上限问题。2.10 requestAsBrowser 的移除与 sendRequestv3 移除requestAsBrowser改为直接使用got-scraping并新增上下文助手context.sendRequest()const crawler new BasicCrawler({ async requestHandler({ sendRequest, log }) { const res await sendRequest({ responseType: json }); log.info(received body, res.body); }, });同时整理了一批选项迁移payload→body/jsonignoreSslErrors→https.rejectUnauthorized语义相反默认falseuseMobileVersion/languageCode/countryCode→headerGeneratorOptionstimeoutSecs→timeout.request毫秒throwOnHttpErrors→throwHttpErrorsdecodeBody→decompressabortFunction被取消方案取代。当前仓库对应的 HTTP 客户端实现见 packages/http-client、packages/got-scraping-client 与 packages/impit-client。2.11 其他 v3 行为变化浏览器池禁止混合插件同一池中混用 Puppeteer 与 Playwright 插件将直接抛错跳过导航可用Request.skipNavigationcontext.sendRequest()在浏览器外处理请求对应示例 docs/examples/skip-navigation.mdx日志crawlee默认导出log实例上下文内提供带爬虫名前缀的log请求处理器内应优先使用自动保存状态每个爬虫都有crawler.useState()返回可自动持久化的状态对象persistState事件触发保存值有缓存const crawler new CheerioCrawler({ async requestHandler({ crawler }) { const state await crawler.useState({ foo: [] as number[] }); state.foo.push(123); // 无需手动保存 }, });Apify SDK 侧平台辅助方法Actor.init/exit/main、getInput、pushData、openDataset等归入apify包事件系统由EventManager管理packages/core/src/events/Actor.on/off替代Apify.events.on内部破坏性变更Request.handledAt改为 ISO 字符串Request.inProgress/reclaimed改为SetAPIFY_MEMORY_MBYTES由CRAWLEE_AVAILABLE_MEMORY_RATIO取代AutoscaledPool的部分选项上移至顶层配置等。三、v3.1 → v3.18 版本时间线关键新增特性CHANGELOG 记录了 v3 后续约两年半的迭代以下按主题提炼每个版本值得关注的能力括号内为对应源码/文档位置。3.1 请求来源与队列体系v3.5.5引入Request Queue v2RQv2此后 v3.10 将 RQv2 设为默认队列v3.13 进一步简化其实现v3.16 移除对RequestQueueV1的弃用标记v3.10.2支持从字符串加载 sitemapv3.11.0新增Sitemap 驱动的请求列表SitemapRequestListv3.11.2 为其加入globs/regexps过滤与弹性加载v3.13.3 支持周期性持久化状态对应实现 packages/core/src/storages/sitemap_request_loader.tsv3.13.9addRequests系列接受(Async)Iterablesv3.15.0新增TandemRequestProvider支持RequestList与RequestQueue组合使用packages/core/src/storages/request_manager_tandem.ts对应指南 docs/guides/request_loaders.mdx。3.2 入队与抓取控制v3.14.0新增maxCrawlDepth爬虫选项限制抓取深度v3.15.0 修复其与自定义transformRequestFunction的兼容v3.18.1 修复 JSDOM/LinkeDOM 上下文中对其的尊重v3.13.2新增onSkippedRequest回调用于报告因过滤条件被跳过的链接v3.13.9 完善v3.13.8不入队超过爬虫处理能力的链接数量v3.18.0enqueueLinksByClickingElements允许任意clickOptions。3.3 反检测与浏览器能力v3.13.0Playwright 新增handleCloudflareChallenge助手v3.16 使其更可配置v3.18.1 适配新的 Cloudflare 挑战标记v3.13.0新增Camoufox 爬虫模板packages/templates/templates/camoufox-ts/v3.13.3 默认关闭其指纹v3.6.1Puppeteer 启用新的 headless 模式v3.8.0 支持puppeteerv22v3.18.0 支持puppeteer25v3.9.1新增browserPerProxy浏览器启动选项v3.15.2默认启用systemInfoV2v3.17 新增动态内存快照v3.18 修复其 CPU tick 基线。3.4 代理与会话v3.9.0ProxyConfiguration新增tieredProxyUrls分层代理与更好的newUrlFunctionv3.12.1 支持传入null关闭代理v3.5.0新增sameDomainDelay、closeCookieModals上下文助手、代理错误自动退休会话v3.3.1 修复会话轮换问题v3.1.1concurrency选项覆盖顺序修复、会话标记为 bad 等相关实现见 packages/core/src/session_pool/ 与 packages/core/src/proxy_configuration.ts。3.5 爬虫家族扩张v3.0.3新增HttpCrawler与JSDOMCrawlerv3.4.0新增LinkeDOMCrawlerpackages/linkedom-crawlerv3.8.0新增AdaptivePlaywrightCrawler自适应渲染类型检测的爬虫后续持续完善持久化与结果比较器v3.13.5、v3.16.0v3.10.0新增FileDownload文件下载器v3.13.3 向streamHandler传入responsev3.17 新增abortDownload助手对应示例 docs/examples/file_download.mdxv3.16.0新增crawlee/stagehand支持 AI 驱动的浏览器自动化docs/guides/stagehand_crawler.mdx。3.6 存储、统计与可观测性v3.3.0新增setStatusMessage基础支持v3.5.0 支持配置自动状态消息v3.18.0 确保终止状态消息可靠送达v3.7.0新增 robots.txt 与 sitemap.xml 工具集packages/utils/src/internals/v3.13.1 将RobotsFile更名为RobotsTxtFilev3.15.3 支持自定义userAgentv3.10.0实现ErrorSnapshotter错误上下文快照packages/core/src/error_snapshotter.ts与 RQv2 默认化v3.12.0允许使用其他 HTTP 客户端v3.12.2 新增 impit 客户端v3.13.0 使用原生 impit 流式传输当前模板默认使用ImpitHttpClientv3.17v3.13.8 / v3.15.0Dataset 新增collectAllKeys全量 CSV 导出选项crawler.exportData()助手v3.6.0。四、源码级印证关键机制在今天仓库中的样子以 packages/basic-crawler/src/internals/basic-crawler.ts 为入口可以印证 CHANGELOG 中多项特性在 v4 分支上的延续skipNavigation、onSkippedRequest、sameDomainDelaySecs默认 0大于 0 时为每个站点建立独立节流时钟、maxCrawlDepth、respectRobotsTxtFile布尔或{ userAgent }默认false均作为构造选项存在与 CHANGELOG 中 v3.13.1/v3.13.2/v3.14.0/v3.15.3 的记载一一对应useState()实现了匿名索引去重与共享状态告警呼应 v3.0 的自动保存爬虫状态addRequests注释明确它是隐式RequestQueue.addRequestsBatched()的别名对应 v3.4.2 引入的批量入队 API。存储层面packages/core/src/storages/ 中request_queue.tsRQv2、request_manager_tandem.tsTandem、sitemap_request_loader.tsSitemapRequestList、batched_adds.ts批量入队等文件直接对应 CHANGELOG 中关于请求队列体系的一系列迭代。测试方面test/core/ 下的request_manager_tandem.test.ts、sitemap_request_loader.test.ts、test/core/storages/ 下的request_queue.test.ts等用例为这些机制提供了可执行佐证。五、升级路径与文档索引各版本完整变更细节均记录在 CHANGELOG.md当前最新记录 v3.18.1跨大版本升级指南位于 docs/upgrading/upgrading_v3.md 与 docs/upgrading/upgrading_v4.md仓库根目录 MIGRATIONS.md 提供整体迁移说明各子包也维护独立 CHANGELOG如 packages/core/CHANGELOG.md、packages/browser-pool/CHANGELOG.md便于聚焦单个模块的变更特性用法可参考 docs/guides/ 与 docs/examples/ 中的对应指南与示例。结语从 v2 到 v3 的拆分重构到 v3.18 为止的持续打磨Crawlee 的版本历史本身就是一部爬虫框架的工程进化史包粒度更细、API 命名更统一、请求来源更多元队列 v2、Sitemap、Tandem、反检测手段更现代指纹、Cloudflare 挑战处理、Camoufox、爬虫类型更丰富HTTP、JSDOM、LinkeDOM、Adaptive、Stagehand。理解这份 CHANGELOG等于同时理解了 Crawlee 的设计取舍与迁移路径无论你是初次选型还是从旧版本升级都能据此做出有依据的决策。【免费下载链接】crawleeCrawlee—A web scraping and browser automation library for Node.js to build reliable crawlers. In JavaScript and TypeScript. Extract data for AI, LLMs, RAG, or GPTs. Download HTML, PDF, JPG, PNG, and other files from websites. Works with Puppeteer, Playwright, Cheerio, JSDOM, and raw HTTP. Both headful and headless mode. With proxy rotation.项目地址: https://gitcode.com/GitHub_Trending/cr/crawlee创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考