browser-use

原文：🇺🇸 英文
已翻译

自动执行浏览器交互操作，可用于网页测试、表单填写、截图和数据提取。当用户需要导航网站、与网页交互、填写表单、截取屏幕或从网页提取信息时使用。

11.6k次下载
查看 GitHub 仓库
添加于

SKILL.md 内容

查看翻译对照 →

借助browser-use CLI实现浏览器自动化

browser-use
命令可提供快速、持久的浏览器自动化功能。它在多个命令之间维持浏览器会话，支持复杂的多步骤工作流。

安装

bash
# 无需安装即可运行（推荐用于一次性使用）
uvx "browser-use[cli]" open https://example.com

# 或永久安装
uv pip install "browser-use[cli]"

# 安装浏览器依赖（Chromium）
browser-use install

快速开始

bash
browser-use open https://example.com           # 导航至指定URL
browser-use state                              # 获取带索引的页面元素
browser-use click 5                            # 通过索引点击元素
browser-use type "Hello World"                 # 输入文本
browser-use screenshot                         # 截取屏幕
browser-use close                              # 关闭浏览器

核心工作流

  1. 导航：
    browser-use open <url>
    - 打开指定URL（如需则启动浏览器）
  2. 检查：
    browser-use state
    - 返回带索引的可点击元素
  3. 交互：使用
    browser-use state
    返回的索引进行交互（如
    browser-use click 5
    、
    browser-use input 3 "text"
    ）
  4. 验证：通过
    browser-use state
    或
    browser-use screenshot
    确认操作结果
  5. 重复操作：浏览器在多个命令之间保持开启状态

浏览器模式

bash
browser-use --browser chromium open <url>      # 默认模式：无头Chromium
browser-use --browser chromium --headed open <url>  # 可见Chromium窗口
browser-use --browser real open <url>          # 用户的Chrome浏览器（包含登录会话）
browser-use --browser remote open <url>        # 云端浏览器（需要API密钥）
  • chromium：快速、隔离，默认无头模式
  • real：使用你的Chrome浏览器，包含Cookie、扩展程序和已登录会话
  • remote：云端托管浏览器，支持代理（需要BROWSER_USE_API_KEY）

命令列表

导航命令

bash
browser-use open <url>                    # 导航至指定URL
browser-use back                          # 返回上一页
browser-use scroll down                   # 向下滚动
browser-use scroll up                     # 向上滚动

页面状态命令

bash
browser-use state                         # 获取URL、标题和可点击元素
browser-use screenshot                    # 截取屏幕（输出base64格式内容）
browser-use screenshot path.png           # 将截图保存至指定文件
browser-use screenshot --full path.png    # 截取整页屏幕

交互命令（使用
browser-use state
返回的索引）

bash
browser-use click <index>                 # 点击元素
browser-use type "text"                   # 向当前聚焦元素输入文本
browser-use input <index> "text"          # 点击元素后输入文本
browser-use keys "Enter"                  # 发送键盘按键
browser-use keys "Control+a"              # 发送组合按键
browser-use select <index> "option"       # 选择下拉菜单选项

标签页管理

bash
browser-use switch <tab>                  # 通过索引切换标签页
browser-use close-tab                     # 关闭当前标签页
browser-use close-tab <tab>               # 关闭指定标签页

JavaScript与数据处理

bash
browser-use eval "document.title"         # 执行JavaScript并返回结果
browser-use extract "all product prices"  # 使用大语言模型提取数据（需要API密钥）

Cookie管理

bash
browser-use cookies get                   # 获取所有Cookie
browser-use cookies get --url <url>       # 获取指定URL的Cookie
browser-use cookies set <name> <value>    # 设置Cookie
browser-use cookies set name val --domain .example.com --secure --http-only
browser-use cookies clear                 # 清除所有Cookie
browser-use cookies clear --url <url>     # 清除指定URL的Cookie
browser-use cookies export <file>         # 将所有Cookie导出至JSON文件
browser-use cookies export <file> --url <url>  # 导出指定URL的Cookie至JSON文件
browser-use cookies import <file>         # 从JSON文件导入Cookie

等待条件

bash
browser-use wait selector "h1"            # 等待元素可见
browser-use wait selector ".loading" --state hidden  # 等待元素消失
browser-use wait selector "#btn" --state attached    # 等待元素加载至DOM
browser-use wait text "Success"           # 等待文本出现
browser-use wait selector "h1" --timeout 5000  # 自定义超时时间（毫秒）

额外交互命令

bash
browser-use hover <index>                 # 悬停在元素上（触发CSS :hover效果）
browser-use dblclick <index>              # 双击元素
browser-use rightclick <index>            # 右键点击元素（打开上下文菜单）

信息获取

bash
browser-use get title                     # 获取页面标题
browser-use get html                      # 获取完整页面HTML
browser-use get html --selector "h1"      # 获取指定元素的HTML
browser-use get text <index>              # 获取元素的文本内容
browser-use get value <index>             # 获取输入框/文本域的值
browser-use get attributes <index>        # 获取元素的所有属性
browser-use get bbox <index>              # 获取元素的边界框（x, y, 宽度, 高度）

Python执行（持久会话）

bash
browser-use python "x = 42"               # 设置变量
browser-use python "print(x)"             # 访问变量（输出：42）
browser-use python "print(browser.url)"   # 访问browser对象
browser-use python --vars                 # 显示已定义变量
browser-use python --reset                # 清除Python命名空间
browser-use python --file script.py       # 执行Python文件
Python会话在多个命令之间维持状态。
browser
对象提供以下功能：
  • browser.url
    - 当前页面URL
  • browser.title
    - 页面标题
  • browser.goto(url)
    - 导航至指定URL
  • browser.click(index)
    - 点击元素
  • browser.type(text)
    - 输入文本
  • browser.screenshot(path)
    - 截取屏幕并保存至指定路径
  • browser.scroll()
    - 滚动页面
  • browser.html
    - 获取页面HTML

智能代理任务（需要API密钥）

bash
browser-use run "Fill the contact form with test data"    # 运行AI代理任务
browser-use run "Extract all product prices" --max-steps 50
智能代理任务使用大语言模型自主完成复杂的浏览器任务。需要BROWSER_USE_API_KEY或已配置的大语言模型API密钥（如OPENAI_API_KEY、ANTHROPIC_API_KEY等）。

会话管理

bash
browser-use sessions                      # 列出活跃会话
browser-use close                         # 关闭当前会话
browser-use close --all                   # 关闭所有会话

配置文件管理

bash
browser-use profile list-local            # 列出本地Chrome配置文件
在打开真实浏览器（
--browser real
）之前，务必询问用户是否要使用特定的Chrome配置文件或不使用配置文件。使用
profile list-local
查看可用配置文件：
bash
browser-use profile list-local
# 输出：Default: Person 1 (user@gmail.com)
#         Profile 1: Work (work@company.com)

# 使用特定配置文件（包含该配置文件的Cookie/登录信息）
browser-use --browser real --profile "Profile 1" open https://gmail.com

# 不使用配置文件（全新浏览器，无现有登录信息）
browser-use --browser real open https://gmail.com

# 无头模式（无可见窗口）- 适用于Cookie导出
browser-use --browser real --profile "Default" cookies export /tmp/cookies.json
每个Chrome配置文件都有独立的Cookie、历史记录和已登录会话。选择正确的配置文件决定了网站是否会自动登录。

云端配置文件

云端配置文件将浏览器状态（如Cookie）存储在Browser-Use云端，可跨会话持久保存。需要BROWSER_USE_API_KEY。
bash
browser-use profile list                      # 列出云端配置文件
browser-use profile get <id>                  # 获取配置文件详情
browser-use profile update <id> --name "New"  # 重命名配置文件
browser-use profile delete <id>               # 删除配置文件
结合
--browser remote --profile <id>
使用云端配置文件：
bash
browser-use --browser remote --profile abc-123 open https://example.com

Cookie同步至云端

⚠️ 重要提示：在将本地浏览器的Cookie同步至云端之前，代理必须：
  1. 询问用户要使用哪个本地Chrome配置文件（
    browser-use profile list-local
    ）
  2. 询问要同步哪些域名 - 请勿默认同步整个配置文件
  3. 确认后再执行
默认行为： 为每个域名同步创建新的云端配置文件。这确保了Cookie的关注点分离。用户可根据需要将Cookie添加至现有配置文件。
步骤1：列出可用配置文件和Cookie
bash
# 列出本地Chrome配置文件
browser-use profile list-local
# → Default: Person 1 (user@gmail.com)
# → Profile 1: Work (work@company.com)

# 查看配置文件中的Cookie
browser-use profile cookies "Default"
# → youtube.com: 23
# → google.com: 18
# → github.com: 2
步骤2：同步Cookie（三种控制级别）
1. 按域名同步（推荐默认方式）
bash
browser-use profile sync --from "Default" --domain youtube.com
# 创建新的云端配置文件："Chrome - Default (youtube.com)"
# 仅同步youtube.com的Cookie
这是推荐的方式 - 仅同步需要的Cookie。
2. 同步完整配置文件（谨慎使用）
bash
browser-use profile sync --from "Default"
# 同步配置文件中的所有Cookie
⚠️ 警告： 这会同步所有Cookie，包括敏感数据、跟踪Cookie和所有网站的会话令牌等。仅当用户明确需要完整浏览器状态时使用。
3. 细粒度控制（高级）
bash
# 将Cookie导出至文件
browser-use --browser real --profile "Default" cookies export /tmp/cookies.json

# 手动编辑JSON文件，仅保留特定Cookie

# 导入至云端配置文件
browser-use --browser remote --profile <id> cookies import /tmp/cookies.json
适用于需要单个Cookie级别控制的用户。
步骤3：使用已同步的配置文件
bash
browser-use --browser remote --profile <id> open https://youtube.com
向现有配置文件添加Cookie：
bash
# 将额外域名的Cookie同步至现有配置文件
browser-use --browser real --profile "Default" cookies export /tmp/cookies.json
browser-use --browser remote --profile <existing-id> cookies import /tmp/cookies.json
管理配置文件：
bash
browser-use profile update <id> --name "New Name"  # 重命名
browser-use profile delete <id>                    # 删除

服务器控制

bash
browser-use server status                 # 检查服务器是否运行
browser-use server stop                   # 停止服务器
browser-use server logs                   # 查看服务器日志

环境搭建

bash
browser-use install                       # 安装Chromium和系统依赖

全局选项

选项描述
--session NAME
使用命名会话（默认："default"）
--browser MODE
浏览器模式：chromium、real、remote
--headed
显示浏览器窗口（仅chromium模式）
--profile NAME
Chrome配置文件（仅real模式）
--json
以JSON格式输出
--api-key KEY
覆盖API密钥
会话行为： 所有未指定
--session
的命令都使用同一个"default"会话。浏览器保持开启状态，并在多个命令之间复用。使用
--session NAME
可并行运行多个浏览器。

API密钥配置

部分功能（
run
、
extract
、
--browser remote
）需要API密钥。CLI会按以下顺序检查密钥位置：
  1. --api-key
    命令行参数
  2. BROWSER_USE_API_KEY
    环境变量
  3. ~/.config/browser-use/config.json
    文件
如需永久配置：
bash
mkdir -p ~/.config/browser-use
echo '{"api_key": "your-key-here"}' > ~/.config/browser-use/config.json

示例

表单提交

bash
browser-use open https://example.com/contact
browser-use state
# 显示：[0] input "Name", [1] input "Email", [2] textarea "Message", [3] button "Submit"
browser-use input 0 "John Doe"
browser-use input 1 "john@example.com"
browser-use input 2 "Hello, this is a test message."
browser-use click 3
browser-use state  # 验证提交是否成功

多会话工作流

bash
browser-use --session work open https://work.example.com
browser-use --session personal open https://personal.example.com
browser-use --session work state    # 检查工作会话
browser-use --session personal state  # 检查个人会话
browser-use close --all             # 关闭两个会话

使用Python进行数据提取

bash
browser-use open https://example.com/products
browser-use python "
products = []
for i in range(20):
    browser.scroll('down')
browser.screenshot('products.png')
"
browser-use python "print(f'Captured {len(products)} products')"

使用真实浏览器（已登录会话）

bash
browser-use --browser real open https://gmail.com
# 使用你的真实Chrome浏览器，包含现有登录会话
browser-use state  # 已自动登录！

技巧

  1. 始终先运行
    browser-use state
    ，查看可用元素及其索引
  2. 使用
    --headed
    进行调试    ，查看浏览器的操作过程
  3. 会话会持久保存 - 浏览器在多个命令之间保持开启
  4. 使用
    --json
    以编程方式解析    输出内容
  5. Python变量在会话内的
    browser-use python
    命令之间持久保存
  6. 真实浏览器模式保留你的登录会话和扩展程序
  7. CLI别名：
    bu
    、
    browser
    和
    browseruse
    与
    browser-use
    功能完全相同

故障排除

浏览器无法启动？
bash
browser-use install                   # 安装/重新安装Chromium
browser-use server stop               # 停止所有卡住的服务器
browser-use --headed open <url>       # 尝试使用可见窗口模式
找不到元素？
bash
browser-use state                     # 检查当前元素
browser-use scroll down               # 元素可能在页面下方
browser-use state                     # 再次检查
会话出现问题？
bash
browser-use sessions                  # 检查活跃会话
browser-use close --all               # 清理所有会话
browser-use open <url>                # 重新开始

清理

完成浏览器自动化后请务必关闭浏览器，执行以下命令：
bash
browser-use close