---
title: "命令速查 — zenit Zig UI 文档"
description: "构建、示例、测试、代码生成与质量检查命令集中查阅。"
url: https://zenit.z.express/zh/docs/reference/commands
language: zh-CN
alternate_en: https://zenit.z.express/docs/reference/commands.md
alternate_es: https://zenit.z.express/es/docs/reference/commands.md
alternate_ja: https://zenit.z.express/ja/docs/reference/commands.md
alternate_ko: https://zenit.z.express/ko/docs/reference/commands.md
alternate_fr: https://zenit.z.express/fr/docs/reference/commands.md
alternate_de: https://zenit.z.express/de/docs/reference/commands.md
project: zenit v0.1.0-alpha (Zig 0.15.2, macOS)
source: https://github.com/version-next/zenit
---

# 命令速查

构建、示例、测试、代码生成与质量检查命令集中查阅。

## 应用项目

以下 step 来自模板 `templates/minimal-app/build.zig`。`app` step 只在 macOS 目标上注册。

```sh
zig build                      # build the executable
zig build run                  # build and run
zig build app                  # package a macOS .app bundle (zig-out/)
zig build -Dtest-mode=true     # enable the automation harness (forwarded to zenit)
```

## zenit 仓库示例

每个示例都有两个 step：`zig build <name>` 生成带 ad-hoc 签名的 `.app`，`zig build run-<name>` 直接运行可执行文件。

| Step | .app 名称 | 内容 |
| --- | --- | --- |
| `hello-button` | Hello Button | 最小窗口与按钮 |
| `counter-reactive` | Reactive Counter | Signal / Memo / Effect 演示 |
| `virtual-list-perf` | 100k Virtual List | 10 万行 VirtualList 压力测试 |
| `text-input` | Text Input Demo | Input / Textarea 与 text\_core 集成 |
| `multi-window` | Multi Window | 两个原生窗口，按窗口路由 |
| `storybook` | zenit Storybook | 全组件 showcase，也是 e2e 目标 |
| `devtools-probe` | DevTools Probe | DevTools 性能面板真实窗口验收 |
| `interop-probe` | zenit Interop Probe | 富剪贴板 / 拖出的系统级验证 |
| `console-probe` | Console Probe | Console + DevTools 真实窗口验证 |
| `design-probe` | Design Probe | 设计稿还原比对靶场 |

```sh
zig build run-hello-button
zig build run-counter-reactive
zig build run-storybook
```

## 测试

### 总入口

| 命令 | 作用 |
| --- | --- |
| `test` | 等同 test-headless |
| `test-headless` | 确定性测试，不需要真实 Metal 设备 |
| `test-all` | 确定性测试 + 需要真实设备的 Metal 测试 |
| `test-null-backend` | 用 Null GPU 后端编译并运行确定性测试，验证 RHI 抽象 |

### UI 与响应式

| 命令 | 作用 |
| --- | --- |
| `test-ui` | UI 系统测试；-Dtest-filter=<子串> 只跑名称匹配的测试 |
| `test-ui-core` | ui\_core 集成测试（src/ui/core/tests.zig） |
| `test-reactive` | 响应式系统测试 |
| `test-allocation-campaign` | 在事务性框架边界上逐点注入分配失败 |

### 渲染与 GPU

| 命令 | 作用 |
| --- | --- |
| `test-render` | render 模块测试 |
| `test-gpu` | GPU 抽象层测试 |
| `test-metal` | 需要真实 Metal 设备的测试 |
| `test-svg` | SVG 解析 / 栅格化测试 |
| `test-timing-ring` | 帧计时环测试 |

### 文本与国际化

| 命令 | 作用 |
| --- | --- |
| `test-text` | text 模块测试（字体目录 / 字重） |
| `test-text-core` | text\_core 模块测试 |
| `test-text-properties` | 可设种子的确定性文本坐标属性测试 |
| `test-i18n` | i18n 模块测试 |
| `test-bidi-conformance` | 完整 Unicode 17.0.0 UAX #9 一致性数据 |

### 平台、窗口与打包

| 命令 | 作用 |
| --- | --- |
| `test-window-lifecycle` | 确定性多窗口生命周期与路由测试 |
| `test-text-hook-owners` | 进程级文本测量钩子的归属栈（关一个窗口不拆掉其他窗口的钩子） |
| `test-selector-scale` | HiDPI 下 FontSelector 缩放同步 |
| `test-system-sdk` | System SDK 测试 |
| `test-system-sdk-backends` | 确定性原生后端测试 |
| `check-system-sdk-cross` | 为 Linux / Windows 编译 System SDK 测试（不运行） |
| `test-harness` | test\_harness（file-RPC）测试 |
| `test-package-consumer` | 以直接包与经 Zig 过滤的包两种方式构建并启动下游应用 |

## 生成与工具

| 命令 | 作用 |
| --- | --- |
| `bench` | 性能基线：zig build bench \[-- filter\] \[-- json=path\] |
| `gen-icons` | 重新生成 -Dicon-set 选中的图标模块（默认 lucide） |
| `gen-icons-lucide` | 重新生成公开 Lucide 图标模块 |
| `gen-icons-common` | 重新生成 provider 无关的 common 图标模块 |
| `gen-icons-untitled / gen-icons-all` | 内部图标集；仅内部 checkout 可用 |
| `gen-component-index` | AST 扫描 src/ui，重新生成 component\_index\_generated.zig |
| `capability-matrix` | 打印生成的 macOS 能力矩阵 |
| `text-corpus-dump` | 打印已提交的 T0 文本坐标语料 |

## 构建选项

| 选项 | 默认 | 作用 |
| --- | --- | --- |
| `-Dtest-mode=true` | `false` | 启用 e2e harness（file-RPC server） |
| `-De2e-port=<n>` | `19816` | E2E 端口，用于默认 RPC 目录名 |
| `-Dtest-filter=<s>` | — | 只运行名称包含该子串的 test-ui 测试 |
| `-Dicon-set=<name>` | `lucide` | 内置图标 provider：lucide 或 untitled（仅内部） |
| `-Dgpu-backend=<name>` | `metal` | GPU 后端：metal 或 null |

> NOTE
> 
> **依赖选项要显式转发。** Zig 的依赖构建选项彼此隔离。下游应用要在 `b.dependency("zenit", ...)` 里转发 `.@"test-mode"` 与 `.@"e2e-port"`，`zig build -Dtest-mode=true` 才会传到 zenit；模板已经这样做。

## 质量脚本

| 脚本 | 作用 |
| --- | --- |
| `./scripts/check_oss_boundary.sh` | 静态检查 src/ui 的 import，并编译 hello-button 确认没有可达的禁用模块 |
| `./scripts/check_style_literals.sh` | 示例代码中裸颜色 / 字号字面量只减不增（ui.arb 逃生舱放行） |
| `bash scripts/switch_icon_set.sh lucide` | 用指定图标集跑 test-headless 与 storybook 构建，不修改工作区 |

> TIP
> 
> **使用 ZIG 覆盖。** 仓库脚本默认使用 PATH 中的 `zig`。需要指定版本时设置 `ZIG=/absolute/path/to/zig`。

## Bundle 检查

示例 bundle 使用 ad-hoc 签名并清除 quarantine 属性。下面的命令验证签名，并列出残留的扩展属性。

```sh
zig build hello-button
codesign --verify --deep --strict "zig-out/Hello Button.app"
xattr -lr "zig-out/Hello Button.app"
```