Puppeteer Real Browser Hono

一个使用 Hono 和 puppeteer-real-browser 构建的网页抓取 API 服务，提供 HTTP 端点以使用真实浏览器实例获取网页内容。

特性

• 🚀 使用 Hono 框架构建的快速轻量 API
• 🌐 基于 puppeteer-real-browser 的真实浏览器自动化
• 🔄 支持单次请求中的多个 URL
• 🎯 基于 CSS 选择器的特定元素内容等待
• 🛡️ 内置广告拦截（使用 @ghostery/adblocker-puppeteer）
• 🔒 Turnstile 防护处理
• 💾 内置 LRU 缓存机制（默认 TTL 为 5 分钟）
• 🔐 并发控制（最大 5 个并发页面）
• 🐳 完整 Docker 支持
• ⚡ 使用 TypeScript 编写，确保类型安全

安装

npm install

开发

使用热重载运行开发服务器：

npm run dev

服务器将在 http://localhost:3000 启动

生产环境

构建项目：

npm run build

启动生产服务器：

npm start

Docker 部署

构建 Docker 镜像：

docker build -t puppeteer-real-browser-hono .

运行容器：

docker run -p 3000:3000 puppeteer-real-browser-hono

API 使用

端点

GET /

查询参数

示例

基本用法

从单个 URL 获取内容：

curl "http://localhost:3000?url=https://example.com"

使用 CSS 选择器

等待特定元素出现后再捕获内容：

curl "http://localhost:3000?url=https://example.com&selector=.main-content"

多个 URL

同时从多个 URL 获取内容：

使用导航选项

自定义导航行为：

curl "http://localhost:3000?url=https://example.com&waitUntil=networkidle2&timeout=60000"

响应格式

成功响应

{
"success": true,
"fromCache": false,
"data": [" ... "]
}

错误响应

{
"success": false,
"error": "Error message"
}

项目结构

.
├── src/
│ ├── index.ts # API 服务器和路由
│ ├── lib.ts # 带信号量的核心页面内容抓取逻辑
│ └── cache.ts # LRU 缓存实现
├── Dockerfile # Docker 配置
├── package.json # 项目依赖
├── tsconfig.json # TypeScript 配置
└── README.md # 本文档

配置

浏览器实例配置如下：

• 窗口最大化：浏览器启动时窗口最大化
• Turnstile 支持：启用以处理 Cloudflare 验证
• 无头模式：禁用（运行可见浏览器）
• 默认视口：Null（使用完整窗口大小）

您可以通过调整 src/lib.ts 中的 realBrowserOption 对象修改这些设置。

依赖项

生产依赖

• @hono/node-server：Hono 的 Node.js 适配器
• hono：快速轻量的 Web 框架
• puppeteer-real-browser：用于真实浏览器自动化的 Puppeteer 包装器
• @ghostery/adblocker-puppeteer：Puppeteer 的广告拦截器
• lru-cache：LRU 缓存实现

开发依赖

• @types/node：Node.js 的 TypeScript 类型定义
• tsx：用于开发的 TypeScript 执行器
• typescript：TypeScript 编译器

技术细节

浏览器配置

本服务使用 puppeteer-real-browser，其提供：

• 真实浏览器指纹
• Cloudflare Turnstile 绕过能力
• 相比标准 Puppeteer 更好的反检测能力

选择器等待逻辑

当提供 selector 参数时，服务将：

1. 导航至 URL
2. 每 1 秒轮询一次选择器是否存在
3. 在指定超时时间后超时（默认：30 秒）
4. 找到选择器后捕获页面内容

许可证

MIT

贡献

欢迎贡献！请随时提交 Pull Request。