AI导哈

浏览器快照工具

一款强大的无头浏览器工具，用于捕获多个配置窗口大小的页面快照，使视觉调试和响应式测试变得简单。

  • by Apra-Labs
  • JavaScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 Apra-Labs/browser-snapshot-agent

使用说明

浏览器快照代理

一个强大的无头浏览器工具，能够在多种预设的窗口尺寸下捕获页面快照，使视觉调试和响应式测试变得轻松简单。

特点/功能

  • 🚀 使用Puppeteer实现无头浏览器自动化
  • 📱 可配置的视口大小（手机、平板、桌面）
  • 📸 全页截图或仅视口截图
  • 🎯 单次运行中处理多个URL和视口
  • ⚙️ 通过JSON或CLI参数进行灵活配置
  • 📊 详细的捕获总结和错误报告
  • 🏷️ 视口的自定义标签
  • 🖼️ PNG或JPEG输出格式
  • ⏱️ 可配置的动态内容等待时间
  • 机器人 MCP（模型上下文协议）服务器 - 与AI助手（如Claude）一起使用

安装

cd browser-snapshot-agent
npm install

使用方法/用途

MCP服务器模式（与AI助手配合使用）

浏览器快照代理可以作为MCP（模型上下文协议）服务器运行，允许像Claude这样的AI助手通过编程方式捕获屏幕截图。

设置

  1. 安装依赖项：
cd browser-snapshot-agent
npm install
  1. 配置您的AI助手 使用MCP服务器。对于Claude Desktop，请在您的配置文件中添加：

Windows： %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "browser-snapshot": {
      "command": "node",
      "args": [
        "C:\\path\\to\\browser-snapshot-agent\\mcp-server.js"
      ]
    }
  }
}
  1. 重启您的AI助手 加载MCP服务器。

可用的MCP工具

一旦配置完成，AI助手即可使用这些工具：

1. capture_snapshot - 捕捉一张单独的屏幕截图

  • 参数： url， width， height， label， outputDir， fullPage， waitTime， format
  • 示例： “以1920x1080分辨率截取https://example.com的屏幕截图”

2. capture_multiple_viewports - 在多个视口尺寸下进行捕获

  • 参数： url， viewports[]， outputDir， fullPage， waitTime， format
  • 示例： “在手机、平板和桌面尺寸下捕获example.com”

3. capture_responsive_set - 使用常见设备尺寸进行完整的响应式测试

  • 参数： url， outputDir， fullPage， waitTime
  • 示例： “对 https://mysite.com 进行全面的响应式测试”

4. capture_from_config - 使用配置文件

  • 参数： configPath
  • 示例： “使用config.json捕获屏幕截图”

MCP 使用示例

在MCP服务器运行的情况下，您可以向您的AI助手询问：

  • “以1920x1080分辨率截取https://example.com的屏幕截图”
  • “为 https://mysite.com 在手机、平板和桌面视口上截取屏幕截图”
  • “对 https://myapp.com 进行完整的响应式设计测试，并将结果保存到 ./test-snapshots”
  • “在iPhone SE和iPhone 12尺寸下捕获https://example.com页面”

人工智能助手将使用MCP工具执行这些请求，并返回捕获的屏幕截图的文件路径。

独立CLI模式

你也可以直接在命令行中使用该代理：

1. 使用配置文件（推荐）

创建或修改 config.json:

{
  "urls": [
    "https://example.com",
    "https://example.com/about"
  ],
  "viewports": [
    {
      "width": 1920,
      "height": 1080,
      "label": "desktop-fullhd"
    },
    {
      "width": 375,
      "height": 667,
      "label": "mobile-iphone-se"
    }
  ],
  "outputDir": "./snapshots",
  "waitTime": 1000,
  "fullPage": true,
  "format": "png",
  "quality": 90
}

然后运行：

node index.js --config config.json

或者简单地（使用默认的config.json）：

node index.js

2. 使用命令行接口（CLI）参数

快速单个URL捕获：

node index.js --url https://example.com --width 1920 --height 1080

多个视口：

node index.js \
  --url https://example.com \
  --width 1920 --height 1080 \
  --width 375 --height 667 \
  --output ./my-snapshots

多个URL：

node index.js \
  --url https://example.com \
  --url https://example.com/about \
  --width 1920 --height 1080

配置选项

配置文件属性

属性 类型 默认值 描述
项目 类别 数量 描述
数组 必填 需要捕获的URL列表 viewports
数组 必需 视口配置 outputDir
截图输出目录 waitTime 1000 数字
页面加载后的等待时间（毫秒） fullPage true 布尔值
捕获整个页面或仅捕获视口 format png 字符串
quality 90 数字

| JPEG质量（1-100） |

{
  "width": 1920,
  "height": 1080,
  "label": "desktop-fullhd"
}
  • width视口对象
  • height视口宽度（以像素为单位）
  • label视口高度（以像素为单位）

（可选）为文件名自定义标签

--config <path>     Path to configuration file
--url <url>         Single URL to capture (can be used multiple times)
--output <dir>      Output directory for snapshots
--width <px>        Viewport width (can be used multiple times)
--height <px>       Viewport height (can be used multiple times)
--wait <ms>         Wait time after page load
--format <type>     Image format: png or jpeg
--quality <0-100>   JPEG quality
--full-page         Capture full page (default: true)
--no-full-page      Capture viewport only
--help, -h          Show help message

CLI 选项

常见的视口尺寸 config.json 默认值

包括以下常见尺寸：

  • 桌面 1920x1080
  • - 全高清桌面 1366x768

- 高清桌面

  • 药片，平板 768x1024
  • - iPad 横屏模式 1024乘768

- iPad 横屏模式

  • 手机 375乘667
  • - iPhone SE 390乘844
  • - iPhone 12/13 414乘896
  • - iPhone 11 Pro Max 360x640

- 安卓

输出

{hostname}_{path}_{width}x{height}_{label}_{timestamp}.{format}

截图保存时使用了描述性的文件名：

example_com__1920x1080_desktop-fullhd_2025-01-15T10-30-45.png

示例：

测试

npm test

运行测试脚本来验证安装：

这将捕获example.com在桌面端和移动端尺寸的测试快照。

用例

视觉回归测试

在更改前后捕获快照以检测视觉差异。

响应式设计验证

测试您的网站在不同设备尺寸上的显示效果。

文档

为文档或演示文稿生成截图。

质量保证

将视觉检查自动化作为您质量保证流程的一部分。

多页面测试

一次性捕获所有重要页面以供审查。

高级示例

{
  "urls": [
    "http://localhost:8080",
    "http://localhost:8080/api-keys.html",
    "http://localhost:8080/quick-start.html"
  ],
  "viewports": [
    { "width": 1920, "height": 1080, "label": "docs-desktop" }
  ],
  "outputDir": "./docs-screenshots",
  "waitTime": 2000
}

捕获特定页面以用于文档编制

{
  "urls": ["https://myapp.com"],
  "viewports": [
    { "width": 375, "height": 667, "label": "iphone-se" },
    { "width": 390, "height": 844, "label": "iphone-12" },
    { "width": 393, "height": 851, "label": "pixel-5" }
  ],
  "fullPage": false,
  "format": "jpeg",
  "quality": 85
}

移动优先测试

{
  "urls": ["https://myproduct.com"],
  "viewports": [
    { "width": 2560, "height": 1440, "label": "4k-desktop" }
  ],
  "format": "png",
  "waitTime": 3000,
  "fullPage": true
}

用于营销的高质量截图

故障排除

Puppeteer 安装问题

npm install puppeteer --legacy-peer-deps

如果你在Windows上安装Puppeteer时遇到问题：

set PUPPETEER_SKIP_DOWNLOAD=true
npm install

或者设置环境变量：

超时错误

{
  "waitTime": 5000
}

如果页面加载时间较长，请增加等待时间：

缺失内容

  • 如果截图是在内容加载之前拍摄的： waitTime
  • 增加
  • 确保页面无需身份验证

检查页面中的JavaScript错误

许可证

麻省理工学院（MIT）

作者

相关 MCP