浏览器循环

Name: 浏览器循环
Author: mattiasw

作者：mattiasw23 星标更新：2025-10-02

安装使用来源：spider==github.com

项目介绍

BrowserLoop

⚠️ 已归档: 该项目已归档，不再接收任何更新。随着 Chrome DevTools MCP 的发布，专门用于浏览器自动化的 MCP 服务器已不再必要，因为该项目提供了更全面的浏览器交互功能，包括截图、控制台监控等。

一个使用 Playwright 从网页中抓取截图和读取控制台日志的 Model Context Protocol (MCP) 服务器。此工具允许 AI 代理自动捕获截图并监控浏览器控制台输出，用于调试、测试和开发任务。

注意： 本仓库中的几乎所有代码都是自动生成的。这意味着您可能不应完全信任它。尽管如此，它确实可以工作，并且我自己也在使用它。

注意： 如果文档不正确，请告知我或提交 PR。如果您也想使用代码生成工具来更新此项目的代码，PROJECT_CONTEXT.md 已被用作上下文，以提供对项目各个部分的良好概述。现在可能有点混乱，但它是一个很好的起点，欢迎您进行更新。

功能

📸 使用 Playwright 捕获高质量截图
📝 监控和收集网页的控制台日志
🌐 支持本地主机和远程 URL
🍪 基于 Cookie 的认证，用于保护页面
🐳 使用 Docker 容器化以实现一致的环境
⚡ 支持 PNG、JPEG 和 WebP 格式，可配置质量
🛡️ 安全的非 root 容器执行
🤖 完整集成 MCP 协议与 AI 开发工具
🔧 可配置视口大小和捕获选项
📱 全页和特定元素的截图捕获
⚠️ 浏览器警告和错误捕获（Permissions-Policy、安全警告）
⚡ 使用 TypeScript 和 Biome 进行快速开发
🧪 使用 Node.js 内置测试运行器进行全面测试

快速开始

📦 NPX 使用（推荐）

最简单的入门方式——无需安装！

# 安装 Chromium 浏览器（一次性设置）
npx playwright install chromium

# 测试 BrowserLoop 是否正常工作
npx browserloop@latest --version

就这样！ 最新版本的 BrowserLoop 将自动下载并执行。非常适合希望零维护截图的 MCP 用户。

MCP 配置

在您的 MCP 配置文件（例如 ~/.cursor/mcp.json）中添加 BrowserLoop：

{
  "mcpServers": {
    "browserloop": {
      "command": "npx",
      "args": ["-y", "browserloop@latest"],
      "description": "使用 Playwright 从网页中捕获截图和控制台日志的服务器"
    }
  }
}

💡 使用 @latest 确保您始终获得最新的特性和错误修复。

🚀 一键安装到 Cursor

使用此深度链接单击即可将 BrowserLoop 添加到 Cursor：

🔗 将 BrowserLoop 添加到 Cursor

此深度链接将自动在您的 Cursor MCP 设置中配置 BrowserLoop，使用 npx 和最新版本的最佳配置。

前提条件： 确保您已经安装了 Chromium：

npx playwright install chromium

浏览器安装要求

🚨 关键点： 在能够截屏之前，BrowserLoop 需要通过 Playwright 安装 Chromium。

第一次设置（所有用户）

安装 Chromium 浏览器：

npx playwright install chromium

验证安装：

# 检查 Playwright 安装
npx playwright --version

# 测试 BrowserLoop（如果使用 NPX）
npx browserloop@latest --version

🐳 Docker 替代方案

对于容器化环境：

# 使用 Docker 拉取并运行
docker run --rm --network host browserloop

# 或者使用 docker-compose 进行开发
git clone <repository-url>
cd browserloop
docker-compose -f docker/docker-compose.yml up

💻 开发安装

对于贡献者或希望从源码构建的高级用户：

# 克隆仓库
git clone <repository-url>
cd browserloop

# 安装依赖
npm install

# 安装 Playwright 浏览器（截图所需）
npx playwright install chromium
# 或者使用方便的脚本：
npm run install-browsers

# 构建项目
npm run build

开发 MCP 配置

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": [
        "/absolute/path/to/browserloop/dist/src/index.js"
      ],
      "description": "使用 Playwright 从网页中捕获截图和控制台日志的服务器"
    }
  }
}

替换 /absolute/path/to/browserloop/ 为您实际的项目路径。

基本用法

配置完成后，您可以在 AI 工具中使用自然语言命令：

截图

截取 https://example.com 的截图
截取 https://example.com 的截图，宽度 1920，高度 1080
截取 https://example.com 的截图，格式为 JPEG，质量 95%
截取 https://example.com 的全页截图
截取 http://localhost:3000 的截图，以验证 UI 更改

控制台日志读取

读取 https://example.com 的控制台日志
检查 https://example.com 上的控制台错误
监控 http://localhost:3000 的控制台警告
仅读取 https://example.com 的错误和警告日志
捕获 https://example.com 的控制台输出以供调试

🔐 Cookie 认证

BrowserLoop 支持基于 Cookie 的认证，用于在开发过程中捕获受登录保护页面的截图：

使用这些 Cookie 截取 http://localhost:3000/admin/dashboard 的截图：[{"name":"connect.sid","value":"s:session-id.signature","domain":"localhost"}]

📖 有关 Cookie 提取方法和开发流程，请参阅：

📖 Cookie 认证指南

常见开发用例：

带有身份验证的本地开发服务器
预发布环境测试
API 文档工具（如 Swagger、GraphQL Playground）
开发期间的自定义 Web 应用程序
管理面板和受保护的路由

文档

🔐 Cookie 认证指南 - 完整的认证截图指南
📚 完整 API 参考 - 参数详细文档、示例及响应格式

关键 API 参数

参数	类型	描述	默认值
`url`	string	要捕获的目标 URL（必需）	-
`width`	number	视口宽度（200-4000）	1280
`height`	number	视口高度（200-4000）	720
`format`	string	图像格式（webp, png, jpeg）	webp
`quality`	number	图像质量（1-100）	80
`fullPage`	boolean	捕获全页	false
`selector`	string	用于元素捕获的 CSS 选择器	-

📖 详情请参阅 docs/API.md，包括参数细节、使用示例及配置选项。

配置

BrowserLoop 可以通过环境变量进行配置：

基本配置

变量	默认值	描述
`BROWSERLOOP_DEFAULT_WIDTH`	`1280`	默认视口宽度（200-4000）
`BROWSERLOOP_DEFAULT_HEIGHT`	`720`	默认视口高度（200-4000）
`BROWSERLOOP_DEFAULT_FORMAT`	`webp`	默认图像格式（`webp`, `png`, `jpeg`）
`BROWSERLOOP_DEFAULT_QUALITY`	`80`	默认图像质量（0-100）
`BROWSERLOOP_DEFAULT_TIMEOUT`	`30000`	默认超时时间（毫秒）
`BROWSERLOOP_USER_AGENT`	-	自定义 User-Agent 字符串

认证配置

变量	默认值	描述
`BROWSERLOOP_DEFAULT_COOKIES`	-	默认 Cookie 文件路径或 JSON 字符串（参见 Cookie 认证指南）

控制台日志配置

变量	默认值	描述
`BROWSERLOOP_CONSOLE_LOG_LEVELS`	`log,info,warn,error,debug`	要捕获的日志级别逗号分隔列表
`BROWSERLOOP_CONSOLE_TIMEOUT`	`30000`	页面导航超时时间（毫秒），而非日志收集时间
`BROWSERLOOP_SANITIZE_LOGS`	`true`	启用/禁用日志中的敏感数据屏蔽
`BROWSERLOOP_CONSOLE_WAIT_NETWORK_IDLE`	`true`	在完成收集前等待网络空闲
`BROWSERLOOP_MAX_LOG_SIZE`	`1048576`	总日志大小的最大值（字节，1MB）

注意： 日志收集总是会在页面加载后等待恰好 3 秒钟以捕获控制台消息。超时设置仅影响页面最初加载的时间。

日志屏蔽

控制台日志屏蔽默认启用（BROWSERLOOP_SANITIZE_LOGS=true），以保护敏感信息。启用时，以下模式将自动被屏蔽：

模式类型	示例输入	屏蔽输出
API 密钥	`sk_live_1234567890abcdef...`	`[API_KEY_MASKED]`
电子邮件地址	`user@example.com`	`[EMAIL_MASKED]`
JWT 令牌	`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`	`[JWT_TOKEN_MASKED]`
认证头	`Bearer abc123token...`	`[AUTH_HEADER_MASKED]`
带认证的 URL	`https://api.com/data?token=secret123`	`[URL_WITH_AUTH_MASKED]`
秘密变量	`password: mySecretPass`	`password: [VALUE_MASKED]`

要禁用屏蔽（用于调试）：

BROWSERLOOP_SANITIZE_LOGS=false

注意：屏蔽保留日志结构，同时屏蔽敏感内容，使日志安全地共享和分析。

性能与可靠性

变量	默认值	描述
`BROWSERLOOP_RETRY_COUNT`	`3`	失败操作的重试次数
`BROWSERLOOP_RETRY_DELAY`	`1000`	重试之间的延迟（毫秒）

日志记录与调试

变量	默认值	描述
`BROWSERLOOP_DEBUG`	`false`	启用调试日志记录到 `/tmp/browserloop.log`
`BROWSERLOOP_ENABLE_METRICS`	`true`	启用错误指标收集
`BROWSERLOOP_DISABLE_FILE_WATCHING`	`false`	禁用自动 Cookie 文件监控

调试日志记录

当 BROWSERLOOP_DEBUG=true 时，详细的日志将写入 /tmp/browserloop.log，包括：

Cookie 文件加载和自动刷新事件
文件监控状态和重新创建事件
截图操作细节
配置更改和错误

实时监控日志：

tail -f /tmp/browserloop.log

注意：日志写入文件（而非控制台），以保持与 MCP 的 stdio 协议兼容性。

示例 MCP 配置，带有默认 Cookie

方法 1：JSON 文件（推荐）

创建一个 Cookie 文件：

// ~/.config/browserloop/cookies.json
[
  {
    "name": "connect.sid",
    "value": "s:your-dev-session.signature",
    "domain": "localhost"
  }
]

在 MCP 配置中引用：

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": ["dist/src/mcp-server.js"],
      "env": {
        "BROWSERLOOP_DEFAULT_COOKIES": "/home/username/.config/browserloop/cookies.json",
        "BROWSERLOOP_DEFAULT_FORMAT": "webp",
        "BROWSERLOOP_DEFAULT_QUALITY": "85"
      }
    }
  }
}

方法 2：JSON 字符串（旧版）

{
  "mcpServers": {
    "browserloop": {
      "command": "node",
      "args": ["dist/src/mcp-server.js"],
      "env": {
        "BROWSERLOOP_DEFAULT_COOKIES": "[{\"name\":\"session_id\",\"value\":\"your_session_value\",\"domain\":\"example.com\"},{\"name\":\"auth_token\",\"value\":\"your_auth_token\"}]",
        "BROWSERLOOP_DEFAULT_FORMAT": "webp",
        "BROWSERLOOP_DEFAULT_QUALITY": "85"
      }
    }
  }
}

控制台日志配置示例

# 仅捕获警告和错误
BROWSERLOOP_CONSOLE_LOG_LEVELS="warn,error"

# 调试模式，包含所有日志，无屏蔽
BROWSERLOOP_DEBUG="true"
BROWSERLOOP_SANITIZE_LOGS="false"
BROWSERLOOP_CONSOLE_LOG_LEVELS="log,info,warn,error,debug"

故障排除

常见问题

“可执行文件不存在” 错误

# 安装 Chromium 浏览器（最常见的解决办法）
npx playwright install chromium

MCP 服务器无法启动

手动测试：npx browserloop@latest --version
验证需求：
- Node.js 20+：node --version
- npm：npm --version
- npx：npx --version
检查 MCP 配置 JSON 语法

截图显示登录页面

使用 Cookie 认证（参见 Cookie 认证指南）
检查 Cookie 过期时间和域设置

控制台日志为空

一些生产网站没有控制台输出（这是正常的）
使用具有控制台活动的开发站点进行测试
启用调试日志记录：BROWSERLOOP_DEBUG=true 并检查 /tmp/browserloop.log
检查日志级别过滤：BROWSERLOOP_CONSOLE_LOG_LEVELS=log,info,warn,error,debug

控制台日志收集时机

收集总是在页面加载后等待恰好 3 秒钟
BROWSERLOOP_CONSOLE_TIMEOUT 控制页面加载超时时间，而非日志收集时间
快速站点仍然需要大约 3-4 秒（加载 + 3 秒收集 + 处理）

网络/连接问题

首先测试外部 URL：https://example.com
对于本地主机：确保您的开发服务器正在运行
检查防火墙设置

更新 BrowserLoop

NPX：使用 @latest 自动使用最新版本——无需手动更新！
检查当前版本：npx browserloop@latest --version

快速诊断

# 测试完整设置
node --version && npm --version
npx playwright --version

# 测试 BrowserLoop
npx browserloop@latest --version

启用调试日志记录： 在您的 MCP 配置中设置 BROWSERLOOP_DEBUG=true 并监控 /tmp/browserloop.log

📖 请参阅 docs/API.md#error-handling 以获取详细的故障排除信息。

许可证

BrowserLoop 采用 GNU Affero General Public License v3.0 或更高版本 (AGPL-3.0-or-later) 许可证。

这意味着：

✅ 免费使用 - 允许个人和商业用途
✅ 自由修改 - 您可以根据需要调整代码
✅ 自由分发 - 分享副本给其他人
✅ 专利保护 - 贡献者提供专利授权
⚠️ 版权 - 衍生作品必须也以 AGPL-3.0 开源