NATIVE.zh-CN.md 11 KB

原生 WebView 后端:实现、运行与接入

原生特性增量(2026-11-06),基于 cfbrowser-202611060942.zip。Windows/macOS 已有真实原生适配代码,处于 experimental 阶段;本次环境仅能交叉编译,尚未在这两个系统执行。不能用构建通过或 doctor 输出替代实机验收。

平台与能力

平台 worker 使用的引擎 前提
Windows amd64/arm64 WebView2 Environment/Controller、Win32/COM 安装匹配架构的 Evergreen WebView2 Runtime,已登录桌面会话
macOS amd64/arm64 系统 WKWebView、purego/objc macOS 11+,已登录 GUI 会话
Linux amd64/arm64 GTK3/WebKitGTK 4.1、purego GTK3/WebKitGTK 4.1 ABI 与图形显示;无桌面时需 Xvfb 等

三平台 worker 均以 CGO_ENABLED=0 构建,无需 C/Objective-C/Swift 编译器、Node 或 WebDriver 服务。系统浏览器运行库仍为原生依赖。此结论只针对独立库与 worker;不会改变 Wails 主程序原有构建要求。

操作 Native 状态
goto/back/forward/reload、新建/关闭页面 已实现
命名隔离世界、JSON 求值、DOM 快照、稳定元素引用 已实现
合成 click/fill/check/uncheck/select/scroll 已实现,inputKind 明确为 synthetic
文本、表格、轮询等待、context 取消 已实现
页面 cookie 共享、不同 session 隔离 已实现;目标平台集成测试须验证
开放 Shadow DOM 的快照、ref、读表、文本等待 三平台已实现;不访问 closed roots
可信 click/hover/fill/type/press Windows WebView2 已实现;macOS/Linux 暂不支持
视口 PNG 截图 三平台已实现;Windows/macOS 仍需目标机运行验收
有界整页截图 Windows 已实现;4096×4096、4 MiB 上限;macOS/Linux 暂不支持
下载、上传、AX、跨域 frame、持久 profile、接管 UI、代理 暂未实现
完全脱离图形会话、严格网络隔离 不支持;networkPolicy=degraded

默认隐藏原生顶层窗口;--headed 从启动时显示。隐藏窗口不表示操作系统提供 displayless WebView。Windows Native 通过 WebView2 原生 COM 通道使用 CDP 求值,不启动完整 Edge,不开放 remote debugging port,也不安装网页可调用的 Go bridge。

Windows 本机验证

在仓库根目录使用 PowerShell:

$env:CGO_ENABLED = "0"
go build -buildvcs=false -mod=vendor -o bin/cfbrowser.exe ./cmd/cfbrowser
go build -buildvcs=false -mod=vendor -o bin/cfbrowser-worker.exe ./cmd/cfbrowser-worker
.\bin\cfbrowser.exe --engine native --worker "$PWD\bin\cfbrowser-worker.exe" --diagnostics demo

无需传入 --browser msedge.exe。完整 Edge 路径可用只能证明 CDP 条件满足,不能证明 Evergreen WebView2 Runtime 可用。运行时缺失/不可创建时,configure 会返回 BROWSER_RUNTIME_UNAVAILABLE;如果 worker 在 configure 前退出,客户端也可能报告 BROWSER_WORKER_EXITED,诊断见 stderr。

成功输出包含 "status":"passed"、sessionId、pageId 与测试表格;Native 会返回托管视口截图的元数据。需要检查可见窗口时,在 demo 前加 --headed;demo 很短,窗口可能迅速关闭。

执行 ABI 测试、demo 与 Native 专属集成测试:

.\scripts\test-native.ps1

等价的集成测试开关:

$env:CFBROWSER_INTEGRATION = "1"
$env:CFBROWSER_TEST_ENGINE = "native"
$env:CFBROWSER_WORKER = "$PWD\bin\cfbrowser-worker.exe"
go test -buildvcs=false -mod=vendor ./integration -count=1 -v -timeout=180s

脚本任何一步失败会返回错误;不会静默回退到 CDP。默认不关闭浏览器沙箱。

macOS 本机验证

在已登录图形会话的 Terminal 中,从仓库根目录运行:

CGO_ENABLED=0 go build -buildvcs=false -mod=vendor -o bin/cfbrowser ./cmd/cfbrowser
CGO_ENABLED=0 go build -buildvcs=false -mod=vendor -o bin/cfbrowser-worker ./cmd/cfbrowser-worker
./bin/cfbrowser --engine native --worker "$PWD/bin/cfbrowser-worker" --diagnostics demo
sh scripts/test-native.sh

脚本额外执行实际 _Block_copy/_Block_release 与 Go callback ABI 测试。此测试无需网页;集成测试才实际创建 WKWebView。

分发到 ClusterFlow 时建议放入独立 bundle。下面的 Python 仅用于可选打包,不是运行时依赖:

python3 scripts/package-macos-worker.py bin/cfbrowser-worker bin/CFBrowserWorker.app
./bin/cfbrowser --engine native --worker "$PWD/bin/CFBrowserWorker.app/Contents/MacOS/cfbrowser-worker" --diagnostics demo

worker 必须直接以 Contents/MacOS/cfbrowser-worker 启动;不能使用 open,否则私有 stdin/stdout 管道不会接入。Info.plist 指定最低 11.0、LSUIElement,以及允许浏览器 Web 内容和本地 HTTP 的 ATS 配置。打包脚本拒绝覆盖已有目录;更新时使用新路径或由发行流程管理旧 bundle。

正式发行先签名内部可执行文件/bundle,再签主应用并公证。沿用 ClusterFlow 的 Developer ID/entitlements 策略,在真实安装包中验证 WebKit 子进程启动、网络与关闭;本次没有完成签名或公证验收。远程无 GUI 的 SSH/LaunchDaemon 环境不在当前支持范围。

原生桥接与生命周期

Windows/macOS 使用 internal/nativehost 的 UI dispatcher;协议线程不能直接调用原生 UI。UI 队列容量 32、worker 页面上限 16、viewport 每轴范围 1–4096、原生求值最多 32 个在途。SDK 自身还有更严格的 session/page 配额和调用序列锁。脚本和结果受 512 KiB 协议预算限制;任意 Evaluate 仅供可信宿主内部使用。

Windows 在初始化阶段固定线程,创建 STA COM apartment、隐藏 HWND 并驱动消息循环。仅复用锁定版本 go-webview2 v1.0.22 的 loader 和 COM lifetime bridge;本地适配器按公开 vtable ABI 进行调用。默认 Go loader 无需旁置 WebView2Loader.dll;不要额外使用可选的 native_webview2loader build tag。调用指针通过 uintptrescapes 保持有效;16 字节 RECT 在 amd64 以地址传参,在 arm64 使用两个整数寄存器。

每 session 在私有目录下创建 webview2-profile;页面共享 Environment、各自有 Controller。求值链是 Page.getFrameTree → Page.createIsolatedWorld → Runtime.evaluate,保留 cfbrowser-isolated 全局与 DOM ref。导航事件按 navigation ID 等待完成。关闭时取消导航回调、解除事件、关闭 Controller、释放 COM 引用和 HWND,并有界等待所属 browser PID 退出。

macOS 在 main.init 固定进程主线程,动态加载 Cocoa/WebKit。每 session 一个 nonpersistent WKWebsiteDataStore 和命名 WKContentWorld;no-op WKUserScript 保持世界生命周期。每页面持有 NSWindow/WKWebView/delegate。NSApplication 事件迭代与周期 autorelease pool 驱动异步回调;JS 结果先 JSON.stringify,再经 NSString UTF-8 拷贝成有界 Go JSON。

completion block 在 native heap 分配,只保存整数 token。Go 注册表保留回调,WebKit 自己 copy/release block;关闭页面移除登记,晚到回调安全忽略。block descriptor 和 signature 由 worker 持有至进程结束,防止原生异步任务晚于页面销毁时使用已释放元数据。每 worker 只创建固定数量的 trampoline,不为每次求值消耗一个 purego callback 槽位。

取消后已经 dispatch 的导航/JS 仍可能执行;不会声称回滚动作。取消创建页面的完成回调会关闭该页面;关闭页面会立即完成仍在等待的求值并回收配额,晚到原生回调不能二次完成。超时后需要先观察页面状态,再决定下一步;有副作用的动作不得直接重放。RPC EOF 退出 worker,宿主等待 2 秒后可终止该 worker;尚无 Windows Job Object、Unix 进程组强杀或 crash-recovery,也不保证宿主被强杀时绝无遗留 WebView 子进程。

ClusterFlow 接入

仅替换底层 driver,八个 Agent 工具、Owner 校验、文件授权和运行取消策略保持兼容:

manager, err := cfbrowser.New(cfbrowser.Config{
    Timeout: 30 * time.Second,
}, &native.Driver{WorkerPath: absoluteWorkerPath})

导入 native "clusterflow.dev/cfbrowser/driver/native"。worker 必须来自宿主信任的安装目录,不能由模型指定。每个 session 启动自己的 worker,不复用 ClusterFlow 前端 WebView,避免加载的第三方网页接触 Wails bridge。关闭 Run/工作区时调用既有 Manager 清理接口;无需迁移 Wails 或引入前端 UI。

宿主采用 vendor 模式时,在实际应用模块执行 go mod tidy/go mod vendor,同时随应用分发对应 worker。详见 INTEGRATION.zh-CN.md。

测试与验收

公共测试覆盖 dispatcher、配额、配置、取消、错误传递、JSON 限制、EOF 与 pump 失败;Windows 特有测试验证 COM callback/vtable、UTF-16 和结构布局;macOS 特有测试验证复制后的原生 block 回调与所有权。新增真实引擎测试验证隔离全局不可见、世界跨调用保留、DOM 对象身份、JS 异常、导航清空状态与原生 viewport。

已有集成测试继续验证动态表单/表格、过期 ref、取消、Owner 范围、同 session cookie 共享、跨 session 隔离、历史导航与关闭。Native 下载测试按能力跳过,不应将其当成下载通过。

GitHub Actions workflow 提供 Windows/macOS 原生运行入口,但本次未触发,也未获得远程结果。目标系统必须运行脚本,确认无崩溃、无错误的 FAIL、所有预期用例执行;再做应用签名包验证。具体本次结果与覆盖率口径见 VALIDATION.zh-CN.md。

参考公开 ABI:WebView2 线程模型、WebView2 CDP、Windows ARM64 ABI、WKWebView API、Apple Block ABI。

SDK/worker 版本一致性

协议 envelope 仍为 v1;新增 session.features,特性代数为 2。新版 SDK 在 configure 后检查代数,旧 worker 返回 BROWSER_WORKER_OUTDATED,必须同时重建 SDK 使用方与 worker。截图走随机私有文件标识,不扩大 512 KiB RPC 消息上限,宿主读取后删除中间文件。整页截图使用 CapturePage(..., true),Agent 使用 cf_browser_capture 的可选 fullPage: true;超限明确返回错误,不截断或滚动拼接。