📋 插件概述
这是一个基于Puppeteer的网页截图插件，支持响应式视口、自定义高度、移动端优化等功能。采用HTTP API架构，提供稳定可靠的截图服务。
🚀 核心特性
✅ 视口控制
viewport_width- 设置视口宽度viewport_height- 设置视口高度- 自动高度调整
✅ 截图模式
- 全页截图
- 视口截图
- 区域截图
✅ 移动端优化
- 移动端检测
- 触摸支持
- 设备像素比
🔧 输入参数说明
必需参数
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
url | string | - | 要截图的网页URL（必需） |
截图参数
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
full_page | boolean | false | 是否全页截图 |
viewport_width | integer | - | 视口宽度（像素） |
viewport_height | integer | - | 视口高度（像素，仅当full_page=false时有效） |
omit_background | boolean | false | 是否省略背景 |
clip | object | - | 截图区域（x, y, width, height） |
api_key | string | - | API密钥（可选，也可通过环境变量PUPPETEER_API_KEY设置） |
📤 输出结果
{
"success": true,
"message": "架构重设计截图成功",
"image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
"image_url": "https://puppeteer.caogiso.site/Cursor/puppeteer-api-server/screenshots/screenshot_1733212345.png",
"metadata": {
"plugin_version": "v5.2.0-AUTO-HEIGHT",
"architecture": "HTTP-API-MODE",
"domain": "puppeteer.caogiso.site",
"filename": "screenshot_1733212345.png",
"full_page": false,
"omit_background": false,
"clip": null,
"successful_endpoint": "https://puppeteer.caogiso.site/puppeteer-wrapper",
"total_duration": 5.2,
"screenshot_quality": "optimized",
"api_usage": {
"daily_used": 15,
"daily_limit": 100,
"used_count": 150,
"total_limit": 1000
},
"price_site_url": "https://price.caogiso.site/"
}
}提示：image_url 为公开访问链接，image_base64 为Base64编码的图片数据。
示例1：移动端固定高度截图
{
"url": "https://example.com",
"full_page": false,
"viewport_width": 375,
"viewport_height": 667
}示例2：桌面端自动高度截图
{
"url": "https://example.com",
"full_page": true,
"viewport_width": 1200
}示例3：区域截图
{
"url": "https://example.com",
"viewport_width": 1200,
"viewport_height": 800,
"clip": {
"x": 100,
"y": 200,
"width": 800,
"height": 600
}
}示例4：透明背景截图
{
"url": "https://example.com",
"viewport_width": 375,
"viewport_height": 667,
"omit_background": true
}📱 设备预设
iPhone设备
iPhone 6/7/8: 375×667
iPhone X/11/12/13: 375×812
iPhone 14/15: 390×844
Android设备
Google Pixel: 411×731
Samsung Galaxy: 360×640
桌面端预设
1920×1080 (Full HD)
1366×768 (HD)
1440×900 (MacBook)
🏗️ 技术架构
HTTP API模式
- 主服务:
https://puppeteer.caogiso.site/puppeteer-wrapper - 超时设置: 180秒（3分钟）
- 重试机制: 自动重试多个API端点
- 认证方式: API Key认证
视口策略
- 固定高度模式:
full_page=false+viewport_height - 自动高度模式:
full_page=true→ 自动调整 - 默认模式: 无视口参数 → 桌面端1920x1080
📊 性能指标
响应时间
- 简单页面: 3-5秒
- 复杂页面: 10-30秒
- 动态页面: 30-60秒
成功率
- 标准网页: 99%+
- 复杂应用: 95%+
- 动态内容: 90%+
并发能力
- 单实例: 支持10+并发请求
- 多实例: 可通过负载均衡扩展
🐛 常见问题
- 截图超时 - 检查网络连接，增加超时时间，确认目标网站可访问
- 视口设置不生效 - 确认参数类型正确（数字），检查full_page参数设置
- 移动端显示异常 - 确认viewport_width < 768px，检查设备像素比
- API密钥问题 - 确认API密钥有效，检查用量是否超限
🔧 调试方法
- 查看日志: 检查HTTP包装器日志文件
- 测试API: 直接调用HTTP API端点
- 参数验证: 确认所有参数类型和格式正确
- 用量检查: 通过API验证接口检查用量状态
📞 技术支持
如有问题，请检查：
- HTTP包装器服务状态
- 网络连接和防火墙设置
- 目标网站的可访问性
- 参数格式和类型
- API密钥有效性