应用打包 (Packaging)

zero-native 提供了打包工具，用于将您的应用打包为适用于 macOS、Linux 和 Windows 的可分发安装包。当配置了 .web_engine = "chromium" 且安装了匹配的 CEF 结构时，Chromium 打包还会自动包含特定平台的 CEF 运行时。

快速开始

两步即可完成构建与打包：

zig build package

或者直接使用 CLI 工具以获得更精细的控制：

zero-native package --target macos --manifest app.zon --binary zig-out/bin/MyApp

构建选项

构建系统暴露了控制平台、Web 引擎和构建特性的选项参数：

选项	可选值	默认值	描述
-Dplatform	auto, null, macos, linux	auto	目标编译平台
-Dweb-engine	system, chromium	app.zon	临时覆盖 WebView 引擎配置
-Dcef-dir	path	--	临时覆盖 CEF 运行时分发目录
-Dtrace	off, events, runtime, all	events	追踪信息输出等级
-Ddebug-overlay	true, false	false	启用 WebView 中的调试覆盖层（Debug overlay）
-Dautomation	true, false	false	启用自动化测试服务器
-Djs-bridge	true, false	false	启用 JavaScript 桥接功能

app.zon 中的打包字段

清单文件定义了打包的元数据：

.{
    .id = "com.example.myapp",
    .name = "myapp",
    .display_name = "My App",
    .version = "1.0.0",
    .icons = .{ "assets/icon.icns", "assets/icon.ico" },
    .platforms = .{ "macos", "linux" },
    .web_engine = "system",
    .cef = .{ .dir = "third_party/cef/macos", .auto_install = false },
}

字段名	用于
id	macOS 的 Bundle 标识符、Linux 的 .desktop 文件、日志保存路径
display_name	菜单栏展示的名称、窗口标题的备用缺省值
version	Info.plist 的版本、安装包的元数据
icons	根据平台规范复制到应用包内对应的图标文件
platforms	指定需要生成哪些平台的安装包

macOS

应用包（App Bundle）

zig build package 会创建一个包含以下内容的 .app 包：

• Contents/MacOS/<binary> — 编译生成的原生可执行二进制文件
• Contents/Resources/icon.icns — 应用图标文件
• Contents/Info.plist — 根据 app.zon 自动生成
• Contents/Resources/dist/ — 前端静态资源（若有配置）

macOS 应用包中声明的最低系统版本（LSMinimumSystemVersion）为 11.0。

有关代码签名、公证以及 .dmg 安装磁盘制作的详细内容，请参阅代码签名文档。

Linux

安装包结构

Linux 打包会创建一个标准的安装目录树结构：

• bin/<name> — 可执行程序
• share/applications/<name>.desktop — 桌面的桌面入口启动文件
• share/icons/hicolor/.../<name>.png — 各种标准尺寸的应用图标

使用命令行直接打包：

zero-native package --target linux --manifest app.zon --binary zig-out/bin/MyApp

Windows

zero-native package --target windows --manifest app.zon --binary zig-out/bin/MyApp.exe

Windows 下的打包功能目前处于早期开发阶段。打包器会将二进制可执行文件与前端静态资产复制到一个可分发的文件夹目录结构中。

前端静态资源

资源绑定 (Bundle Assets)

如果您的应用包含前端构建步骤，可以将其输出结果打包：

zig build bundle-assets

这会将配置好的 dist 目录复制到构建输出中。生产环境的安装包会通过内置的 zero://app/ 协议对它们提供服务，因此类似于 /assets/app.js 的绝对路径可以在不依赖于本地 file:// 协议的情况下正常工作。

在 app.zon 中进行配置：

.frontend = .{
    .dist = "dist",
    .entry = "index.html",
    .spa_fallback = true,
}

字段	描述
dist	编译构建后的前端输出目录路径
entry	dist 目录内的 HTML 入口文件
spa_fallback	对未知路由返回入口文件（单页应用 SPA 模式）

CEF 运行时捆绑 (CEF Bundling)

当使用 Chromium 引擎时，需要将 CEF 运行时连同应用一起捆绑：

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

这会将所需的 CEF 框架、链接库和相关资源文件复制到生成的应用包中。CEF 的版本包必须与目标平台以及芯片架构严格相匹配。

在安装、构建、打包以及 CI 验证环节请使用完全相同的 CEF 版本。标准的应用开发工作流一般如下：

1. zero-native cef install --version <pinned-version>
2. zig build
3. zero-native package --target macos

一般情况下，请在 app.zon 中设置 .web_engine = "chromium" 和 .cef = .{ .dir = "third_party/cef/macos", .auto_install = false } 以应用正常的 Chromium 打包流程。仅在需要单次临时覆盖配置时，才使用 -Dweb-engine, --web-engine, -Dcef-dir 或 --cef-dir 参数。

通过以下命令在本地验证 Chromium macOS 包的布局结构：

zig build test-package-cef-layout -Dplatform=macos

这一门槛检查（Gated Check）步骤需要本地有 CEF 目录或启用了 -Dcef-auto-install=true。它会验证打包好的应用是否完整包含了 CEF 的框架文件和资源文件。

应用图标生成 (Icon Generation)

从源 PNG 图片中生成各个平台特定的图标文件：

zig build generate-icon

这会从 assets/icon.png 中生成适用于 macOS 的 icon.icns 和适用于 Windows 的 icon.ico。

构建验证 (Validation)

在开始打包之前，先检查您的清单描述配置和开发环境是否已就绪：

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

doctor 命令会检查宿主环境、WebView 可用性、清单配置合法性、日志存储路径以及可选的 CEF 路径。加上 --strict 会让任何警告也直接导致校验失败。关于 zero-native doctor 具体检查哪些内容的细节，请参阅调试诊断文档。

平台打包快捷命令

除了使用通用命令 zero-native package --target <platform>，CLI 还可以使用以下快捷打包命令：

• zero-native package-windows [--output path] [--binary path]
• zero-native package-linux [--output path] [--binary path]
• zero-native package-ios [--output path] [--binary path]
• zero-native package-android [--output path] [--binary path]

目标平台支持度 (Platform Targets)

平台目标	支持状态
macos	完全支持：.app 包生成、代码签名、公证服务（Notarization）、.dmg 磁盘文件制作
linux	支持：.desktop 入口创建、图标安装、可执行文件打包
windows	早期支持：基于目录的程序打包
ios	实验性的
android	实验性的