Crawlee PlaywrightCrawler + TypeScript 模板全解析：从零搭建生产级浏览器爬虫项目

Crawlee PlaywrightCrawler TypeScript 模板全解析从零搭建生产级浏览器爬虫项目【免费下载链接】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本指南以仓库中 playwright-ts 模板 为骨架完整讲解如何使用 Crawlee 的PlaywrightCrawler与 TypeScript 搭建一个开箱即用、可直接部署的生产级爬虫项目。你将掌握模板的目录结构与依赖配置、入口文件与路由系统的编写方式、PlaywrightCrawler的底层运行原理以及本地开发与 Docker 容器化部署的完整流程。一、模板项目概览README 说了什么仓库根目录下的packages/templates/templates/playwright-ts/是一份官方维护的 TypeScript 模板其 README.md 对该模板给出了明确定位This template is a production ready boilerplate for developing withPlaywrightCrawler. Use this to bootstrap your projects using the most up-to-date code.即这是一份面向PlaywrightCrawler开发的生产级样板工程用于帮助开发者以最新的代码实践快速启动新项目。README 同时建议读者进一步查阅PlaywrightCrawler的 API 文档与示例对应仓库内的 crawlee-playwright.api.md 与 playwright_crawler.mdx。模板在仓库中的注册信息该模板由 packages/templates/manifest.json 登记名称为playwright-ts描述为 PlaywrightCrawler template project [TypeScript]包含的文件清单为src/main.ts爬虫入口src/routes.ts路由定义.dockerignore、.gitignoreDockerfile容器化部署package.json依赖与脚本README.md项目说明tsconfig.jsonTypeScript 编译配置与cheerio-ts、puppeteer-ts、camoufox-ts等模板并列playwright-ts面向需要真实浏览器渲染 JavaScript 的场景。模板的完整文件结构packages/templates/templates/playwright-ts/ ├── src/ │ ├── main.ts # 爬虫实例创建与启动 │ └── routes.ts # 基于标签的路由处理 ├── Dockerfile # 多阶段镜像构建 ├── README.md # 模板说明 ├── package.json # 依赖、脚本、入口 └── tsconfig.json # TS 编译配置二、项目骨架与依赖解析package.json 与 tsconfig.json依赖清单package.json 声明了如下关键依赖依赖版本范围作用crawlee^3.0.0核心爬虫框架提供PlaywrightCrawler、createPlaywrightRouter、ProxyConfigurationcrawlee/impit-client^3.0.0基于 impit 的 HTTP 客户端提供Browser枚举与ImpitHttpClientplaywright1.62.1浏览器自动化底层驱动锁定具体版本开发依赖包括apify/tsconfig基础 TS 配置、tsx直接运行 TS、typescript与types/node。项目采用type: module即 ESM 模块体系因此源码中的导入语句都带有.js后缀如import { router } from ./routes.js。脚本命令命令实际执行用途npm run startnpm run start:dev开发模式启动npm run start:devtsx src/main.ts用 tsx 直接运行 TS 源码无需预编译npm run start:prodnode dist/main.js运行编译产物生产模式npm run buildtsc用 TypeScript 编译器输出到dist/npm run postinstallnpx crawlee install-playwright-browsers安装依赖后自动下载 Playwright 浏览器内核其中postinstall是值得注意的自动化设计执行npm install之后会自动调用crawlee install-playwright-browsers下载 Playwright 所需的浏览器二进制省去手动初始化步骤。TypeScript 编译配置tsconfig.json 继承apify/tsconfig并覆盖以下选项module/moduleResolutionNodeNext匹配 ESM 模块规范targetES2022outDirdist与start:prod脚本对应lib包含DOM使代码中可以引用document、window等浏览器 APIinclude仅编译./src/**/*。三、入口文件 main.ts创建并运行 PlaywrightCrawlersrc/main.ts 是爬虫的启动入口完整代码如下// For more information, see https://crawlee.dev/ import { Browser, ImpitHttpClient } from crawlee/impit-client; import { PlaywrightCrawler, ProxyConfiguration } from crawlee; import { router } from ./routes.js; const startUrls [https://crawlee.dev]; const crawler new PlaywrightCrawler({ // proxyConfiguration: new ProxyConfiguration({ proxyUrls: [...] }), httpClient: new ImpitHttpClient({ browser: Browser.Chrome }), requestHandler: router, // Comment this option to scrape the full website. maxRequestsPerCrawl: 20, }); await crawler.run(startUrls);各配置项解读startUrls爬虫的种子 URL 列表。crawler.run(startUrls)会将这些 URL 封装为Request对象送入请求队列作为爬取起点。httpClient模板显式注入了ImpitHttpClient并将浏览器指纹设置为Browser.Chrome让 Playwright 驱动的浏览器以 Chrome 标识发起网络请求。这是可选的性能优化项也可去掉让 Crawlee 使用默认 HTTP 客户端。requestHandler: router把路由对象作为请求处理器传入即每个页面加载完成后交由routes.ts中定义的路由逻辑分发处理详见第四节。maxRequestsPerCrawl: 20限制整次爬取最多处理 20 个请求。模板注释明确说明注释掉该选项即可爬取整站。该参数用于控制爬取规模避免误爬全站消耗过多资源。proxyConfiguration默认被注释。需要代理轮换时取消注释并填写代理地址即可例如new ProxyConfiguration({ proxyUrls: [...] })。PlaywrightCrawler 的源码级说明从 playwright-crawler.ts 的类注释可以看到PlaywrightCrawler的核心定位它基于 headless Chromium、Firefox 和 WebKit由 Playwright 驱动提供并行网页爬取框架URL 既可来自静态列表也可来自支持递归入队的动态请求队列因为通过真实浏览器执行 JavaScript它适合需要渲染 JS 的网站对于无需 JS 的站点官方明确建议改用CheerioCrawler——后者以原始 HTTP 请求抓取速度快约 10 倍每处理一个Request爬虫会打开一个新的浏览器标签页tab并调用用户提供的requestHandler浏览器实例池由 browser-pool 内部管理新页面只有在 CPU 与内存充足时才会开启并发度通过minConcurrency、maxConcurrency、maxRequestsPerMinute等选项调节。从构造函数的实现playwright-crawler.ts可以看出所有选项通过 Zod schema 校验解析optionsSchema基于z.strictObject非法配置会在构造阶段直接抛错若同时传入launchContext.proxyUrl会抛出异常并提示必须改用proxyConfiguration——这正是模板中代理配置以ProxyConfiguration形式出现的原因配置支持headless布尔选项默认true需要可视化调试时可显式关闭。四、路由系统 routes.ts基于标签的请求分发src/routes.ts 使用 Crawlee 的路由机制组织业务逻辑import { createPlaywrightRouter } from crawlee; export const router createPlaywrightRouter(); router.addDefaultHandler(async ({ enqueueLinks, log }) { log.info(enqueueing new URLs); await enqueueLinks({ include: [https://crawlee.dev/**], label: detail, }); }); router.addHandler(detail, async ({ request, page, log, pushData }) { const title await page.title(); log.info(${title}, { url: request.loadedUrl }); await pushData({ url: request.loadedUrl, title, }); });工作流程拆解默认处理器addDefaultHandler当请求没有指定标签label时执行。这里对每个已加载页面调用enqueueLinks通过include: [https://crawlee.dev/**]过滤出站内链接并给新入队的请求打上label: detail标签。命名处理器addHandler(detail)所有被打上detail标签的请求进入该分支通过 Playwright 的page.title()获取页面标题再用pushData把{ url, title }写入默认数据集Dataset。这一默认处理器负责发现链接并打标签、命名处理器负责提取数据的模式是 Crawlee 官方推荐的递归爬取范式对应仓库文档中的 crawl_all_links_playwright.ts 与 playwright_recursive_crawl.mdx 示例。Router 源码机制在 router.ts 中可以看到路由系统的设计细节默认路由使用唯一的defaultRouteSymbol 标识router.tsaddDefaultHandler注册的回调即挂载在该 Symbol 下RouteSchemas支持为每个标签声明请求userData的校验 schema支持 Zod、Valibot 等 Standard Schema 生态从而在编译期推导出每个路由的userData类型并在运行期校验入队请求的数据形状路由上下文会收窄request、addRequests、enqueueLinks的类型router.ts使入队带某标签的请求必须携带匹配的 userData这类约束在编译期即被强制这正是 TypeScript 模板的核心价值之一。请求处理器与重试语义requestHandler的语义定义在 playwright-crawler.ts处理器接收PlaywrightCrawlingContext其中page是已执行过page.goto(request.url)的 Playwright 页面response是主资源的响应对象。若处理器抛出异常爬虫会按maxRequestRetries重试全部重试失败后转入failedRequestHandler。因此编写处理器时应让异常自然抛出而不是自行吞掉。此外PlaywrightCrawlerOptions还支持preNavigationHooks导航前依次执行的钩子适合注入 Cookie、修改浏览器属性或调整gotoOptions如gotoOptions.timeout 60_000postNavigationHooks导航后执行的钩子典型用途是检测验证码并处理。五、本地开发与运行按模板package.json的脚本本地运行流程为# 1. 安装依赖postinstall 会自动下载 Playwright 浏览器 npm install # 2. 开发模式直接运行 TypeScript 源码 npm run start:dev # 3. 或一键走开发启动 npm run start生产环境则先构建再运行npm run build # tsc 编译到 dist/ npm run start:prod # node dist/main.js运行后爬虫会从https://crawlee.dev出发最多处理 20 个请求maxRequestsPerCrawl: 20将每个页面的{ url, title }结果写入默认数据集。如需爬取整站删掉该配置项即可。想要有头模式可视化观察可参考 headful_playwright.ts。六、Docker 容器化部署Dockerfile 采用多阶段构建将编译与运行环境分离充分利用 Docker 层缓存构建阶段builderFROM apify/actor-node-playwright-chrome:24-1.58.2 AS builder COPY --chownmyuser package*.json ./ RUN npm install --includedev --auditfalse COPY --chownmyuser . ./ RUN npm run build基础镜像为apify/actor-node-playwright-chrome:24-1.58.2预装 Node.js 24、Playwright 与 Chrome 浏览器仓库中关于镜像选型的完整说明见 docker_images.mdx先只拷贝package*.json再安装依赖是为了命中 Docker 层缓存——只有依赖文件变化时才重新执行npm install安装时使用--auditfalse跳过安全审计以加快速度。运行阶段FROM apify/actor-node-playwright-chrome:24-1.58.2 COPY --frombuilder --chownmyuser /home/myuser/dist ./dist COPY --chownmyuser package*.json ./ RUN npm --quiet set progressfalse \ npm install --omitdev \ echo Installed NPM packages: \ (npm list --omitdev --all || true) \ echo Node.js version: \ node --version \ echo NPM version: \ npm --version COPY --chownmyuser . ./ CMD ./start_xvfb_and_run_cmd.sh npm run start:prod --silent关键点仅从 builder 阶段拷贝编译产物dist/运行阶段只安装生产依赖--omitdev最终镜像更小COPY --chownmyuser保持文件归属与镜像内非 root 用户一致符合镜像安全约定启动命令先执行start_xvfb_and_run_cmd.sh为 headful 场景提供虚拟显示再以静默模式运行npm run start:prod如确定不需要有头浏览器可移除该脚本以换取微小性能提升。构建与运行docker build -t crawlee-playwright-ts . docker run crawlee-playwright-ts七、从模板到项目的改造路径基于该模板启动真实项目时通常只需修改三处startUrls替换为你的目标站点种子地址enqueueLinks的include规则按目标站点的 URL 结构设置链接过滤如https://example.com/**并可增加exclude排除无关路径routes.ts的处理器在detail路由中扩展pushData的数据结构或按业务拆分为更多带标签的路由。如需更复杂的路由类型约束可利用createPlaywrightRouter配合RouteSchemas为每个标签声明userData校验 schema参考 router.ts 的机制说明。八、延伸阅读PlaywrightCrawler 完整 API模板 README.md 指向的官方文档入口playwright_crawler.mdx 示例官方 Playwright 爬虫示例crawl_all_links_playwright.ts递归爬取全部链接的完整示例playwright_crawler.mdx 指南 与 avoid_blocking_playwright.ts浏览器爬虫的反封锁实践docker_images.mdxDockerfile 中使用的apify/actor-node-playwright-chrome镜像选型说明playwright-crawler 源码PlaywrightCrawler的完整实现含全部选项的 JSDoc 注释。该模板覆盖了依赖管理 → 浏览器初始化 → 递归入队 → 数据提取 → 容器化部署的完整链路是理解 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），仅供参考