# 桌面端打包流程

本文用于梳理 `zn-ai` 当前仓库的 Windows / macOS 打包流程，说明应该先执行哪个脚本、每个脚本会自动带哪些前置步骤，以及常见使用场景。

## 1. 先记结论

如果你只是想正常出包，不需要手动先跑 `bundle-openclaw`、`bundle:preinstalled-skills`、`uv:download:*`。

直接按目标平台执行：

- Windows 安装包：`pnpm run package:win`
- mac 双架构包：`pnpm run package:mac`
- mac Intel 单架构包：`pnpm run package:mac:x64`
- mac Apple Silicon 单架构包：`pnpm run package:mac:arm64`

也就是说：

- 要打 Windows 包，优先跑 `package:win`
- 要打 mac 包，优先跑 `package:mac` 或具体架构脚本
- `package` 只是“准备打包产物”，不是最终安装包命令
- `build` 是“当前宿主机默认 electron-builder 打包”，不如平台脚本直观，日常不建议优先用

## 2. 推荐执行顺序

### 2.1 第一次打包或切分支后

1. `pnpm install`
2. `pnpm typecheck`
3. 按目标平台执行对应脚本

推荐命令：

```powershell
pnpm install
pnpm typecheck
pnpm run package:win
```

或：

```powershell
pnpm install
pnpm typecheck
pnpm run package:mac
```

### 2.2 日常出 Windows 包

```powershell
pnpm run package:win
```

### 2.3 日常出 mac 包

如果希望一次出 x64 + arm64：

```powershell
pnpm run package:mac
```

如果只想出单一架构：

```powershell
pnpm run package:mac:x64
```

或：

```powershell
pnpm run package:mac:arm64
```

## 3. 各脚本职责

### 3.1 `pnpm run package`

这是“打包前准备阶段”，会自动执行：

1. `prepackage`
2. `vite build`
3. `node scripts/bundle-openclaw.mjs`
4. `zx scripts/bundle-preinstalled-skills.mjs`

所以它会完成：

- 检查并补齐平台所需的 bundled runtime binaries
- 生成 `dist` 和 `dist-electron`
- 生成 `build/openclaw`
- 生成 `build/preinstalled-skills`

但是它不会直接产出最终安装包。

### 3.2 `pnpm run package:win`

等价于：

```powershell
pnpm run package
electron-builder --win --publish never
```

用途：

- 产出 Windows NSIS 安装包
- 当前配置只打 `x64`

### 3.3 `pnpm run package:mac`

等价于：

```powershell
pnpm run package
electron-builder --mac --publish never
```

用途：

- 产出 macOS 包
- 当前配置目标包含 `dmg` 和 `zip`
- 当前配置默认覆盖 `x64` 和 `arm64`

### 3.4 `pnpm run build`

等价于：

```powershell
pnpm run package
electron-builder
```

特点：

- 使用 `electron-builder.yml` 默认目标
- 更适合“按宿主机默认配置整体打一遍”
- 不如 `package:win` / `package:mac` 明确

## 4. 打包时自动发生的事

### 4.1 `prepackage`

`prepackage` 会自动执行：

```powershell
node scripts/ensure-bundled-runtime-binaries.mjs
```

这一步会按当前平台检查 `resources/bin` 下的运行时文件是否齐全。

当前规则：

- Windows：检查 `uv.exe` 和 `node.exe`
- macOS：检查 `uv`
- Linux：检查 `uv`

如果缺失，会自动调用对应下载脚本：

- Windows：`uv:download:win`、`node:download:win`
- macOS：`uv:download:mac`
- Linux：`uv:download:linux`

因此正常情况下，你不需要手动先跑这些下载脚本。

### 4.2 `afterPack`

`electron-builder` 打包后会自动执行：

```powershell
scripts/after-pack.cjs
```

它会继续完成这些动作：

- 把 `resources/bin/<platform-arch>/...` 平铺复制到安装包里的 `resources/bin/`
- 把 `electron/scripts` 处理到包内
- 补拷 `playwright`、`playwright-core`、`chromium-bidi`、`bytenode`
- 补拷 `build/openclaw`
- 清理不必要的开发文件，缩小包体

所以如果你是正常走 `package:win` / `package:mac`，这些都已经自动串好了。

## 5. 什么时候手动跑单独脚本

### 5.1 手动预拉 Windows 运行时

如果你只是想提前把 Windows 运行时二进制准备好，可以执行：

```powershell
pnpm run prep:win-binaries
```

它会跑：

```powershell
pnpm run uv:download:win
pnpm run node:download:win
```

适合场景：

- 网络较慢，想在正式打包前先把依赖下载好
- 排查 `resources/bin/win32-*` 是否齐全

### 5.2 手动更新预装 skills

如果你只想刷新预装 skills，不是正式出包，可以执行：

```powershell
pnpm run bundle:preinstalled-skills
```

### 5.3 手动更新 OpenClaw 运行时

如果你只想刷新 `build/openclaw`，可以执行：

```powershell
pnpm run bundle:openclaw
```

## 6. 产物位置

最终安装包 / 压缩包输出目录：

```text
release/
```

打包中间产物目录：

```text
dist/
dist-electron/
build/openclaw/
build/preinstalled-skills/
```

## 7. Windows / mac 实操建议

### 7.1 Windows

推荐最简流程：

```powershell
pnpm install
pnpm typecheck
pnpm run package:win
```

说明：

- 当前 `electron-builder.yml` 的 Windows 目标是 `nsis`
- 当前只配置了 `x64`

### 7.2 macOS

推荐最简流程：

```powershell
pnpm install
pnpm typecheck
pnpm run package:mac
```

如果只打单架构：

```powershell
pnpm run package:mac:x64
```

或：

```powershell
pnpm run package:mac:arm64
```

如果只是本地快速验包，不追求最大压缩率：

```powershell
pnpm run package:mac:fast
```

如果想保留 `afterPack` 清理前的更多内容，便于本地排查：

```powershell
pnpm run package:mac:local
```

说明：

- `package:mac:local` 会设置 `SKIP_AFTERPACK_CLEANUP=1`
- 它不是跳过打包，而是跳过 `afterPack` 里的清理步骤

## 8. 常见误区

### 误区 1：先手动跑 `bundle-openclaw` 才能打包

不是必须。

因为 `package` 已经会自动执行：

- `node scripts/bundle-openclaw.mjs`
- `zx scripts/bundle-preinstalled-skills.mjs`

### 误区 2：先手动跑 `uv:download:win` 才能打 Windows 包

也不是必须。

因为 `prepackage` 会自动执行 `ensure-bundled-runtime-binaries.mjs`，缺失时会自动下载。

### 误区 3：`package` 就是最终出包命令

不是。

`package` 只做准备，不直接生成最终安装包；真正平台出包应使用：

- `package:win`
- `package:mac`
- `package:mac:x64`
- `package:mac:arm64`

## 9. 建议你平时直接记住的命令

### Windows

```powershell
pnpm run package:win
```

### macOS

```powershell
pnpm run package:mac
```

### 只做前置产物准备

```powershell
pnpm run package
```

### 只想检查类型

```powershell
pnpm typecheck
```