本文说明 Electron 应用的打包、签名与发布流程。安全基线与更新链路的信任要求见 Electron 安全加固,构建产物与体积治理见 前端工程化,静态资源缓存与分发见 Nginx 缓存机制与实践 与 CDN 原理与接入排障,制品仓库与制品治理的通用要求见 构建与制品仓库,版本与发布流程的组织见 变更与发布管理,产物校验与签名在安全体系中的位置见 密码学与安全架构。
一、起源
1.1 与网页部署的四处差别
| 差别 | 说明 | 带来的工作量 |
|---|---|---|
| 分发形态 | 需要安装包或压缩包,而不是上传静态文件 | 需要打包与安装器配置 |
| 平台矩阵 | 需要覆盖多个操作系统与处理器架构 | 构建与测试矩阵成倍增加 |
| 系统信任 | 未签名的应用会被系统提示或拦截 | 需要证书、签名与公证流程 |
| 更新机制 | 用户不会主动重新下载安装 | 需要内置更新与更新服务 |
1.2 需要回答的问题
- 要发布哪些平台与架构,是否需要通用包。
- 采用哪种分发形态,是否需要管理员权限安装。
- 更新如何下发、如何回滚、如何控制放量范围。
- 签名凭据由谁保管、如何进入流水线而不泄露。
1.3 取舍
| 选择 | 获得 | 付出 |
|---|---|---|
| 覆盖全平台与全架构 | 用户覆盖面广 | 构建与验证成本高,产物数量多 |
| 只发布单一平台与架构 | 成本最低 | 部分用户无法使用,后续补齐成本更高 |
| 内置自动更新 | 用户始终使用新版本 | 需要更新服务与签名一致性,更新失败需兜底 |
二、原理
2.1 两段式流程
第一阶段:构建界面产物(前端构建工具)-> 静态资源
第二阶段:打包应用(打包工具)-> 安装包与更新产物
两个阶段的职责不能混:前端构建工具负责资源组织与优化,打包工具负责归档、平台适配、签名与生成安装包。混淆会导致"打包配置里写构建逻辑"这类难以维护的做法。
打包时需要三份产物:主进程代码、预加载脚本、界面静态资源。三者的模块格式要求不同,预加载脚本在沙箱模式下必须使用传统模块格式,这一点是工程配置中最容易出错的地方,具体见 工程实践与排查。
2.2 分发形态
| 形态 | 特点 | 适用 |
|---|---|---|
| 安装器 | 有安装过程,可创建快捷方式与注册协议与文件关联 | 面向普通用户,需要完整集成系统 |
| 免安装压缩包 | 解压即用,无需管理员权限 | 内部分发与便携场景,无法注册协议与关联 |
| 系统包格式 | 由系统包管理器安装与升级 | 面向特定发行版用户 |
| 应用商店 | 由商店审核与分发并处理更新 | 面向普通消费者,需满足商店规范 |
安装器的两种模式需要明确选择:面向当前用户的安装不需要管理员权限,适合企业内部与个人用户;面向整机的安装需要管理员权限,适合统一部署,但会让安装与卸载更重。
2.3 平台与架构矩阵
| 维度 | 说明 |
|---|---|
| 操作系统 | 三类平台产物互不通用,必须在对应平台上构建或使用交叉构建方案 |
| 处理器架构 | 新架构需要单独产物;通用包把两套二进制合并,体积显著增大 |
| 运行时版本 | 运行时版本需要固定,升级时需回归验证原生模块与行为 |
| 构建环境 | 不同平台的签名与公证工具只在对应平台可用,因此流水线需要多平台执行机 |
结论:矩阵的确定要在项目早期完成,因为签名凭据、构建执行机与测试用例都依赖它。
2.4 归档格式
把应用代码打包为单一归档文件的目的是减少文件数量、加快加载并避免被零散篡改。但归档带来两类必须处理的限制:
| 限制 | 原因 | 处理方式 |
|---|---|---|
| 原生模块不可用 | 动态库需要以真实文件存在才能被加载 | 将其从归档中解包到独立目录 |
| 外部程序不可用 | 需要以文件路径调用的可执行文件无法从归档内运行 | 同样需要解包 |
| 资源路径变化 | 打包后代码位置与开发时不同 | 统一通过路径接口获取资源位置,不写死相对层级 |
归档不是安全存储:它可以被解包查看,因此不能放入密钥(与 Electron 安全加固 中的结论一致)。
2.5 体积治理
| 手段 | 效果 |
|---|---|
| 只打包运行期依赖 | 剔除开发期依赖与构建产物中间文件 |
| 使用文件白名单 | 只包含必需目录,避免把源码与测试一并打入 |
| 剔除语言包 | 运行时自带的界面语言资源可按需保留,能显著减小体积 |
| 压缩归档 | 减小安装包体积,代价是启动时解压耗时 |
| 剔除无用资源 | 图片与字体与示例文件按实际使用裁剪 |
体积治理的收益不仅是下载更快,还包括安装与启动更快、被杀毒软件扫描的时间更短。
2.6 签名与公证
| 平台 | 步骤 | 要点 |
|---|---|---|
| Windows | 使用代码签名证书对可执行文件与安装包签名并加时间戳 | 凭据可为文件形式或硬件令牌与云端签名,后者更适合流水线 |
| macOS | 开发者证书签名加启用强化运行时加提交公证加附加公证结果 | 需要声明必要权限,公证不通过需查看日志定位原因 |
| Linux | 无统一强制要求 | 发布校验值与签名文件供用户核对 |
两点工程要求:
- 签名凭据必须通过流水线的密钥管理注入,禁止写入构建配置与版本库。
- 时间戳的意义是让签名在证书到期后仍然有效,缺少时间戳会导致历史版本在证书过期后无法通过校验。
2.7 自动更新机制
| 组成 | 说明 |
|---|---|
| 更新元数据 | 描述最新版本号与产物地址与摘要,客户端据此判断是否需要更新 |
| 更新产物 | 安装包或用于差分的产物与差分索引 |
| 客户端逻辑 | 检查、下载、校验、安装、重启 |
| 关注点 | 说明 |
|---|---|
| 增量更新 | 通过差分索引只下载变化部分,显著减少下载量 |
| 检查时机 | 启动后延迟检查加周期检查加手动检查,避免启动时抢占带宽 |
| 强制更新 | 存在安全问题或接口不兼容时强制,需要给出明确提示与阻断界面 |
| 失败处理 | 下载失败可重试,安装失败应保留旧版本可启动,并提供手动下载入口 |
| 平台差异 | 某类平台的更新依赖已签名且以特定格式打包,另一类平台由自身格式支持更新 |
| 版本单调 | 更新只允许升级到更高版本,因此回滚需要发布一个版本号更高的旧代码包 |
回滚的实现方式是"用更高的版本号重新发布旧代码",而不是让客户端降级;这一点常被忽略,导致线上问题出现时无法快速回退。
2.8 版本与通道
| 项 | 要求 |
|---|---|
| 版本号 | 与安装包元数据与更新元数据与应用内展示保持一致,便于排查 |
| 通道分离 | 稳定与测试使用不同更新地址,避免测试版本下发给正式用户 |
| 灰度 | 按比例或按用户群放量,并能随时暂停 |
| 产物留档 | 每个版本的产物与校验值与签名一并留档,支持回滚与追溯 |
2.9 分发
| 方式 | 要点 |
|---|---|
| 对象存储加内容分发 | 适合面向公网分发,注意缓存策略与版本化路径 |
| 自建下载页 | 提供校验值与发布说明与历史版本 |
| 企业内部下发 | 结合软件分发系统静默安装,注意安装模式与权限 |
| 更新服务 | 与产物分离部署,保证元数据可即时更新而不受缓存影响 |
更新元数据文件不应被长期缓存,否则发布后客户端长时间看不到新版本;产物本身可以长期缓存,因为文件名带版本号。
三、实现
3.1 打包配置
// electron-builder 配置(package.json 片段)
{
"name": "desktop-app",
"version": "1.4.0",
"main": "dist/main/main.js",
"scripts": {
"build:renderer": "vite build",
"build:main": "esbuild src/main/index.js --bundle --platform=node --external:electron --outfile=dist/main/main.js",
"build:preload": "esbuild src/preload/index.js --bundle --platform=node --external:electron --format=cjs --outfile=dist/main/preload.js",
"build": "npm run build:renderer && npm run build:main && npm run build:preload",
"dist": "npm run build && electron-builder --publish never"
},
"build": {
"appId": "com.example.desktop",
"productName": "示例应用",
"directories": { "output": "release", "buildResources": "build" },
"files": [
"dist/**/*",
"package.json",
"!**/*.map",
"!**/node_modules/**/{test,__tests__,docs,example}/**"
],
"asar": true,
"asarUnpack": [
"**/node_modules/**/*.node",
"resources/bin/**"
],
"electronLanguages": ["zh-CN", "en-US"],
"win": {
"target": [
{ "target": "nsis", "arch": ["x64"] },
{ "target": "zip", "arch": ["x64"] }
],
"icon": "build/icon.ico",
"signAndEditExecutable": true
},
"nsis": {
"oneClick": false,
"perMachine": false,
"allowToChangeInstallationDirectory": true,
"createDesktopShortcut": true,
"createStartMenuShortcut": true,
"deleteAppDataOnUninstall": false
},
"mac": {
"target": [
{ "target": "dmg", "arch": ["x64", "arm64"] },
{ "target": "zip", "arch": ["x64", "arm64"] }
],
"category": "public.app-category.productivity",
"hardenedRuntime": true,
"entitlements": "build/entitlements.mac.plist",
"notarize": true
},
"linux": {
"target": ["AppImage", "deb"],
"category": "Utility",
"icon": "build/icons"
},
"publish": [
{
"provider": "generic",
"url": "https://dl.example.com/desktop/${channel}",
"channel": "latest"
}
]
}
}
<!-- build/entitlements.mac.plist:强化运行时所需的权限声明 -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<!-- 运行时需要即时编译能力 -->
<key>com.apple.security.cs.allow-jit</key>
<true/>
<!-- 需要加载应用内动态库 -->
<key>com.apple.security.cs.disable-library-validation</key>
<true/>
<!-- 需要访问用户选择的文件 -->
<key>com.apple.security.files.user-selected.read-write</key>
<true/>
</dict>
</plist>
要点:文件白名单排除源映射与测试目录;原生模块与外部程序必须解包;语言包按需保留;两类平台分别声明签名与公证相关配置。
3.2 更新逻辑
// main/updater.js:更新检查与安装
const { autoUpdater } = require('electron-updater');
const { dialog, BrowserWindow, app } = require('electron');
function setupUpdater(win) {
// 更新源来自打包配置;如使用自建服务可按通道覆盖
autoUpdater.currentVersion = app.getVersion();
autoUpdater.autoDownload = true;
autoUpdater.autoInstallOnAppQuit = true;
autoUpdater.on('checking-for-update', () => {
console.log('[updater] 检查更新');
});
autoUpdater.on('update-available', (info) => {
console.log('[updater] 发现新版本', info.version);
win?.webContents.send('update:available', { version: info.version });
});
autoUpdater.on('update-not-available', () => {
console.log('[updater] 已是最新版本');
});
autoUpdater.on('download-progress', (progress) => {
// 进度回传界面,避免用户以为无响应
win?.webContents.send('update:progress', {
percent: Math.round(progress.percent),
transferred: progress.transferred,
total: progress.total,
});
});
autoUpdater.on('update-downloaded', async (info) => {
const { response } = await dialog.showMessageBox(win, {
type: 'info',
buttons: ['立即重启安装', '稍后'],
defaultId: 0,
cancelId: 1,
message: `新版本 ${info.version} 已下载完成`,
detail: '重启应用后生效。',
});
if (response === 0) autoUpdater.quitAndInstall();
});
autoUpdater.on('error', (err) => {
// 更新失败不应影响应用使用,记录并提示可手动下载
console.error('[updater] 更新失败', err);
win?.webContents.send('update:error', { message: '更新失败,可稍后重试' });
});
// 启动后延迟检查,避免与启动过程争抢资源
setTimeout(() => {
autoUpdater.checkForUpdates().catch((err) => console.error('[updater]', err));
}, 10_000);
// 周期性检查
setInterval(() => {
autoUpdater.checkForUpdates().catch(() => {});
}, 6 * 60 * 60 * 1000);
// 手动检查入口
return () => autoUpdater.checkForUpdates();
}
module.exports = { setupUpdater };
# 更新服务目录结构(以通用源为例)
/desktop/latest/
├── latest.yml # Windows 元数据:版本号、产物、摘要
├── latest-mac.yml # macOS 元数据
├── latest-linux.yml # Linux 元数据
├── 示例应用-1.4.0-setup.exe
├── 示例应用-1.4.0-setup.exe.blockmap # 差分索引
├── 示例应用-1.4.0.dmg
└── 示例应用-1.4.0-mac.zip
# 缓存策略
# 元数据文件:不缓存或极短缓存,保证发布后客户端能立即看到新版本
# 产物文件:按版本号命名,可长期缓存
3.3 发布流程
# 1. 校验工作区干净并确认版本号已更新(版本必须单调递增)
git status --porcelain | grep -q . && { echo "存在未提交改动"; exit 1; }
node -e "console.log(require('./package.json').version)"
# 2. 按锁文件安装依赖(保证构建可复现)
npm ci
# 3. 静态检查与类型检查
npm run lint && npx tsc --noEmit
# 4. 构建三份产物并打包(签名凭据由流水线注入,不写入配置文件)
npm run build
export CSC_LINK="$SIGN_CERT_BASE64" # 由流水线密钥注入
export CSC_KEY_PASSWORD="$SIGN_CERT_PASS"
npx electron-builder --publish never
# 5. 校验产物:签名状态与体积
ls -lh release/
# Windows:确认签名有效
# osslsigncode verify -in "release/示例应用-1.4.0-setup.exe"
# macOS:确认签名与公证
# codesign --verify --deep --strict --verbose=2 "release/mac/示例应用.app"
# spctl --assess --type execute --verbose "release/mac/示例应用.app"
# 6. 生成校验值并随版本留档
sha256sum release/*.exe release/*.dmg > release/SHA256SUMS
# 7. 先上传产物再更新元数据,保证客户端看到的元数据对应的产物已存在
# 上传顺序:产物 -> 差分索引 -> 元数据
# 8. 按比例放量:先小范围用户的更新地址指向新版本,确认无误后全量
# 回滚:发布一个版本号更高的旧代码包,客户端按正常更新流程回退到旧行为
# 1. 从历史标签检出行问题前版本
git checkout v1.3.2
# 2. 提升补丁号并重新构建签名
npm version 1.4.1 --no-git-tag-version
npm run dist
# 3. 上传并更新元数据,客户端检查更新后即回退到旧行为
3.4 常见问题对照
| 现象 | 常见原因 | 处置 |
|---|---|---|
| 安装后应用无法启动且系统提示来源不可信 | 未签名或未完成公证 | 完成两类签名与公证并核对安全机制评估结果 |
| 加固运行时启用后应用启动失败 | 缺少必要的权限声明 | 按实际能力补充声明后重新签名 |
| 历史版本在证书到期后校验失败 | 签名未加时间戳 | 签名时启用时间戳 |
| 打包后原生模块加载失败 | 模块未解包或与运行时版本不匹配 | 解包原生模块并按其运行时版本重新编译 |
| 打包后找不到资源文件 | 资源路径按开发时的相对层级书写 | 统一通过路径接口获取资源位置 |
| 安装包体积异常大 | 打入了开发依赖与非必需资源与全部语言包 | 收紧文件白名单并剔除多余语言包 |
| 部分用户安装包无法运行 | 架构不匹配 | 补充对应架构产物或发布通用包 |
| 发布新版本后客户端长时间检测不到 | 更新元数据被缓存 | 元数据不缓存或设置极短缓存 |
| 客户端下载到不完整产物 | 元数据先于产物上传 | 按"产物、差分索引、元数据"的顺序上传 |
| 更新安装后应用无法启动 | 新旧版本签名身份不一致或产物被篡改 | 统一签名身份并校验产物签名与摘要 |
| 更新失败导致应用不可用 | 未保留旧版本可启动 | 安装失败时保留旧版本并提供手动下载入口 |
| 需要回退但客户端不降级 | 更新机制默认只允许升级 | 发布版本号更高的旧代码包 |
| 测试版本下发到了正式用户 | 未做通道分离 | 稳定与测试使用不同更新地址 |
四、总结
- 桌面分发与网页部署的差别在分发形态、平台矩阵、系统信任与更新机制四处,工作量集中在打包与签名与更新服务。
- 打包分两段:前端构建工具负责资源组织,打包工具负责归档与平台适配与签名与安装包生成,两者职责不应混淆。
- 平台与架构矩阵应在项目早期确定,因为它决定签名凭据、构建执行机与测试矩阵。
- 归档格式减少文件数量并加快加载,但原生模块与需要以路径调用的外部程序必须解包,资源位置也应统一通过接口获取。
- 体积治理的手段是运行期依赖白名单与剔除语言包与压缩归档,收益同时体现在下载、安装与启动。
- 两类平台必须完成签名与公证,签名凭据经流水线密钥注入且必须加时间戳以覆盖证书到期场景。
- 自动更新由元数据、产物与客户端逻辑组成,增量更新依赖差分索引,检查时机应在启动后延迟并周期执行。
- 更新机制默认只允许升级,因此回滚采用"更高版本号重新发布旧代码"的方式,不能依赖客户端降级。
- 版本号、通道与灰度三者需要同时管理:通道隔离测试与正式,灰度控制放量范围并支持暂停。
- 发布顺序是"产物、差分索引、元数据",元数据不缓存、产物按版本命名可长期缓存,从而保证发布即时生效且下载高效。