应用调试 (Debugging)

zero-native 提供了结构化追踪、持久化日志记录、Panic 异常捕获以及用于调试桌面应用的诊断工具。

追踪模式 (Trace modes)

运行时会输出结构化的追踪记录。您可以使用 TraceMode 来控制输出的详细程度：

模式	描述
off	关闭追踪输出
events	仅输出生命周期和平台事件（默认值）
runtime	输出运行时内部信息：帧渲染耗时、重绘更新区域（invalidation）、窗口状态等
all	输出所有详细的内部追踪信息

在构建时可以通过 -Dtrace=true 启用，或者在代码中从字符串解析：

const mode = zero_native.debug.parseTraceMode("all"); // 返回 ?TraceMode

追踪输出源 (Trace sinks)

追踪记录会路由输出到指定的接收器（Sink）中。zero-native 提供了以下三种 Sink 接收器：

• FileTraceSink —— 将追踪日志记录追加写入到磁盘上的文件中：

  var file_sink = zero_native.debug.FileTraceSink.init(io, log_dir, log_file, .json_lines);

• FanoutTraceSink —— 广播输出到多个子接收器（例如同时向标准输出和文件写入）：

  var sinks = [_]trace.Sink{ stdout_sink.sink(), file_sink.sink() };
  var fanout = zero_native.debug.FanoutTraceSink{ .sinks = &sinks };

• StdoutTraceSink（来自 zero-native 的 trace 模块）—— 将记录输出到标准输出（stdout），适用于交互式开发环境。

通过 RuntimeOptions.trace_sink 将配置好的 Sink 实例接入到运行时中：

var runtime = zero_native.Runtime.init(.{
    .platform = my_platform,
    .trace_sink = fanout.sink(),
});

日志格式 (Log format)

通过 ZERO_NATIVE_LOG_FORMAT 环境变量来控制持久化日志的格式：

环境变量取值	描述
jsonl	JSON 行格式 —— 每一行对应一个 trace 记录的 JSON 对象（默认值）
text	适合人类阅读的常规文本行

日志路径 (Log paths)

各个平台上默认的日志文件存储位置如下：

平台	默认存储路径
macOS	~/Library/Logs/<bundle-id>/zero-native.jsonl
Linux	~/.local/state/<bundle-id>/logs/zero-native.jsonl
Windows	%LOCALAPPDATA%\<bundle-id>\Logs\zero-native.jsonl

如果需要覆盖默认存储路径，可以使用 ZERO_NATIVE_LOG_DIR 环境变量：

ZERO_NATIVE_LOG_DIR=/tmp/my-logs zig build run-webview

Panic 异常捕获 (Panic capture)

zero-native 会在 Zig 默认的异常处理程序运行之前捕获 panic 崩溃：

1. 向日志目录下的 last-panic.txt 中写入一份崩溃诊断报告（包含 panic 信息和返回地址）；
2. 向日志文件中追加一条带有 fatal 级别的追踪日志记录；
3. 随后调用 std.debug.defaultPanic 以输出标准的 Zig panic 信息。

在您的应用中启用 Panic 捕获：

pub const panic = std.debug.FullPanic(zero_native.debug.capturePanic);

并在程序初始化启动期间调用 installPanicCapture：

zero_native.debug.installPanicCapture(io, log_setup.paths);

调试覆盖层 (Debug overlay)

在构建时传入 -Ddebug-overlay=true 可以在 WebView 中启用可视化的调试覆盖层（Debug Overlay）。它会直观地显示每一帧的渲染耗时、重绘更新区域（invalidation regions）以及窗口元数据：

zig build run-webview -Ddebug-overlay=true

关于完整的环境与诊断工具参考，请参阅命令行参考 (zero-native doctor)。

环境变量说明

环境变量名	描述
ZERO_NATIVE_LOG_DIR	覆盖默认的日志文件输出目录。
ZERO_NATIVE_LOG_FORMAT	指定日志格式：text 或 jsonl（默认值为 jsonl）。