app.zon 配置参考 (app.zon Reference)

app.zon 清单文件用于声明应用的元数据、权限、桥接策略、安全规则和窗口布局。它在构建、打包和验证时会被 CLI 和工具链读取。

配置示例

.{
    .id = "dev.zero_native",
    .name = "zero-native",
    .display_name = "zero-native",
    .version = "0.1.0",
    .icons = .{ "assets/icon.icns", "assets/icon.ico" },
    .platforms = .{ "macos" },
    .permissions = .{ "window" },
    .capabilities = .{ "webview", "js_bridge" },
    .bridge = .{
        .commands = .{
            .{ .name = "native.ping", .origins = .{ "zero://app" } },
            .{ .name = "zero-native.window.create", .permissions = .{ "window" }, .origins = .{ "zero://app" } },
        },
    },
    .security = .{
        .navigation = .{
            .allowed_origins = .{ "zero://app", "http://127.0.0.1:5173" },
            .external_links = .{ .action = "deny" },
        },
    },
    .web_engine = "system",
    .cef = .{ .dir = "third_party/cef/macos", .auto_install = false },
    .windows = .{
        .{ .label = "main", .title = "zero-native", .width = 720, .height = 480, .restore_state = true },
    },
}

字段说明

字段名	描述
id	反向 DNS 格式的 Bundle 标识符（例如 com.example.myapp）。
name	简短的机器/系统级应用名称。
display_name	面向用户的应用展示名称（用于菜单栏、窗口标题的缺省回退等）。
version	语义化版本（Semver）字符串。
icons	打包时所使用的图标文件的路径列表。
platforms	目标编译及打包平台，可选值为 macos, linux, windows。
permissions	运行时权限声明（详见安全机制）。
capabilities	开启的应用功能特性声明（详见安全机制）。
bridge	桥接命令策略（详见桥接机制）。
security	导航与外部链接访问的安全规则（详见安全机制）。
web_engine	指定使用的 Web 引擎类型：system（系统默认）或 chromium（目前 macOS 构建已支持，详见Web 引擎）。
cef	针对 Chromium 应用的 CEF 运行时配置，包括安装目录 dir 和是否自动安装 auto_install。
windows	窗口属性定义（详见窗口管理）。
frontend	前端项目的构建与开发配置（详见前端项目）。

frontend.dev 属性

可选的 frontend.dev 配置块用来设置受托管的前端开发服务器，以便配合 zero-native dev 和 zig build dev 开发命令：

.frontend = .{
    .dist = "frontend/dist",
    .entry = "index.html",
    .spa_fallback = true,
    .dev = .{
        .url = "http://127.0.0.1:5173/",
        .command = .{ "npm", "--prefix", "frontend", "run", "dev" },
        .ready_path = "/",
        .timeout_ms = 30000,
    },
},

字段名	描述
url	开发期间 WebView 应当加载的前端开发服务器 URL。
command	启动前端开发服务器的命令（将以子进程的形式启动）。
ready_path	用于轮询检查开发服务器就绪状态的 HTTP 路径（默认值为 /）。
timeout_ms	等待开发服务器就绪的最大毫秒数，超时则判定为失败（默认值为 30000）。

配置验证

您可以使用以下命令检查和验证您的 app.zon 文件：

zero-native validate app.zon
zero-native doctor --manifest app.zon --strict