345 lines
6.3 KiB
Markdown
345 lines
6.3 KiB
Markdown
# 桌面端打包流程
|
||
|
||
本文用于梳理 `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
|
||
```
|