【免费下载链接】PiDeck
PiDeck 是一个开源的桌面工作台，用于在本地项目目录中统一管理 PI | DSH Agent 会话，并支持导入 Codex、Claude 本地会话以便统一浏览和恢复。支持多项目工作区、会话历史、Git 集成、内置终端、模型配置和插件管理，基于 Electron 构建。
PiDeck是一个基于 Electron 的开源桌面工作台，用于统一管理本地项目中的 PI / DSH Agent 会话。这篇文章带你走通它的打包发布全流程：如何用 electron-builder 一条命令产出 Windows（NSIS / portable / zip）、macOS（dmg / zip）、Linux（AppImage / deb / tar.gz）三平台安装包，以及如何借助 preflight 门禁和 CI 流水线把发布风险降到极低。
一、打包前你需要知道的三件事
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 要求先跑 release-preflight.mjs（即npm run preflight）。它把机器可判定的门禁收口成四个并行泳道：
- typecheck——
tsc --noEmit全量类型检查； - unit-tests——
node --test全量单元测试； - format—— biome 格式检查；
- 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 全自动发布流水线
手动打包装的是"信任本地环境"，而正式发版走的是全自动化流水线，核心文件是 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 分支产出安装包供下载测试。
五、发布后：自动更新与镜像同步
安装包发出后，闭环由两件事完成：
- 客户端自动更新：
package.json中publish指向 GitHub Release，electron-updater 按平台读取对应的latest.yml/latest-mac.yml拉取增量更新（.blockmap支撑差分下载）； - 镜像同步：发布事件触发
sync-atomgit.yml，待资产清单稳定后把 Release（含安装包）增量同步到 AtomGit 镜像，国内用户可就近下载。
六、给新手的打包 Checklist
📋 按这个顺序走，可以覆盖 95% 的发布场景：
npm run preflight全绿（红灯先修再重试）；CHANGELOG.md/CHANGELOG.zh-CN.md写好本次版本条目，中英文条目数一致；package.json版本号已 bump，发版提交用chore: release vX.Y.Z；- 本地至少跑一次目标平台
npm run dist:win/dist:mac/dist:linux并人工 smoke 安装包； - 推送 tag
vX.Y.Z，让 CI 全自动构建并发布 Release； - 核对 Release 资产齐全（含
latest.yml、.blockmap），再等镜像同步完成。
⚠️ 常见坑：
dist:fast产物只用于日常验证，不要用它对外发布——它跳过了类型检查、最高档压缩和 afterPack 清理，正式发布前必须跑完整dist:*命令。
PiDeck 的整套发布链路可以概括为：本地脚本保证可复现，preflight 门禁保证一致性，CI 矩阵保证多平台覆盖。理解了这三层，你就能独立维护一个 Electron 应用的完整发布流程了。
【免费下载链接】PiDeck
PiDeck 是一个开源的桌面工作台，用于在本地项目目录中统一管理 PI | DSH Agent 会话，并支持导入 Codex、Claude 本地会话以便统一浏览和恢复。支持多项目工作区、会话历史、Git 集成、内置终端、模型配置和插件管理，基于 Electron 构建。
相关推荐
electron-builder 跨平台构建完全指南：macOS / Linux / Windows 多平台打包与 Docker 实战
electron builder 跨平台构建完全指南：macOS / Linux / Windows 多平台打包与 Docker 实战 导读 本篇指南以 ele
构建工具桌面应用开发工具LiveAutoRecord打包发布：Electron Builder多平台构建
LiveAutoRecord打包发布：Electron Builder多平台构建 前言：为什么需要专业的打包方案？ 你还在为Electron应用的多平台打包而烦
从零构建VacuumTube：npm安装到electron-builder多平台打包完整开发指南
从零构建VacuumTube：npm安装到electron builder多平台打包完整开发指南 本文带你从零开始构建 VacuumTube ——一个把 You
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
