You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 

5.7 KiB

打包、更新与平台支持

应用身份

pnpm rename my-desktop "My Desktop" com.example.desktop
pnpm install

app.config.json 的 name/productName/appId 供主进程与 electron-builder 共同读取。更新源留空时不启用更新,也不访问任何模板作者服务器。正式发布前设置自己的图标、版本、许可证、支持链接和签名配置。

构建

pnpm package 生成当前平台的未安装目录。pnpm dist 默认 Windows NSIS、macOS DMG、Linux AppImage。推荐各自在目标系统构建,尤其是含原生 SQLite 的产物;CI 已准备三平台验证流程。

原生依赖使用 electron-builder 安装与打包时检查。SQLite 13 提供 Node-API 预构建;pnpm 禁止其隐式 node-gyp,避免支持的桌面平台为了空构建而要求本机编译器。其他原生模块或预构建不覆盖的平台可能仍需编译工具。遇到原生模块问题执行 pnpm rebuild。包管理器默认使用官方 registry;中国网络可以按本机环境设置 Electron 下载镜像,仓库不强制全体用户使用区域镜像。

Windows 安装包默认未签名。macOS 分发需要 Developer ID 签名、notarization 与必要的 entitlements。应用模板不能替代证书或发布账号。使用平台 CI secret 配置 electron-builder 的 CSC_LINK、CSC_KEY_PASSWORD 等变量,不提交证书或密码。

本仓库 release workflow 分别读取 CSC_LINK_WINDOWS / CSC_KEY_PASSWORD_WINDOWS 和 CSC_LINK_MACOS / CSC_KEY_PASSWORD_MACOS,再映射到各平台的 CSC_LINK / CSC_KEY_PASSWORD,避免两种平台共用错误证书。macOS notarization 另需 APPLE_ID、APPLE_APP_SPECIFIC_PASSWORD 和 APPLE_TEAM_ID。

更新 feed

在 app.config.json 设置 updateUrl 为自己的 HTTPS 发布目录。electron-builder 会据此生成 publish 配置,运行时 UpdateService 使用相同地址。构建完成后发布安装包与对应的 latest*.yml/blockmap 文件。

模板使用 electron-updater 的平台 autoUpdater:Windows NSIS、macOS 的更新产物和 Linux AppImage 都需要正确配置发布格式。macOS 已默认生成 DMG 和更新所需的 ZIP。Linux 应从实际 AppImage 中测试更新;解压目录不能代表安装后的更新行为。

配置 feed 的安装版本默认在启动 10 秒后检查,并每 6 小时检查一次;app.config.json 的 updates 可关闭启动检查或修改间隔(15 分钟至 7 天)。检查只通知可用更新,autoDownload/autoInstallOnAppQuit/allowDowngrade/allowPrerelease 均为 false。下载可以取消;失败或取消后重新检查再重试。安装前使用主进程原生确认,确认后完成作用域清理,再由安装器退出并重启。更新日志只记录脱敏错误与状态转换,关闭 upstream 含路径/URL 的详细日志。

允许启动参数关闭整个更新能力,不会因此改变发布 feed。失败后周期检查继续工作,不自动下载或强制安装。一次下载取消不代表回滚已执行的系统安装;已安装版本不通过 allowDowngrade 降级。

从第一版建立升级链路

  1. 正式发布前重命名模板,之后保持 appId、应用 name、用户数据路径和签名身份稳定。更名需要单独的数据迁移,不是普通版本升级。
  2. 在 package.json 递增稳定版本,创建对应 vX.Y.Z 标签;所有平台产物使用同一份源码与版本。不要用相同版本替换不同安装包。
  3. 配置 updateUrl、diagnosticsUrl、平台图标、签名和 macOS notarization。pnpm release:check 会检查地址、身份、版本、标签及本机签名配置是否齐备;不测试远程可用性或证书实际有效性。
  4. 使用 pnpm release:build,或手动触发 .github/workflows/release.yml 指定已有版本标签。工作流构建并保留产物,不自动向 feed 或 GitHub Release 发布。启用 updateUrl 时 forceCodeSigning 开启,签名失败会阻止对应签名构建。
  5. 先上传安装产物及 blockmap/ZIP,再发布对应 latest*.yml。客户端检查前清单不能指向尚未上传完的文件;服务端避免缓存旧清单,产物 URL 保持不可变。
  6. 在实际安装的旧版本上验证检查、下载、取消、重启安装和下一次启动,检查设置、笔记、凭据与数据库保留;从至少前一个版本和受支持的最旧版本分别升级。SQLite 每次迁移必须保持事务、连续编号与拒绝降级。
  7. 验证断网、404、错误 hash、不可信签名、磁盘空间不足以及安装失败;观察统一诊断,再扩大发布范围。仓库的服务状态测试不能替代这些真实安装验收。

灰度和发布撤回

在 latest*.yml 中配置 stagingPercentage(例如 10),由 electron-updater 决定当前用户是否处于灰度范围;逐步调到 25、50、100,无须改变客户端接口。客户端没有忽略灰度的强制更新入口。electron-builder v26 灰度说明

出现故障时可以暂停扩大灰度,清单切回之前的安全版本可阻止尚未升级的用户继续取得故障版本;已升级的用户需要发布更高版本的修复,不能靠降低版本号修复。应用数据迁移不能随安装程序自动回滚,涉及不可逆数据变更时需要额外备份与恢复方案。

当前依赖是 electron-updater 6.8.9 / electron-builder 26,不宣称具备 v27 文档中的签名清单或跨平台原子回滚能力。HTTPS、hash 校验和平台签名各承担自己的边界,发布账号、证书和 feed 存储权限仍由发布者保护。

验证范围

本地运行记录见 docs/validation.md。仓库包含 Windows/macOS/Linux CI 定义,但 CI 文件存在不代表已经在远程平台运行。真实更新依赖自己的 feed 和签名产物;默认禁用状态可以本地验证。