(Browser Automation Toolkit)
基于 pywebview 社区定制版(6.2.1) 构建的桌面级浏览器自动化工具。 用系统原生网页内核(Windows: Edge WebView2 / macOS: WKWebView / Linux: GTK-WebKit 或 CEF) 开一个真窗口,然后像人一样导航、点击、填表、提取、截图。
不依赖 Selenium / Playwright,不需要额外下载浏览器内核。
- 1. 它解决什么问题
- 2. 环境要求
- 3. 安装
- 4. 五分钟上手
- 5. 命令总览(26 个)
- 6. extract 详解:把"能抓到"变成"抓得准"
- 7. eval:自定义 JS 与页面内 fetch
- 8. 截图
- 9. Web 控制面板
- 10. 环境变量
- 11. 能力边界(含真实站点实测)
- 12. 排障
- 13. 回归自检
- 14. 目录结构
- 15. 许可与来源
普通爬虫(requests + HTML 解析)在现代站点上会连撞三面墙:
| 问题 | 普通爬虫 | 本项目 |
|---|---|---|
| 内容是 JS 渲染的 | 拿到空壳 HTML | 等页面渲染完再从真实 DOM 取 |
| 需要登录 / 点击 / 滚动才出数据 | 无法交互 | 真窗口,可点击、滚动、填表 |
| 有反爬指纹检测 | 请求头就能识破 | 真实浏览器内核,指纹与真人一致 |
代价是它比 requests 慢得多(每个命令都要开一次窗口,冷启动约 10 秒),
所以定位是:小而精的自动化,而不是大规模并发采集。
上层 browser_cli 把常见动作封装成 26 个命令行命令 + 27 个动作方法 + 9 个提取方法,
并提供了一个 Flask 控制面板和 15 个 HTTP 端点。
| 项 | 要求 |
|---|---|
| Python | >= 3.9(推荐 3.10+;3.9 下 Pillow 会被自动约束到 11.x) |
| Windows | Edge WebView2 Runtime(Win10/11 通常已自带) |
| macOS | 系统自带 WKWebView,无需额外安装 |
| Linux | GTK3 + WebKit2,或 CEF(pip install -e ".[cef]") |
3.9 仅解除了元数据限制,本仓库的自动化测试在 Python 3.13 上完成,3.9 未做完整回归。 生产建议直接用 3.10+。
在仓库根目录执行:
# 1) 安装上层工具包(会同时拉齐 click / pyyaml / pillow / beautifulsoup4 / flask)
pip install -e ./browser_cli
# 2) 装好后 browser-cli 可在任意目录使用
browser-cli --version
browser-cli doctor如果只想跑定制版内核本身(不装 CLI):
pip install -e .| 现象 | 原因 | 处理 |
|---|---|---|
browser-cli 报 No module named 'browser_cli' |
旧版 packages.find 扫不到自身目录(包目录就是项目根),editable 安装的导入映射为空 |
已在 browser_cli/pyproject.toml 改为显式 packages + package-dir,重装即可 |
版本号变成 0.1.dev1 |
浅克隆 / zip 包没有 git tag,setuptools_scm 推不出 6.2.1 |
已在 pyproject.toml 加 fallback_version = "6.2.1" |
pip install -e . 报不支持 editable |
pip 过旧(< 24,不支持 PEP 660) | pip install -U "pip>=24" setuptools wheel |
Failed building wheel for pillow |
3.9 下 Pillow 12 无预编译 wheel | 依赖已按 Python 版本分流,3.9 自动锁 pillow<12 |
| 仓库 200MB+,clone 很慢 | vendor/cefpython3/ 是 Windows CEF 二进制(约 150MB),macOS/Linux 用不到 |
用稀疏检出,只取源码(见下) |
稀疏检出(省流量):
git clone --depth 1 --filter=blob:none --sparse https://github.com/liuda1999/pywebview-master.git
cd pywebview-master
git sparse-checkout set --no-cone '/*' '!vendor/' '!examples/assets/*.mp4' '!examples/assets/*.webm'# 环境自检(Python / pywebview / WebView2 / 网络 / 后端)
browser-cli doctor
# 开一个网页(窗口会真实弹出)
browser-cli goto "https://www.bilibili.com"
# 提取标题
browser-cli extract "title" --url "https://example.com"
# 抓动态列表:等够 10 条再取,避免"只渲染了一半"
browser-cli extract ".quote .text" --url "https://quotes.toscrape.com/js/" \
--wait-selector ".quote" --wait-count 10 --format json
# 二维表格(自动展开 colspan/rowspan)
browser-cli extract "table" --table --format json --url "https://example.com"
# 自定义 JS 取结构化数据(嵌套记录 / Shadow DOM / 同源 iframe)
browser-cli eval "[...document.querySelectorAll('.quote')].map(q => ({
text: q.querySelector('.text').innerText,
tags: [...q.querySelectorAll('.tag')].map(t => t.innerText)
}))" --url "https://quotes.toscrape.com/js/"
# 启动 Web 控制面板(默认 8125 端口)
browser-cli webui命令执行完窗口会自动关闭。想让它停住观察,用
multi-window --stay-open或goto后手动接管窗口。
| 命令 | 说明 | 示例 |
|---|---|---|
goto |
导航到 URL | goto "https://example.com" |
extract |
CSS 选择器提取(支持二维表格 / Shadow DOM / 内容就绪等待) | extract "h1" --url "..." --format json |
eval |
执行自定义 JS 输出 JSON(--await 支持页面内 fetch) |
eval "[...document.querySelectorAll('a')].length" --url "..." |
snapshot |
页面概况快照(标题 / URL / 正文预览 / 链接表单图片计数) | snapshot --url "https://example.com" |
| 命令 | 说明 |
|---|---|
fill-form |
一次填写多个字段,可选提交 |
fill-steps |
分步执行(fill / click / wait / type / select / extract) |
hover |
鼠标悬停,触发 mouseenter / mouseover |
scroll-to |
滚动到指定元素 |
scroll-down |
向下滚动指定像素 |
press |
模拟键盘按键(Enter / Tab / Escape / ArrowDown…) |
upload |
触发文件选择框 |
| 命令 | 说明 |
|---|---|
search |
打开搜索页 → 输入关键词 → 提交 → 可选提取结果 |
login |
自动填用户名密码并提交,可选提取登录后内容 |
| 命令 | 说明 |
|---|---|
screenshot |
整页或指定元素截图(Windows 走原生抓取,渲染与屏幕一致) |
pdf |
调起打印对话框,手动另存为 PDF |
| 命令 | 说明 |
|---|---|
record |
交互式录制操作,存成 JSON 脚本 |
replay |
回放脚本,支持 --speed 调速 |
| 命令 | 说明 |
|---|---|
wait-for-timeout |
等待指定毫秒 |
wait-for-url |
等待 URL 匹配 glob(如 **/success) |
| 命令 | 说明 |
|---|---|
multi-window |
同时打开多个窗口并保持一段时间 |
batch |
按 URL 列表批量处理,汇总输出 |
webui |
启动 Web 控制面板(默认 8125) |
| 命令 | 说明 |
|---|---|
doctor |
环境诊断(Python / pywebview / WebView2 / 网络 / 后端 / 功能统计) |
browsers |
列出系统已安装浏览器 |
set-cookies |
为站点写入 Cookie |
run |
执行 YAML 剧本 |
默认行为是"导航完立刻 querySelectorAll",这在动态站点上会静默返回残缺数据——
页面不报错,但只拿到 4 条而你以为是 10 条。下面这些选项就是为解决它而加的。
| 选项 | 作用 | 适用场景 |
|---|---|---|
--wait-selector SEL |
等元素出现 | 内容由 JS 注入 |
--wait-count N |
等至少 N 个元素 | 列表 / 瀑布流只渲染了一半 |
--wait-text |
等文本或表单值非空 | 元素已出现、内容还没写入 |
--wait-js EXPR |
等任意 JS 条件为真 | 值被异步覆盖(--wait-text 表达不了) |
--table |
按二维表格提取,展开 colspan/rowspan |
HTML 表格 |
--deep / --no-deep |
是否穿透 Shadow DOM(默认开) | Web Components |
--min-count N |
少于 N 条则退出码 1 | 流水线里想让残缺结果触发失败 |
--attribute |
text / html / value |
取表单值要用 value |
--format |
json / csv / txt |
不指定 --wait-selector 时,--wait-count / --wait-text 会自动以被提取的选择器为等待目标。
结果异常会告警:匹配到 0 个元素,或匹配到了但内容全为空,都会在 stderr 打 [警告],
不会被当成成功。
# 等某个值被异步改写后再取(硬等 --wait-dynamic 是下策)
browser-cli extract "#price" --attribute value --url "..." \
--wait-js "document.querySelector('#price').value !== '加载中'"
# 表格转 CSV
browser-cli extract "table.data" --table --format csv -o out.csv --url "..."
# 让残缺结果直接失败
browser-cli extract ".item" --wait-selector ".item" --min-count 20 --url "..."--table 输出的结构是 [[表][行][单元格]],合并单元格会用空串补齐,保证每行列数一致。
extract 只能做扁平化提取。一旦遇到"一条记录多个字段"或表格结构,
用 eval 一次返回对象数组更省事:
browser-cli eval "[...document.querySelectorAll('.quote')].map(q => ({
text: q.querySelector('.text').innerText,
author: q.querySelector('.author').innerText,
tags: [...q.querySelectorAll('.tag')].map(t => t.innerText)
}))" --url "https://quotes.toscrape.com/js/" -o quotes.jsonJS 很长时写进文件,用 --file 加载:
browser-cli eval --file my_extract.js --url "https://..." -o out.json不少站点的数据在接口里,页面 DOM 只被登录墙挡着。在页面上下文里发 fetch
既能复用站点的会话/Cookie,又能绕过 CORS 限制:
// kline.js
(async () => {
const r = await fetch('https://push2his.eastmoney.com/api/qt/stock/kline/get?...');
const j = await r.json();
return j.data.klines.map(s => s.split(','));
})()browser-cli eval --await --file kline.js --url "https://quote.eastmoney.com/..." -o k.json必须加 --await。不加的话 fetch 返回的 Promise 不会被求值,你拿到的是 {}。
--await 的实现是"JS 写全局变量 + Python 轮询",所以 Promise 的拒绝也会被原样抛出,
不会退化成超时。
Windows 上优先走 Win32 PrintWindow + PW_RENDERFULLCONTENT 抓窗口客户区,
再按 innerWidth 归一化到 CSS 像素,因此:
- 渲染结果与屏幕一致(字体、图片、深色主题都对)
- 会自动裁掉标题栏
--selector元素截图会先把元素滚进视口再裁剪
非 Windows 或抓取失败时退回 html2canvas(从 CDN 注入,首次会慢 0.5~1s)。
html2canvas 的渲染保真度较差(实测在 WebView2 上会丢文字),只作为兜底。
BROWSER_CLI_HEADLESS=1(隐藏窗口)时原生抓取拿不到画面,截图会退回html2canvas,文字可能缺失。要可靠截图请用可见窗口。
# 默认端口 8125,5 个窗口
browser-cli webui
# 自定义
browser-cli webui --port 8125 --max-windows 3 --no-open启动日志会打印带令牌的地址,形如 http://127.0.0.1:8125/?token=<随机串>。
固定令牌供脚本调用:
BROWSER_CLI_WEBUI_TOKEN=my-token browser-cli webui --no-open
curl -H "X-Browser-CLI-Token: my-token" http://127.0.0.1:8125/api/windows鉴权读的是
X-Browser-CLI-Token请求头或?token=查询参数, 不是Authorization: Bearer(用 Bearer 会 403)。 面板同时校验 Host,只接受127.0.0.1/localhost/::1,防 DNS rebinding。
端点(15 个):
| 端点 | 方法 | 功能 |
|---|---|---|
/ |
GET | 控制面板页面 |
/api/windows |
GET | 窗口列表 |
/api/windows/switch |
POST | 切换激活窗口 |
/api/goto |
POST | 导航 |
/api/status |
GET | 当前窗口状态 |
/api/extract |
POST | 提取 |
/api/exec_js |
POST | 执行 JS |
/api/screenshot |
POST | 截图 |
/api/fill |
POST | 填写字段 |
/api/click |
POST | 点击 |
/api/links |
POST | 提取链接 |
/api/login |
POST | 自动登录 |
/api/search |
POST | 搜索并提取 |
/api/fill-steps |
POST | 分步自动化 |
/api/stop |
POST | 停止窗口 |
| 变量 | 默认 | 说明 |
|---|---|---|
BROWSER_CLI_TIMEOUT |
30 | 默认操作超时(秒) |
BROWSER_CLI_WIDTH |
1024 | 窗口宽 |
BROWSER_CLI_HEIGHT |
768 | 窗口高 |
BROWSER_CLI_HEADLESS |
0 | 设为 1 隐藏窗口(截图会降级) |
BROWSER_CLI_GUI |
auto | 指定后端(edgechromium / cef) |
BROWSER_CLI_IGNORE_SSL |
1 | 设为 0 恢复证书校验 |
BROWSER_CLI_WEBUI_TOKEN |
随机 | 固定面板令牌 |
状态说明:✅ 可用 |
| 场景 | 状态 | 说明 |
|---|---|---|
| 静态 HTML 抓取 | ✅ | extract |
| JS 渲染内容 | ✅ | 配合 --wait-* |
| 列表懒加载 / 无限滚动 | 需循环 scroll-down + 等待;列表本身要重新取 |
|
| 点击后才出现的内容 | fill-steps 或 YAML 剧本 |
|
| HTML 表格二维结构 | ✅ | extract --table(含合并单元格) |
| 多字段嵌套记录 | ✅ | eval 返回对象数组 |
| Shadow DOM | ✅ | --deep(默认开启) |
| 同源 iframe | eval 里走 contentDocument |
|
| 跨域 iframe | ❌ | 同源策略限制,JS 无法访问 |
| 页面 CSP 禁止 eval | ❌ | macOS/WKWebView 会整体失效(见 TROUBLESHOOTING 1.5);Windows/WebView2 不受影响 |
| 页面 DOM 被登录墙屏蔽,但接口公开 | ✅ | eval --await 直接打接口 |
| 服务端登录墙(无 Cookie 不下发数据) | ❌ | 如淘宝搜索 |
| 验证码 / 风控 | ❌ | 不在解决范围 |
| 目标 | 结果 | 备注 |
|---|---|---|
| 微博热搜榜 TOP20 | ✅ 20 条 | 排名 / 关键词 / 热度 / 链接,广告位与置顶位已过滤 |
| 腾讯新闻科技频道 | ✅ 20 条 | 首屏 11 条,滚动后补齐;推广位 href 为空需过滤 |
| COMEX 黄金日 K(东财) | ✅ 30 根 | 页面 DOM 被合规提示挡住,改走页面内 fetch 公开行情接口 |
| 淘宝搜索 RTX5060 | ❌ | 商品列表服务端不下发,只剩骨架屏;登录框在跨域 iframe 内无法关闭 |
可直接复跑的脚本在 browser_cli/testcases/accept/。
详细踩坑记录见 browser_cli/TROUBLESHOOTING.md:
| 症状 | 先看这里 |
|---|---|
| 窗口弹不出来 / 看不到 | TROUBLESHOOTING 1.1(SW_HIDE 环境,用 scripts/run_visible.py) |
fill 返回成功但值被清空 |
TROUBLESHOOTING 1.2(SPA 异步覆盖,内置重填) |
| 报"等待选择器超时"但元素明明存在 | TROUBLESHOOTING 1.5(CSP 拦截 eval) |
| 多窗口卡死 / 列表一直"加载中" | TROUBLESHOOTING 1.4(patches.py 补偿) |
| 抓到的条数偏少 | 加 --wait-count / --wait-js / --min-count |
自带本地测试页(动态内容 / 合并单元格 / Shadow DOM / 模拟 CSP),不依赖外网:
python -m browser_cli.testcases.check_fixes覆盖 13 条用例:等待策略、二维表格、Shadow DOM、iframe、eval --await、
CSP 诊断、--min-count 退出码等。每条都会真实开窗,整套约 3 分钟。
pywebview-master/
├── webview/ # pywebview 定制版内核(platforms/ 下分 winforms / cocoa / gtk / qt / cef)
├── interop/ # JS ↔ Python 桥
├── vendor/cefpython3/ # Windows CEF 二进制(macOS/Linux 可稀疏检出跳过)
├── browser_cli/ # 上层自动化工具包
│ ├── cli.py # 26 个 CLI 命令
│ ├── controller.py # BrowserController / MultiWindowManager / WindowPool
│ ├── actions.py # 27 个动作方法(含 fill 防覆盖、deep 查询、表格解析)
│ ├── parser.py # 9 个提取 / 过滤 / 落盘方法
│ ├── webui.py # Flask 控制面板(15 个端点)
│ ├── patches.py # 多窗口 NavigationCompleted 补偿
│ ├── testcases/
│ │ ├── fixtures/ # 本地测试页
│ │ ├── accept/ # 真实站点取数示例
│ │ └── check_fixes.py # 回归自检
│ └── TROUBLESHOOTING.md
├── scripts/run_visible.py # 强制窗口可见启动器
├── tests/ # pywebview 内核集成测试
└── examples/ # 内核用法示例
- 内核基于 pywebview(BSD),版本 6.2.1 社区定制版
- 上层
browser_cli为自研组件 - 本项目整体遵循 BSD License,见
LICENSE