PiDeck 打包发布全流程:electron-builder 构建 Windows、macOS、Linux 三平台安装包完整指南

原创2026-10-15 23:37:001,969 阅读

PiDeck 打包发布全流程:electron-builder 构建 Windows、macOS、Linux 三平台安装包完整指南

PiDeck 是一个基于 Electron 的开源桌面工作台,用于统一管理本地项目中的 PI / DSH Agent 会话。这篇文章带你走通它的打包发布全流程:如何用 electron-builder 一条命令产出 Windows(NSIS / portable / zip)、macOS(dmg / zip)、Linux(AppImage / deb / tar.gz)三平台安装包,以及如何借助 preflight 门禁和 CI 流水线把发布风险降到极低。

一、打包前你需要知道的三件事

PiDeck 桌面工作台全景,展示多项目会话管理与文件树布局

PiDeck 的技术栈是 Electron + React + TypeScript,打包链路分为两层:

层级 工具 职责
代码构建 electron-vite 把 src/ 编译成 out/ 下的 main / preload / renderer 产物
安装包构建 electron-builder 把 out/ + 依赖 + 图标打成各平台原生安装包

所有打包配置集中在 package.json 的 build 字段中,包括:

  • asar: true + compression: maximum —— 代码打进 asar 归档并做最高档压缩,减小安装体积;
  • asarUnpack —— 把 node-pty、sharp、koffi 等原生模块保留在 asar 外,保证 .node 二进制可被正确加载;
  • extraResources —— 附带内置扩展、提示词库、技能库、宠物资源、DSH runtime 等数据文件;
  • afterPack 钩子指向 after-pack-cleanup.js —— 打包后自动删除 Electron 52 个多余语言包(只留中/繁中/英文,节省约 42MB)并清理非运行时文件。

💡 新手提示:想本地跑通一遍,先装好依赖(npm install),再执行 npm run build 完成代码构建,之后所有 dist:* 脚本都会自动先触发它。

二、三平台打包命令速查

PiDeck 为每个平台封装了专用脚本,用法非常一致:

npm run dist:win              # Windows:nsis + portable + zip 三格式
npm run dist:win -- nsis      # 只打 NSIS 安装器
npm run dist:mac              # macOS:dmg + zip
npm run dist:linux            # Linux:AppImage + deb + tar.gz
npm run dist:linux:arm64      # Linux ARM64 变体
npm run pack                  # 快速验证:只产 unpacked 目录,不出安装包
npm run dist:fast             # 日常迭代:跳过类型检查 + 低压缩 + 单格式

各平台产物格式如下:

平台 产物 说明
Windows *.exe(NSIS 安装器 / portable 便携版)、*.zip 安装器支持自选目录、桌面/开始菜单快捷方式
macOS *.dmg、*.zip 按 ${arch} 区分 x64 / arm64 产物命名
Linux *.AppImage、*.deb、*.tar.gz deb 包名 pideck,并声明了对旧包 pi-desktop 的替代关系

所有产物统一输出到 release/ 目录,文件名由 artifactName 模板生成(如 PiDeck-0.9.0-setup.exe),版本号自动取自 package.json。

2.1 Windows 打包:自动校验更新资产

dist-win.js 在打完包后会做一次额外的"自动更新资产"体检:Windows 端依赖 electron-updater 的 NSIS provider,latest.yml、setup.exe 和对应 .blockmap 三者必须同时上传到同一个 Release,缺任何一个都会导致客户端无法安全差分更新。脚本会直接告诉你缺了什么,避免发布后用户升级失败。

2.2 Linux 原生模块的 glibc 基线

内置终端依赖 node-pty 原生模块。CI 中在 Debian 10 容器里重建它,确保产物只依赖 glibc 2.28——否则在统信 UOS 20、麒麟 V10 等国产系统上会因 openpty 符号绑定新 GLIBC 而无法加载。打包后可用 linux-native-baseline.js 对包内 app.asar.unpacked 做 ELF 符号扫描验证。

三、发版前门禁:一条命令跑完所有检查

PiDeck 内置 pi 环境检测向导,四步引导安装、确认路径、验证权限并安装完成

正式发版前,PiDeck 要求先跑 release-preflight.mjs(即 npm run preflight)。它把机器可判定的门禁收口成四个并行泳道:

  1. typecheck —— tsc --noEmit 全量类型检查;
  2. unit-tests —— node --test 全量单元测试;
  3. format —— biome 格式检查;
  4. release —— 发布一致性:版本号 / CHANGELOG / README 三处一致、模型目录与扩展清单等 --check 生成器同步、DSH wire payload 形状、Electron 二进制体检等 10 余项。

设计亮点是"不首错即停":所有泳道跑完才汇总,一次看到全部问题,完整 JSON 报告落盘 release-preflight/。常用变体:

npm run preflight                        # 默认四泳道
npm run preflight -- --e2e               # 追加 Playwright E2E(较慢)
npm run preflight -- --skip unit-tests   # 日常快速通道

完整发版清单见 release-process.md:CHANGELOG 中英条目要同步、版本号写入 package.json / package-lock.json、安装包至少做一遍人工 smoke——发版前不能只依赖 CI 构建成功。

四、CI 全自动发布流水线

PiDeck 内置终端与 Git 面板,展示终端命令执行和 Git 分支管理界面

手动打包装的是"信任本地环境",而正式发版走的是全自动化流水线,核心文件是 release.yml。触发方式有两种:

  • 推送 tag:git push 一个 v* 形式的 tag 即全自动触发;
  • 手动 workflow_dispatch:可选 tag(带 auto 哨兵值 = 按 package.json 版本号发)、并可选发布通道。

流水线结构一览:

push tag v* 
  ├─ resolve-version        解析版本 / tag / 通道(stable 或 dev)
  ├─ extract-changelog      从 CHANGELOG.zh-CN.md 抽取该版本正文作 Release 说明
  ├─ build-release (矩阵并行)
  │    ├─ windows-latest    → nsis + portable + zip
  │    ├─ macos-latest ×2   → dmg + zip(x64 与 arm64 分 job)
  │    └─ ubuntu ×2         → AppImage + deb + tar.gz(x64 与 arm64 原生 runner)
  └─ pack-dsh-runtime       单 runner 交叉打包 6 平台的 DSH runtime tgz

几个值得注意的工程细节:

  • 单发布方不变量:所有构建 job 都带 --publish never,发布统一由末尾的 softprops 步骤用 PAT 完成,避免多 job 抢发同一个 Release;
  • dev 双品牌通道:channel=dev 走 dist-dev.js,产出独立的 "PiDeck Dev" 包(独立 appId、独立 pideck-dev:// 协议),以 prerelease 形式发布,不抢占 /releases/latest,与 stable 通道互不影响;
  • 跨平台 runtime:DSH runtime 的 6 个平台 tgz 由单个 ubuntu runner 交叉打包完成,补齐了 win32-arm64 / darwin-x64 等平台缺口(见 dsh-runtime-cross-pack.md);
  • Linux 双门禁:构建前在 glibc 2.28 基线重建原生模块,构建后再解包 deb 验证 ELF 符号,防止 runner 升级后静默回退。

日常快速验证则可用 build-windows.yml 等手动构建 workflow,从最新 main 分支产出安装包供下载测试。

五、发布后:自动更新与镜像同步

PiDeck 设置页用量统计面板,展示 Token 用量、成本与会话热力图

安装包发出后,闭环由两件事完成:

  1. 客户端自动更新:package.json 中 publish 指向 GitHub Release,electron-updater 按平台读取对应的 latest.yml / latest-mac.yml 拉取增量更新(.blockmap 支撑差分下载);
  2. 镜像同步:发布事件触发 sync-atomgit.yml,待资产清单稳定后把 Release(含安装包)增量同步到 AtomGit 镜像,国内用户可就近下载。

六、给新手的打包 Checklist

📋 按这个顺序走,可以覆盖 95% 的发布场景:

  1. npm run preflight 全绿(红灯先修再重试);
  2. CHANGELOG.md / CHANGELOG.zh-CN.md 写好本次版本条目,中英文条目数一致;
  3. package.json 版本号已 bump,发版提交用 chore: release vX.Y.Z;
  4. 本地至少跑一次目标平台 npm run dist:win / dist:mac / dist:linux 并人工 smoke 安装包;
  5. 推送 tag vX.Y.Z,让 CI 全自动构建并发布 Release;
  6. 核对 Release 资产齐全(含 latest.yml、.blockmap),再等镜像同步完成。

⚠️ 常见坑:dist:fast 产物只用于日常验证,不要用它对外发布——它跳过了类型检查、最高档压缩和 afterPack 清理,正式发布前必须跑完整 dist:* 命令。

PiDeck 的整套发布链路可以概括为:本地脚本保证可复现,preflight 门禁保证一致性,CI 矩阵保证多平台覆盖。理解了这三层,你就能独立维护一个 Electron 应用的完整发布流程了。

登录后查看全文
PiDeck