快速入门 (Quick Start)

zero-native 是一个支持可选 Web 引擎的 Zig 桌面应用外壳（Shell）。对于轻量级应用，可以使用系统内置的 WebView（WKWebView、WebKitGTK）；在 macOS 上，则可以通过 CEF 捆绑 Chromium，以获得可预测的 Chromium 渲染效果。仅需不到一分钟，即可创建一个带 Web UI 的原生桌面应用。

Beta 阶段支持范围

当前 Beta 阶段的目标是 macOS 桌面应用。系统 WebView 构建支持 macOS 和 Linux，而 Chromium/CEF 构建与打包功能目前仅限 macOS，对 Windows 的支持以及 Linux 下的 Chromium 支持已列入路线图。

前提条件

Zig: 0.16.0 或更高版本
Node.js: 带有 npm，用于处理生成的前端项目
操作系统: macOS 11 或更高版本，或者 Linux（Windows 支持正在开发中）

创建项目

bash

zero-native init my_app --frontend next
cd my_app

前端框架选项：next、vite、react、svelte、vue。

这将搭建一个完整的 zero-native 项目结构：

文件/目录	用途
`build.zig`	包含平台、追踪 (trace)、调试覆盖层 (debug-overlay)、自动化、JS 桥接 (js-bridge) 和 Web 引擎选项的 Zig 构建图 (Build graph)
`build.zig.zon`	Zig 包清单文件，声明 zero-native 依赖项
`app.zon`	应用元数据：名称、图标、权限、桥接命令、安全策略、窗口定义
`src/main.zig`	包含 `app()` 和可选的 `bridge()` 方法的 App 结构体
`src/runner.zig`	平台适配：追踪接收器 (trace sinks)、文件日志、异常捕获 (panic capture)、状态存储、运行时初始化
`assets/icon.icns`	适用于 macOS 打包的应用图标
`frontend/`	使用 `--frontend` 参数选定的前端框架初始项目

运行应用

bash

zig build run

首次前端构建会自动安装依赖项。随后您的应用将打开一个渲染 HTML 的原生 WebView 窗口。

macOS Beta 工作流

在 macOS Beta 上验证应用时，请使用以下开发与打包流程：

bash

zero-native init my_app --frontend next
cd my_app
zig build run
zero-native cef install
zig build run
zero-native package --target macos --signing identity --identity "Developer ID Application: Your Name"
zero-native doctor --manifest app.zon --strict

在运行 Chromium 之前，请在 app.zon 中设置 .web_engine = "chromium" 和 .cef = .{ .dir = "third_party/cef/macos", .auto_install = false }。-Dweb-engine 和 --web-engine 参数仍可用于单次覆盖，但标准的应用工作流会直接读取清单配置。

对于前端框架，在开发期间请通过开发服务器（Dev Server）运行前端，然后在发布时打包构建好的静态资源。

Hello World

最简单的 zero-native 应用只需提供名称和内联 HTML 即可：

zig

const HelloApp = struct {
    fn app(self: *@This()) zero_native.App {
        return .{
            .context = self,
            .name = "hello",
            .source = zero_native.WebViewSource.html(
                \\<!doctype html>
                \\<html>
                \\<body style="font-family: system-ui; padding: 2rem;">
                \\  <h1>Hello from zero-native</h1>
                \\</body>
                \\</html>
            ),
        };
    }
};

后续步骤

Web 引擎 (Web Engines) — 在系统 WebView 与 Chromium (CEF) 之间做出选择
应用模型 (App Model) — 应用、源码及生命周期回调的工作原理
前端项目 (Frontend Projects) — 将 React、Vue 或 Svelte 与 zero-native 结合使用
桥接 (Bridge) — 从 JavaScript 调用原生 Zig 代码
安全 (Security) — 权限、策略与导航规则

快速入门 (Quick Start) ​

Beta 阶段支持范围 ​

前提条件 ​

创建项目 ​

运行应用 ​

macOS Beta 工作流 ​

Hello World ​

后续步骤 ​

快速入门 (Quick Start)

Beta 阶段支持范围

前提条件

创建项目

运行应用

macOS Beta 工作流

Hello World

后续步骤