用途
browse 是一个浏览器自动化命令行工具,配合 Claude 使用,用于自动化浏览器交互。它可以通过 CLI 命令导航网页、提取数据、截图、填写表单,并与 Web 应用进行交互。
环境选择(本地与远程)
CLI 会根据可用配置自动在本地和远程浏览器环境之间选择:
- 本地模式(默认):使用本地 Chrome,无需 API 密钥。适合开发、简单页面、无机器人防护的可信站点。
- 远程模式(Browserbase):当设置了 BROWSERBASE_API_KEY 和 BROWSERBASE_PROJECT_ID 时激活。提供反机器人隐身、自动验证码识别、住宅代理、会话持久化。适用于目标站点有机器人检测、验证码、IP 限流、Cloudflare 防护,或需要特定地区访问的场景。凭据可在 https://browserbase.com/settings 获取。
选择建议:简单浏览(文档、维基、公共 API)使用本地模式即可;受保护站点(登录墙、验证码、反爬)使用远程模式;如果本地模式因机器人检测或访问被拒而失败,切换到远程模式。
主要能力
所有命令在两种模式下行为一致,守护进程在首次命令时自动启动。
导航
- browse open <url>:跳转到 URL(别名:goto)
- browse reload:重新加载当前页面
- browse back:在历史中后退
- browse forward:在历史中前进
页面状态(优先使用 snapshot 而非 screenshot)
- browse snapshot:获取带元素引用的可访问性树(快速、结构化)
- browse screenshot [path]:截取可视化屏幕截图(较慢,消耗视觉 token)
- browse get url:获取当前 URL
- browse get title:获取页面标题
- browse get text <selector>:获取文本内容(使用 "body" 获取全部文本)
- browse get html <selector>:获取元素的 HTML 内容
- browse get value <selector>:获取表单字段值
建议默认使用 browse snapshot 来理解页面状态,它返回带元素引用的可访问性树,可用于交互。仅在需要视觉上下文(布局、图片、调试)时使用 browse screenshot。
交互
- browse click <ref>:按 snapshot 中的引用点击元素(例如 @0-5)
- browse type <text>:向聚焦元素输入文本
- browse fill <selector> <value>:填写输入框并回车
- browse select <selector> <values...>:选择下拉选项
- browse press <key>:按键(Enter、Tab、Escape、Cmd+A 等)
- browse drag <fromX> <fromY> <toX> <toY>:从一点拖拽到另一点
- browse scroll <x> <y> <deltaX> <deltaY>:在坐标处滚动
- browse highlight <selector>:在页面上高亮元素
- browse is visible <selector>:检查元素是否可见
- browse is checked <selector>:检查元素是否被勾选
- browse wait <type> [arg]:等待 load、selector 或 timeout
会话管理
- browse stop:停止浏览器守护进程
- browse status:检查守护进程状态(包含环境)
- browse env:显示当前环境(本地或远程)
- browse env local:切换到本地 Chrome
- browse env remote:切换到 Browserbase(需要 API 密钥)
- browse pages:列出所有打开的标签页
- browse tab_switch <index>:按索引切换标签页
- browse tab_close [index]:关闭标签页
使用方式
安装检查
在运行任何浏览器命令之前,先验证 CLI 是否可用:
which browse || npm install -g @browserbasehq/browse-cli
典型工作流
- browse open <url>:导航到页面
- browse snapshot:读取可访问性树,理解页面结构并获取元素引用
- browse click <ref> / browse type <text> / browse fill <selector> <value>:使用 snapshot 中的引用进行交互
- browse snapshot:确认操作生效
- 按需重复第 3-4 步
- browse stop:完成后关闭浏览器
快速示例
browse open https://example.com browse snapshot # 查看页面结构 + 元素引用 browse click @0-5 # 点击引用为 0-5 的元素 browse get title browse stop
模式对比
| 特性 | 本地 | Browserbase |
|---|---|---|
| 速度 | 更快 | 稍慢 |
| 设置 | 需要 Chrome | 需要 API 密钥 |
| 隐身模式 | 否 | 是(定制 Chromium、反机器人指纹) |
| 验证码识别 | 否 | 是(自动 reCAPTCHA/hCaptcha) |
| 住宅代理 | 否 | 是(201 个国家、地理定位) |
| 会话持久化 | 否 | 是(cookie/认证跨会话保持) |
| 最适合 | 开发/简单页面 | 受保护站点、机器人检测、生产级抓取 |
适用场景
- 简单浏览:文档、维基、公共 API,使用本地模式。
- 受保护站点:登录墙、验证码、反爬,使用远程模式。
- 生产级抓取:需要隐身、代理、会话持久化时使用远程模式。
最佳实践
- 交互前始终先执行 browse open。
- 使用 browse snapshot 检查页面状态,它快速且提供元素引用。
- 仅在需要视觉上下文(布局检查、图片、调试)时使用 screenshot。
- 使用 snapshot 中的引用进行点击/交互,例如 browse click @0-5。
- 完成后执行 browse stop 清理浏览器会话。
限制与故障排查
- "No active page":运行 browse stop,然后检查 browse status。如果仍显示运行中,用 pkill -f "browse.*daemon" 杀掉僵尸守护进程,再重试 browse open。
- 找不到 Chrome:安装 Chrome 或使用 browse env remote。
- 操作失败:运行 browse snapshot 查看可用元素及其引用。
- Browserbase 失败:确认 API 密钥和项目 ID 已设置。
切换到远程模式
当检测到以下情况时切换到远程:验证码(reCAPTCHA、hCaptcha、Turnstile)、机器人检测页面("Checking your browser...")、HTTP 403/429、本应有内容的站点出现空白页,或用户要求时。
简单站点(文档、维基、公共 API、localhost)不要切换。
browse env remote # 切换到 Browserbase browse env local # 切回本地 Chrome
切换在运行 browse stop 或再次切换之前保持有效。
更多详细示例见 EXAMPLES.md,API 参考见 REFERENCE.md。