Browserbase CLI配置常见错误与解决

BrowserbaseCLIClaudeSkills插件配置

我在配置Browserbase CLI和skills插件时踩了5个坑，前后花了4小时才全部打通。这篇文章复盘每个问题的根因和解决方案。

问题1：API KEY格式错误导致的 "Authentication failed"

安装完成后第一步就是配置API KEY：

npm install -g @browserbasehq/browse-cli
browse auth --key YOUR_API_KEY

我遇到的第一个错误：

Error: Authentication failed. Please check your API key.

**根因**：Browserbase的API KEY需要从 https://browserbase.com/settings 的 "Developer" 标签页获取，不是在项目设置里。而且KEY格式是 sk-... 开头的，但有些人的环境变量会错误地加上引号。

解决：

# 正确做法：直接赋值，不加引号
export BROWSERBASE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

# 验证是否生效
browse auth status

问题2：local模式和remote模式的选择困惑

Browserbase CLI有两种运行环境，很多人在第一次使用时不知道选哪个：

**local模式**：`browse env local` — 使用本机Chrome，无额外费用
**remote模式**：`browse env remote` — 使用Browserbase云端浏览器，按时间计费

踩坑记录：我一开始以为remote模式更"专业"，结果：

1. 每次测试都要花钱

2. CAPTCHAsolving在Start计划不包含，需要升级到Developer计划（$99/月）

3. 延迟比local模式高（~200ms vs 本地即时）

正确选择：

**开发调试** → local模式
**生产环境/爬取被保护站点** → remote模式

# 开发阶段用local
browse env local
browse open https://example.com

# 生产环境切换到remote
browse env remote
browse open --context-id my-session https://example.com

问题3：context ID持久化失败

Browserbase的核心功能之一是session持久化——你可以保存登录状态，下次直接复用。

# 保存context（包含cookies、localStorage等）
browse open --context-id my-session --persist https://mail.google.com

# 之后加载这个session
browse open --context-id my-session

踩坑：我按照官方文档操作，第二次加载时发现session丢失了。

**根因**：context ID在Start计划（免费）只能保存7天。7天后自动清理。而且--persist参数只在remote模式下有效，local模式不支持。

验证方法：

# 查看当前context列表
bb contexts list

# 查看某个context的剩余有效期
bb contexts get

问题4：CAPTCHA计费陷阱

Browserbase的CAPTCHA solving功能是按次计费的，但很多人在免费计划里被坑了：

**Start计划（免费）**：不包含CAPTCHA solving
**Developer计划（$99/月）**：包含CAPTCHA solving，但有次数限制（$5额度/月）

踩坑场景：我用Start计划测试一个需要CAPTCHA的网站，任务一直卡在验证页面，以为是bug：

browse open https://example.com requiring-captcha
# 卡在验证码页面，无法继续

后来看账单才发现请求一直在重试，每次都在消耗。

正确做法：

1. 先用 browse what-antibot 检测目标站点是否有CAPTCHA保护

2. 如果有，且需要自动解决 → 至少升级到Developer计划

3. 如果只是测试 → 用 browse env local + 手动解决验证码

# 先检测站点类型
browse what-antibot https://target-site.com

问题5：代理区域限制

Browserbase的remote模式提供 residential proxies（住宅IP），但IP的地理位置是固定的：

计划	代理区域
Start	美国、加拿大、欧洲（随机）
Developer	同上 + 可指定区域
Startup/Growth/Enterprise	支持更多地区（亚洲、大洋洲等）

踩坑：我测试一个需要日本IP的网站，用的是Start计划，结果所有请求都被路由到了美国节点，网站检测到IP不匹配直接拒绝了。

解决：

1. 如果需要特定地区 → 检查你的计划是否支持

2. 如果只是绕过bot detection → 可以用local模式 + 关闭JavaScript检测

# 检测代理配置
bb usage

# 查看当前IP信息
browse env remote --info

完整配置清单

以下是经过验证的完整配置流程：

# 1. 安装CLI
npm install -g @browserbasehq/browse-cli

# 2. 配置API KEY（从 https://browserbase.com/settings 获取）
export BROWSERBASE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

# 3. 验证认证
browse auth status

# 4. 选择模式（开发用local）
browse env local

# 5. 测试安装是否成功
browse open https://example.com
browse screenshot

适用人群

适合使用Browserbase的场景：

需要爬取有bot protection的网站（Cloudflare、reCAPTCHA等）
需要多地区IP测试
需要AI agent进行网页自动化操作

不适合的场景：

简单的一次性爬取（直接用curl/requests更划算）
低预算项目（免费计划限制多，付费计划$99/月起）
只需要截图功能（有很多免费工具）