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

配置选项

配置文件属性

| JPEG质量（1-100） |

{
  "width": 1920,
  "height": 1080,
  "label": "desktop-fullhd"
}

• width视口对象
• height视口宽度（以像素为单位）
• label视口高度（以像素为单位）

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

--config 
     Path to configuration file
--url          Single URL to capture (can be used multiple times)
--output       Output directory for snapshots
--width 
        Viewport width (can be used multiple times)
--height 
       Viewport height (can be used multiple times)
--wait          Wait time after page load
--format      Image format: png or jpeg
--quality    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）

作者