Web 引擎 (Web Engines)

zero-native 拥有一套统一的 App/Runtime API，并且支持可选择的 Web 引擎后端。默认引擎是各个平台系统自带的 WebView。在 macOS 上，应用还可以选择通过 CEF 捆绑 Chromium。

支持矩阵 (Support Matrix)

平台	系统 (system)	Chromium
macOS	WKWebView	CEF，随应用捆绑
Linux	WebKitGTK	暂未接入；构建会尽早报错，而不会默默回退使用 WebKitGTK
Windows	开发中	开发中

设计的兼容性目标是：在平台支持的每一个引擎上，都提供相同的 Zig 应用模型、相同的运行时服务、相同的内置桥接命令、相同的 window.zero 辅助函数结构以及相同的安全策略语义。

系统 WebView (System WebView)

.web_engine = "system",

系统模式不需要捆绑任何浏览器依赖。它直接使用操作系统内置的 Web 引擎，因此渲染表现和 Web 平台特性支持将取决于用户安装的操作系统版本。

Chromium (CEF)

只需在应用中设置一次引擎：

.web_engine = "chromium",
.cef = .{ .dir = "third_party/cef/<platform>", .auto_install = false },

然后运行：

zero-native cef install
zig build run

在 macOS 上，CEF 模式是一等公民。它使用与 WKWebView 完全相同的 zero-native 运行时 API，但通过捆绑 Chromium 来确保渲染的一致性并提供可预测的 Web 平台特性。

Chromium 可在 macOS、Linux 和 Windows 上通过 CEF 使用。Linux 仍可使用系统自带的 WebKitGTK，Windows 亦可使用其原生系统宿主 WebView。

环境配置

推荐的使用方式是通过命令行工具（CLI）进行管理：

zero-native cef install
zero-native doctor --manifest app.zon

zero-native cef install 会从 GitHub Releases 下载为当前平台预先准备好的 CEF 运行时，并对其进行校验，然后将其完整安装到 third_party/cef/macos、third_party/cef/linux 或 third_party/cef/windows 目录中。该预制运行时中已包含了 libcef_dll_wrapper，因此应用开发者不需要具备 CMake 或 Chromium 的构建知识。

默认安装会使用 zero-native 指定并经过测试的 CEF 版本。您可以在应用的 CI 流程或配置文档中通过 zero-native cef install --version <version> 锁定该版本。当您主动升级 Chromium 时，请重新运行安装，然后重新构建并打包应用。打包的 Chromium 应用必须捆绑与二进制文件链接时完全相同的 CEF 结构，版本不匹配通常会导致启动失败，或者报找不到框架/资源的错误。

您也可以选择在构建时通过单条命令完成本地配置：

zig build run

只需在 app.zon 中设置 .cef = .{ .dir = "third_party/cef/<platform>", .auto_install = true }，即可允许构建或打包流程自动安装预制的运行时。此外，您仍然可以通过 -Dcef-dir=/path/to/cef 参数或配置文件中的 .cef.dir 指定手动的 CEF 目录。高级用户也可以使用 zero-native cef install --source official --allow-build-tools 直接从官方 CEF 归档源安装。具体的目录布局详见 third_party/cef/README.md。

核心维护者在准备版本的首次运行时发布或在发布前测试新的 CEF 分支时，可以使用 tools/cef/build-from-source.sh 从源码构建 CEF。

构建覆盖选项 (Build Overrides)

参数	描述
-Dweb-engine=system	临时使用平台系统的 WebView，而不是清单（Manifest）中的默认设置。
-Dweb-engine=chromium	在支持的平台上临时使用 CEF。目前支持 macOS 构建。
-Dcef-dir=path	指定 CEF 分发目录的路径。
-Dcef-auto-install=true	当 Chromium 构建缺失 CEF 时，临时自动运行 zero-native cef install。

捆绑打包 (Bundling)

zig build cef-bundle -Dcef-dir=/path/to/cef

当通过 app.zon 或临时参数选定 Chromium 时，本地 Chromium 构建还会将 CEF 框架复制到 zig-out/bin/Frameworks 目录中。当清单配置或命令行覆盖解析为 Chromium 时，打包过程将自动包含该运行时。

对于 Beta 版分发，在提交公证（Notarization）之前，请验证打包好的 .app 在 Contents/Frameworks 下是否包含了 Chromium Embedded Framework.framework，并且代码签名同时覆盖了应用本身以及嵌入的该框架。

冒烟测试 (Smoke Tests)

zig build test-webview-cef-smoke -Dplatform=macos -Dweb-engine=chromium
zig build test-package-cef-layout -Dplatform=macos

Chromium 冒烟测试步骤需要本地 CEF 布局或启用 -Dcef-auto-install=true。它会通过自动化启动示例应用，验证 native.ping，并测试 JavaScript 中窗口的创建、列表、聚焦和关闭。包布局步骤会验证 Chromium macOS 包中是否包含了 CEF 所需的框架与资源。

如何选择引擎 (Choosing An Engine)

考量因素	系统 (System)	Chromium
包体积	极小，因为浏览器引擎由系统内置提供。	较大，因为需要捆绑打包 CEF 运行时。
渲染一致性	渲染表现因用户系统的 OS 版本而异。	极高，对于附带同一 CEF 版本的所有应用都是一致的。
启动时间	最快。	较慢，因为 CEF 需要初始化 Chromium。
最适合的场景	小型应用、低系统开销占用、极简依赖。	需要 Chromium 专属行为、复杂的前端技术栈或更精细的渲染控制的应用。

在 app.zon 中

.web_engine = "system",
// 或者在支持的平台上：
.web_engine = "chromium",
.cef = .{
  .dir = "third_party/cef/<platform>",
  .auto_install = true,
},