Crawlee 聚合包公开 API 全解析：从 `utils` 命名空间到 12 个子包的统一入口

Crawlee 聚合包公开 API 全解析从utils命名空间到 12 个子包的统一入口【免费下载链接】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是 Crawlee 项目的聚合入口包umbrella package它将crawlee/core、crawlee/playwright、crawlee/puppeteer、crawlee/utils等全部子包的公开 API 汇于一处并额外暴露一个内置的utils命名空间。本文以仓库中的公开 API 报告 crawlee.api.md 为骨架结合 packages/crawlee/src/index.ts 及crawlee/utils各工具源码逐项拆解crawlee包到底导出什么、每个工具如何工作、以及这份 API 报告文件本身是怎样被生成和维护的。读完你将能准确判断从crawlee能导入什么、该从哪个子包导入什么并理解该仓库的公开 API 兼容性承诺机制。crawlee包是什么一份来自 package.json 的定位从 packages/crawlee/package.json 可以看出crawlee包自述为 The scalable web crawling and scraping library for JavaScript/Node.js版本为4.0.0要求node 22.0.0采用 ESMtype: module。关键信息如下它不实现任何爬虫逻辑而是把crawlee/basic、crawlee/browser、crawlee/browser-pool、crawlee/cheerio、crawlee/core、crawlee/fs-storage、crawlee/http、crawlee/jsdom、crawlee/linkedom、crawlee/playwright、crawlee/puppeteer、crawlee/utils全部作为workspace:*依赖引入并重新导出playwright与puppeteer是可选 peer 依赖peerDependenciesMeta中标记为optional意味着你不装浏览器驱动也能使用 HTTP 类爬虫只有在使用 Playwright/Puppeteer 爬虫时才需要安装对应浏览器库bin指向./src/cli.ts通过 src/cli.ts 中的import-local机制加载crawlee/cli提供npx crawlee脚手架命令但 CLI 本身不参与公开 API 承诺详见后文。也就是说日常开发中import { ... } from crawlee能拿到的所有东西在类型层面都记录在这份 crawlee.api.md 报告中。报告总览crawlee公开表面只有两大部分API Extractor 生成的报告结构非常简单清晰一个显式声明的utils常量对象8 个成员均标注public12 条export * from crawlee/...全量转发声明。实际源码 packages/crawlee/src/index.ts 与报告一一对应前 17 行完成 12 个子包的全量转发第 19–28 行定义utils对象。export const utils { puppeteer: puppeteerUtils, playwright: playwrightUtils, log, social, sleep, downloadListOfUrls, parseOpenGraph, extractMicrodata, };注意报告中的顺序puppeteer、playwright、log、social、sleep、downloadListOfUrls、parseOpenGraph、extractMicrodata与源码完全一致因为这份.api.md就是由编译产物dist/index.d.ts机械生成的。utils命名空间逐成员解析utils的设计意图很明确把高频的、与爬虫运行时解耦的通用工具函数收拢到一个命名空间下避免crawlee/utils的深层路径导入。下面结合crawlee/utils源码逐一说明。puppeteer/playwright浏览器工具集这两个成员分别引用crawlee/puppeteer与crawlee/playwright包的puppeteerUtils/playwrightUtils命名空间见 packages/utils/src/index.ts 与 crawlee 入口源码的导入语句。它们封装了与浏览器实例、页面生命周期、page.evaluate辅助等相关的实用函数是编写 Playwright/Puppeteer 爬虫处理函数时的常用补充工具。由于浏览器工具集随浏览器子包演进这里不逐一枚举其成员以各子包公开 API 报告如 crawlee-puppeteer.api.md、crawlee-playwright.api.md为准。log全局日志实例log直接引用crawlee/core的Log实例。它贯穿整个 Crawlee 运行时——爬虫状态、请求重试、统计信息都会经由该实例输出。在自定义爬虫代码中可直接使用import { log } from crawlee; log.info(开始抓取任务, { url: https://example.com });social社交媒体信息提取social是crawlee/utils中以命名空间方式导出的整组社交信息工具源码见 packages/utils/src/internals/social.ts内部通过export * as social from ./internals/social.js暴露见 packages/utils/src/index.ts。它提供两类能力邮箱与电话提取emailsFromText(text)/emailsFromUrls(urls)从纯文本或mailto:链接数组中提取邮箱地址。内部使用EMAIL_REGEX精确单条匹配/^...$/i形式与EMAIL_REGEX_GLOBAL批量匹配/.../ig形式两个正则都遵循 RFC 5321 的长度约束local part 与域名标签分别限长{1,64}、{0,62}源码注释明确说明这是为了避免在长输入上产生二次回溯ReDoSphonesFromText(text)/phonesFromUrls(urls)从文本或tel:/phone:/callto:链接中提取电话号码。源码内置了十余种常见号码格式模式并做了两层过滤少于 7 位数字的结果被丢弃PHONE_MIN_DIGITS形如2018-11-10的日期模式被排除SKIP_PHONE_REGEXS。phonesFromText的结果被归类为不确定uncertain因为纯文本号码误报率高。社交平台正则每平台一对精确/全局正则平台精确匹配批量匹配LinkedInLINKEDIN_REGEXLINKEDIN_REGEX_GLOBALInstagramINSTAGRAM_REGEXINSTAGRAM_REGEX_GLOBALTwitter/XTWITTER_REGEXTWITTER_REGEX_GLOBALFacebookFACEBOOK_REGEXFACEBOOK_REGEX_GLOBALYouTubeYOUTUBE_REGEXYOUTUBE_REGEX_GLOBALTikTokTIKTOK_REGEXTIKTOK_REGEX_GLOBALPinterestPINTEREST_REGEXPINTEREST_REGEX_GLOBALDiscordDISCORD_REGEXDISCORD_REGEX_GLOBAL这些正则都使用负向后瞻/前瞻防止误匹配嵌入在单词中的 URL且维护了保留路径黑名单如 Twitter 的home、login、hashtag等Facebook 的rsrc.php、groups等避免把平台的功能页误判为用户主页。全局版本在遇到带子路径的 URL 时只截取基础主页部分。综合入口parseHandlesFromHtml(html, data?)一次性从 HTML 文档中提取邮箱、电话与全部社交平台主页返回SocialHandles结构含emails、phones、phonesUncertain、linkedIns、twitters、instagrams、facebooks、youtubes、tiktoks、pinterests、discords字段。实现上它先用 cheerio 解析文档电话来自tel:链接高置信度邮箱来自mailto:链接加纯文本保留重复并按字母序去重社交 URL 则直接对原始 HTML 做全局正则匹配。可选的data参数会回填data.$cheerio 对象与data.text纯文本避免调用方二次解析。sleep毫秒级延时sleep是极简的异步延时工具源码见 packages/utils/src/internals/general.ts底层直接复用node:timers/promises的setTimeoutexport async function sleep(millis?: number): Promisevoid { return setTimeout(millis ?? undefined); }用途很明确在爬虫处理函数中放慢请求节奏、规避目标站点的反爬限制。若传入非正数或省略参数Promise 会立即 resolve。示例import { sleep } from crawlee; // 每次请求前休息 1.5 秒 await sleep(1500);同一文件还导出了两个 URL 匹配正则URL_NO_COMMAS_REGEX与URL_WITH_COMMAS_REGEX后者额外支持 URL 路径/查询中的逗号但可能破坏逗号分隔列表的解析以及expandShadowRoots这类内部工具。downloadListOfUrls下载并解析 URL 列表该函数用于给定一个 URL下载其内容并抽出其中所有链接典型场景是抓取 CSV、纯文本种子列表。源码与参数校验见 packages/utils/src/internals/extract-urls.ts支持选项如下选项类型默认值说明urlstring必填待下载的资源地址encodingBufferEncodingutf8文件编码urlRegExpRegExpURL_NO_COMMAS_REGEX自定义 URL 匹配正则应为大小写不敏感且带 global 标志如/something/giproxyUrlstring无下载请求使用的代理httpClientBaseHttpClientnew FetchHttpClient()自定义 HTTP 客户端实现细节值得一提内部通过 zod schema 做严格参数校验z.strictObject非法参数会抛出ArgumentValidationError对 Google 表格的分享链接做了自动修复若 URL 匹配docs.google.com/spreadsheets/d/...会被改写为.../gviz/tq?tqxout:csv以获取可下载的 CSV 数据下载完成后用TextDecoder按指定编码解码再交给extractUrls按行切分、逐行用正则抽 URL。parseOpenGraphOpen Graph 元数据解析parseOpenGraph从页面 HTML或已加载的 cheerio 对象中解析 Open Graph 协议元数据源码见 packages/utils/src/internals/open_graph_parser.ts。用法import { parseOpenGraph } from crawlee; const og await parseOpenGraph(htmlheadmeta propertyog:title content标题//head/html); // { title: 标题 }实现要点内置一份OPEN_GRAPH_PROPERTIES声明表覆盖og:title、og:type、og:image含url/secure_url/type/width/height/alt子属性、og:url、og:audio、og:description、og:determiner、og:locale含alternate、og:site_name、og:video以及不以og:开头的扩展属性族videovideo:actor、video:director、video:duration等、music专辑、曲目、音乐人等、article发布时间、作者、标签等、book作者、ISBN 等、profile姓名、用户名、性别等同一属性出现多次如多个video:actor时会保留为数组单个值则返回字符串带子属性的属性会组织成嵌套对象原始值以outputNameValue键存放例如og:image的裸值落在imageValue下支持第二个参数additionalProperties传入自定义的OpenGraphProperty声明以扩展解析范围。extractMicrodataschema.org 微数据解析extractMicrodata按照 HTML 规范中的 microdata processing model。它接受原始 HTML 字符串或 cheerio 对象返回顶层MicrodataItem数组每个 item 包含typeitemtype属性的 tokens如[https://schema.org/Product]iditemid属性properties按itemprop名归组的属性值值类型为字符串或嵌套的MicrodataItem同名属性重复时以数组存储。实现上遵循微数据的作用域规则嵌套itemscope元素构成独立 item其子树不再归属外层 itemitemref引用通过按需建立的id索引Mapstring, Element解析源码注释说明大多数文档不会触发itemref查找因此该索引采用惰性构建。文本值会被 trim 并折叠内部空白URL 类属性原样返回而不做相对路径解析。注意crawlee/utils还导出htmlToText、extractUrls、EnqueueStrategy、robots、sitemap、expandShadowRoots等更多工具见 packages/utils/src/index.ts它们大多可通过crawlee/utils子包直接导入而crawlee聚合包只把上述 8 个高频成员收进utils命名空间。12 个export *聚合包背后的子包矩阵报告第二部分的 12 条export *定义了crawlee对全部子包的转发构成完整的爬虫能力栈子包职责定位crawlee/core爬虫基类、自动伸缩autoscaling、请求/会话/存储管理等运行时核心crawlee/basic基于 HTTP 的基础爬虫抽象crawlee/browser浏览器类爬虫抽象层无头/有头浏览器通用逻辑crawlee/http直接使用 HTTP 客户端的高性能爬虫crawlee/cheerio基于 Cheerio 的静态 HTML 解析爬虫crawlee/jsdom基于 JSDOM 的 DOM 爬虫crawlee/linkedom基于 linkedom 的轻量 DOM 爬虫crawlee/playwrightPlaywright 驱动爬虫含playwrightUtilscrawlee/puppeteerPuppeteer 驱动爬虫含puppeteerUtilscrawlee/browser-pool浏览器实例池、指纹与代理轮换crawlee/fs-storage基于文件系统的存储实现数据集、键值存储、请求队列crawlee/utils通用工具sleep、social、downloadListOfUrls等这样用户只需import { CheerioCrawler, Dataset, ... } from crawlee即可获得完整能力而无需关心各子包的边界。各子包的完整类型级接口可分别查阅 crawlee-core.api.md、crawlee-cheerio.api.md、crawlee-playwright.api.md 等同目录报告。这份报告文件是怎么来的API Extractor 工作流crawlee.api.md顶部声明 Do not edit this file. It is a report generated by API Extractor它确实是机械生成的产物。维护流程记录在 docs/public-api/README.md生成先pnpm build构建所有包再从每个包的dist/index.d.ts运行 API Extractor 生成报告。根目录package.json中对应脚本为pnpm api:extract内部通过pnpm dlx github:apify/api-extractor-report执行校验CI 运行pnpm api:check等价于 extract 命令加--verify一旦提交的报告与当前构建结果不一致即失败——这要么意味着 API 变更是有意的提交更新后的报告reviewer 通过 diff 审视公开表面变化要么是无意的需要修复源码范围报告采用 API Extractor 的public变体被标记为internal含alpha/beta与旧式ignore的符号会被剔除只有public表面进入报告未打标签的符号按约定隐式视为 public该代码库不使用显式public标签被遗忘的导出forgotten exports若某类型被公开 API 引用但入口文件从未导出它报告会通过includeForgottenExports将其纳入并带显式横幅注释// Not exported by the entry point; reachable only as a referenced type.——其形状属于兼容性承诺范围但名称不可导入因此输出时不带export。报告会随后处理裁剪掉仅被internal成员引用而未能存活的声明与死导入保证报告里不出现自身未声明的符号排除清单crawlee/cli与crawlee/templates被刻意排除在报告之外因为它们是工具型包CLI 二进制与项目脚手架不属于承诺向后兼容的可导入 API排除列表在scripts/api-extractor/run.ts中维护中间产物docs/public-api/temp/存放中间报告含暂存的.public.api.md已被 git-ignore。这正是 crawlee.api.md 中// (No packageDocumentation comment for this package)注释的由来——报告只反映类型级表面不包含包级文档注释。实践指南如何正确使用crawlee聚合包安装任一子包均随聚合包可用浏览器驱动按需选装npm install crawlee # 使用 Playwright 时再装 npm install crawlee playwright # 使用 Puppeteer 时再装 npm install crawlee puppeteer导入实践import { CheerioCrawler, // 来自 crawlee/cheerio Dataset, // 来自 crawlee/core / storages sleep, // utils 命名空间成员亦可顶层导入 social, // utils 命名空间成员 utils, // 整个命名空间 } from crawlee; // 用 social 从抓到的 HTML 里提取联系方式 const html a hrefmailto:helloexample.comContact/a; const handles await social.parseHandlesFromHtml(html); // { emails: [helloexample.com], phones: [], ... } // 用 sleep 控制请求节奏 await sleep(1000); // 用 downloadListOfUrls 把种子 URL 列表转成请求队列 const urls await utils.downloadListOfUrls({ url: https://example.com/urls.txt });类型校验crawlee是纯 ESM 包type: moduleexports指向./dist/index.js要求 Node.js ≥ 22在 CommonJS 项目中请使用动态import()或升级为 ESM 工程。何时应该绕过聚合包当你的项目只想使用crawlee/utils中的某个工具如robots、sitemap、EnqueueStrategy时直接安装并导入对应子包可减小依赖面同时crawlee聚合包不会转发crawlee/impit-client、crawlee/http-client、crawlee/otel、crawlee/types等基础设施包的导出这些需按需从各自包名导入。小结crawlee聚合包的公开 API 表面由两件事构成一个 8 成员的utils命名空间puppeteer、playwright、log、social、sleep、downloadListOfUrls、parseOpenGraph、extractMicrodata和12 条子包全量转发。前者每个成员都能在 packages/utils 找到精确实现后者把 core、browser、cheerio、playwright、puppeteer、fs-storage 等能力统一到一个导入源。而 crawlee.api.md 本身则是仓库用 API Extractor 把这份承诺固化成机器可校验契约的载体——任何对公开 API 的改动都会被pnpm api:check拦截并要求同步更新报告从而让向后兼容成为可审计、可 diff 的工程实践。【免费下载链接】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），仅供参考