vercel-labs/zero-native · 上手攻略

• 仓库：vercel-labs/zero-native（现更名为 vercel-labs/native）
• 链接：https://github.com/vercel-labs/native
• 分类：developer-tool
• 作者：Jay
• 更新：2026-08-13

是什么

Native SDK（项目原名 Zero-Native）是 Vercel Labs 出品的原生桌面应用开发工具链，用 Zig 做运行时引擎、TypeScript 或 Zig 写业务逻辑、.native 声明式标记写界面，编译后输出不含任何浏览器 runtime 的单个本地二进制。核心理念：开发者喜欢 Web 技术的表达力，但 Electron 的重量（Chromium 捆绑、GB 级内存）是真实代价；Native SDK 保留了声明式 UI 的开发体验，把 runtime 换成 Zig 渲染引擎，实现"无浏览器 Native 性能 + Web 开发体验"。

⚠️ 项目已于 2026 年 6 月正式开源，仓库从 vercel-labs/zero-native 更名为 vercel-labs/native，npm 包名为 @native-sdk/cli，主命令为 native。

解决什么问题

• Electron 的体积：Chromium 捆绑导致应用动不动 100MB+ 内存，Native SDK 编译后二进制仅数 MB。
• Flutter/GTK 绑手的 UI 表达：声明式 .native 标记比 Qt/WPF 更贴近 Web 开发者直觉。
• AI Agent 构建桌面应用：内置 automation server + accessibility snapshot + 确定性截图，AI Agent 可以直接操作界面并验证状态，降低 Agent 自动化桌面应用的门槛。

快速安装

# 前置：Node.js 22.15+（23.5+ on 23 line），Zig 0.16.0（CLI 会自动下载校验）
npm install -g @native-sdk/cli
native version

# 创建应用（TypeScript 模板）
native init my_app
cd my_app
native dev

一个原生窗口会立即打开，显示可用的计数器界面。macOS 上开发体验最深，Linux 通过软件渲染器（deterministic reference renderer）实现全功能，Windows 支持尚待验证（建议参考官方文档）。

核心用法

项目结构

my_app/
├── src/
│   ├── core.ts      # 逻辑：Model + Msg + update 函数，TypeScript 编译为 native
│   └── app.native   # UI 声明：元素、布局、绑定、消息分发
├── app.zon          # 应用清单：身份、窗口、权限、安全策略
├── assets/icon.png  # 图标源（打包时转换为各平台格式）
└── package.json / tsconfig.json  # 编辑器 IntelliSense 专用，无关构建

UI 编写（.native 文件）

<!-- src/app.native -->
<window title="计数器">
  <column gap="16" padding="24">
    <text size="20" weight="bold">当前计数：{count}</text>
    <row gap="8" main="center" cross="center">
      <button variant="secondary" on-press="decrement">−</button>
      <button variant="primary" on-press="increment">+</button>
    </row>
  </column>
</window>

业务逻辑（src/core.ts）

// Model 定义
interface Model {
  count: number;
}

// Msg 消息类型
type Msg =
  | { kind: 'increment' }
  | { kind: 'decrement' }
  | { kind: 'reset' };

// 唯一状态更新函数（Elm 风格）
export function update(model: Model, msg: Msg): Model {
  switch (msg.kind) {
    case 'increment': return { ...model, count: model.count + 1 };
    case 'decrement': return { ...model, count: model.count - 1 };
    case 'reset':     return { ...model, count: 0 };
  }
}

Zig 核心模板（可选）

native init my_app --template zig-core
# 业务逻辑在 src/main.zig，与 TypeScript 版完全等价

CLI 命令

AI Agent 集成

# 查看内置 agent 技能
native skills list

每个应用内置 automation server，Agent 可通过： - accessibility snapshots：读取界面可访问性树，了解当前状态 - widget 驱动：模拟按钮点击、输入框填充 - 断言：验证运行时的具体状态 - 确定性截图：frame-by-frame 重放 + 状态指纹校验

典型适用场景

• 轻量工具应用：计算器、笔记、剪贴板管理、系统监控，不需要 Web 能力但要好看。
• AI Agent 桌面自动化：让 Agent 操作真实原生界面并验证执行结果，适合自动化测试或 RPA 场景。
• 对性能敏感的桌面工具：需要低内存占用（MB 级而非 GB 级）且保持现代 UI 体验。
• 跨平台 CLI GUI 包装：用声明式 UI 给命令行工具加图形界面，代码量远少于 Qt/GTK。

坑与注意

1. macOS 是主开发平台：Linux 功能完整但依赖软件渲染器，Windows 支持状态建议查官方文档；发布前在所有目标平台测试。
2. Node.js 版本要求高：需要 22.15+（或 23.5+），旧版 Node 不兼容；Node 本身不进入最终二进制，但 build 时必须。
3. Zig 工具链版本锁定 0.16.0：native build 会检测 PATH 中的 Zig 版本，不兼容时自动下载 pinned 版本到 ~/.native/toolchains/，离线环境需预先配置。
4. 发布包体积（实测待验证）：README 称"scaffolded counter app builds to a single binary a few megabytes small"，但尚未实测验证，建议实际 ls -lh 确认。
5. 组件库成熟度：组件 catalog（button、tabs、text fields、dialogs、charts、virtual lists）已存在，但相比 Electron/Flutter 生态仍然小很多；复杂 UI 需自己实现组件。
6. app.zon 权限配置：文件操作、网络、系统 API 权限在清单文件声明，生产发布时需仔细审核权限范围。
7. 调试体验：无 Chrome DevTools；native check 提供类型错误定位（file:line:column），但运行时调试需要靠截图或日志。
8. SQLite 关系型特性需 Node：若在 Zig 核心中使用关系型 SQLite，构建时 Node 只参与 schema 检查和迁移生成，最终二进制不依赖 Node。

与同类对比

Native SDK 的差异化在于AI-native：内置 accessibility-driven automation + 确定性重放机制，让 AI Agent 真正能操作和验证桌面应用，而不是只能在命令行层面打转。

一句话推荐结论

如果你想用 TypeScript/Zig 写桌面应用但受不了 Electron 的体积，且需要 AI Agent 能直接操作和验证界面状态，Native SDK 是目前这个方向最认真的尝试；但 2026 年中才开源、生态还小，生产项目用之前建议先跑通 examples/ 里的完整案例确认能力边界。

原始 commit：https://github.com/vercel-labs/native（README + quick-start，fetch 日期 2026-08-13） - InfoQ 报道：2026-06-15 开源 - npm：@native-sdk/cli（版本号需 native version 确认） - Zig 版本：0.16.0（CLI 自动管理） - Node.js：22.15+（23.5+ on 23 line）