zn-ai/docs/Desktop-Packaging-Workflow.md

桌面端打包流程

本文用于梳理 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. 按目标平台执行对应脚本

推荐命令：

pnpm install
pnpm typecheck
pnpm run package:win

或：

pnpm install
pnpm typecheck
pnpm run package:mac

2.2 日常出 Windows 包

pnpm run package:win

2.3 日常出 mac 包

如果希望一次出 x64 + arm64：

pnpm run package:mac

如果只想出单一架构：

pnpm run package:mac:x64

或：

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

等价于：

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

用途：

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

3.3 pnpm run package:mac

等价于：

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

用途：

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

3.4 pnpm run build

等价于：

pnpm run package
electron-builder

特点：

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

4. 打包时自动发生的事

4.1 prepackage

prepackage 会自动执行：

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 打包后会自动执行：

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 运行时二进制准备好，可以执行：

pnpm run prep:win-binaries

它会跑：

pnpm run uv:download:win
pnpm run node:download:win

适合场景：

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

5.2 手动更新预装 skills

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

pnpm run bundle:preinstalled-skills

5.3 手动更新 OpenClaw 运行时

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

pnpm run bundle:openclaw

6. 产物位置

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

release/

打包中间产物目录：

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

7. Windows / mac 实操建议

7.1 Windows

推荐最简流程：

pnpm install
pnpm typecheck
pnpm run package:win

说明：

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

7.2 macOS

推荐最简流程：

pnpm install
pnpm typecheck
pnpm run package:mac

如果只打单架构：

pnpm run package:mac:x64

或：

pnpm run package:mac:arm64

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

pnpm run package:mac:fast

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

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

pnpm run package:win

macOS

pnpm run package:mac

只做前置产物准备

pnpm run package

只想检查类型

pnpm typecheck