Skip to content

About

使用 Web 技术(HTML/CSS/JavaScript)构建跨平台桌面应用的轻量级 Python GUI 库,Python 与 JavaScript 双向桥接,无需打包浏览器引擎。 Build cross-platform desktop GUIs with web technologies (HTML/CSS/JS) in Python — lightweight, with a two-way Python↔JavaScript bridge and no bundled browser engine.

Topics

Resources

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

pywebview 浏览器自动化套件

(Browser Automation Toolkit)

基于 pywebview 社区定制版(6.2.1) 构建的桌面级浏览器自动化工具。 用系统原生网页内核(Windows: Edge WebView2 / macOS: WKWebView / Linux: GTK-WebKit 或 CEF) 开一个真窗口,然后像人一样导航、点击、填表、提取、截图。

不依赖 Selenium / Playwright,不需要额外下载浏览器内核。


目录


1. 它解决什么问题

普通爬虫(requests + HTML 解析)在现代站点上会连撞三面墙:

问题 普通爬虫 本项目
内容是 JS 渲染的 拿到空壳 HTML 等页面渲染完再从真实 DOM 取
需要登录 / 点击 / 滚动才出数据 无法交互 真窗口,可点击、滚动、填表
有反爬指纹检测 请求头就能识破 真实浏览器内核,指纹与真人一致

代价是它比 requests 慢得多(每个命令都要开一次窗口,冷启动约 10 秒), 所以定位是:小而精的自动化,而不是大规模并发采集。

上层 browser_cli 把常见动作封装成 26 个命令行命令 + 27 个动作方法 + 9 个提取方法, 并提供了一个 Flask 控制面板和 15 个 HTTP 端点。


2. 环境要求

项 要求
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+。


3. 安装

在仓库根目录执行:

# 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'

4. 五分钟上手

# 环境自检(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 后手动接管窗口。


5. 命令总览(26 个)

5.1 导航与提取

命令 说明 示例
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"

5.2 表单与交互

命令 说明
fill-form 一次填写多个字段,可选提交
fill-steps 分步执行(fill / click / wait / type / select / extract)
hover 鼠标悬停,触发 mouseenter / mouseover
scroll-to 滚动到指定元素
scroll-down 向下滚动指定像素
press 模拟键盘按键(Enter / Tab / Escape / ArrowDown…)
upload 触发文件选择框

5.3 搜索与登录

命令 说明
search 打开搜索页 → 输入关键词 → 提交 → 可选提取结果
login 自动填用户名密码并提交,可选提取登录后内容

5.4 截图与导出

命令 说明
screenshot 整页或指定元素截图(Windows 走原生抓取,渲染与屏幕一致)
pdf 调起打印对话框,手动另存为 PDF

5.5 录制与回放

命令 说明
record 交互式录制操作,存成 JSON 脚本
replay 回放脚本,支持 --speed 调速

5.6 等待与同步

命令 说明
wait-for-timeout 等待指定毫秒
wait-for-url 等待 URL 匹配 glob(如 **/success)

5.7 多窗口与批处理

命令 说明
multi-window 同时打开多个窗口并保持一段时间
batch 按 URL 列表批量处理,汇总输出
webui 启动 Web 控制面板(默认 8125)

5.8 环境与诊断

命令 说明
doctor 环境诊断(Python / pywebview / WebView2 / 网络 / 后端 / 功能统计)
browsers 列出系统已安装浏览器
set-cookies 为站点写入 Cookie
run 执行 YAML 剧本

6. extract 详解:把"能抓到"变成"抓得准"

默认行为是"导航完立刻 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 输出的结构是 [[表][行][单元格]],合并单元格会用空串补齐,保证每行列数一致。


7. eval:自定义 JS 与页面内 fetch

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.json

JS 很长时写进文件,用 --file 加载:

browser-cli eval --file my_extract.js --url "https://..." -o out.json

--await:页面内发请求

不少站点的数据在接口里,页面 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 的拒绝也会被原样抛出, 不会退化成超时。


8. 截图

Windows 上优先走 Win32 PrintWindow + PW_RENDERFULLCONTENT 抓窗口客户区, 再按 innerWidth 归一化到 CSS 像素,因此:

  • 渲染结果与屏幕一致(字体、图片、深色主题都对)
  • 会自动裁掉标题栏
  • --selector 元素截图会先把元素滚进视口再裁剪

非 Windows 或抓取失败时退回 html2canvas(从 CDN 注入,首次会慢 0.5~1s)。 html2canvas 的渲染保真度较差(实测在 WebView2 上会丢文字),只作为兜底。

BROWSER_CLI_HEADLESS=1(隐藏窗口)时原生抓取拿不到画面,截图会退回 html2canvas,文字可能缺失。要可靠截图请用可见窗口。


9. Web 控制面板

# 默认端口 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 停止窗口

10. 环境变量

变量 默认 说明
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 随机 固定面板令牌

11. 能力边界(含真实站点实测)

状态说明:✅ 可用 | ⚠️ 有条件可用 | ❌ 不可用

场景 状态 说明
静态 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 不下发数据) ❌ 如淘宝搜索
验证码 / 风控 ❌ 不在解决范围

实测记录(2026-11,Windows + WebView2)

目标 结果 备注
微博热搜榜 TOP20 ✅ 20 条 排名 / 关键词 / 热度 / 链接,广告位与置顶位已过滤
腾讯新闻科技频道 ✅ 20 条 首屏 11 条,滚动后补齐;推广位 href 为空需过滤
COMEX 黄金日 K(东财) ✅ 30 根 页面 DOM 被合规提示挡住,改走页面内 fetch 公开行情接口
淘宝搜索 RTX5060 ❌ 商品列表服务端不下发,只剩骨架屏;登录框在跨域 iframe 内无法关闭

可直接复跑的脚本在 browser_cli/testcases/accept/。


12. 排障

详细踩坑记录见 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

13. 回归自检

自带本地测试页(动态内容 / 合并单元格 / Shadow DOM / 模拟 CSP),不依赖外网:

python -m browser_cli.testcases.check_fixes

覆盖 13 条用例:等待策略、二维表格、Shadow DOM、iframe、eval --await、 CSP 诊断、--min-count 退出码等。每条都会真实开窗,整套约 3 分钟。


14. 目录结构

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/               # 内核用法示例

15. 许可与来源

  • 内核基于 pywebview(BSD),版本 6.2.1 社区定制版
  • 上层 browser_cli 为自研组件
  • 本项目整体遵循 BSD License,见 LICENSE

About

使用 Web 技术(HTML/CSS/JavaScript)构建跨平台桌面应用的轻量级 Python GUI 库,Python 与 JavaScript 双向桥接,无需打包浏览器引擎。 Build cross-platform desktop GUIs with web technologies (HTML/CSS/JS) in Python — lightweight, with a two-way Python↔JavaScript bridge and no bundled browser engine.

Topics

Resources

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages