本文说明 Electron 应用的打包、签名与发布流程。安全基线与更新链路的信任要求见 Electron 安全加固,构建产物与体积治理见 前端工程化,静态资源缓存与分发见 Nginx 缓存机制与实践 与 CDN 原理与接入排障,制品仓库与制品治理的通用要求见 构建与制品仓库,版本与发布流程的组织见 变更与发布管理,产物校验与签名在安全体系中的位置见 密码学与安全架构。

一、起源

1.1 与网页部署的四处差别

差别 说明 带来的工作量
分发形态 需要安装包或压缩包,而不是上传静态文件 需要打包与安装器配置
平台矩阵 需要覆盖多个操作系统与处理器架构 构建与测试矩阵成倍增加
系统信任 未签名的应用会被系统提示或拦截 需要证书、签名与公证流程
更新机制 用户不会主动重新下载安装 需要内置更新与更新服务

1.2 需要回答的问题

  1. 要发布哪些平台与架构,是否需要通用包。
  2. 采用哪种分发形态,是否需要管理员权限安装。
  3. 更新如何下发、如何回滚、如何控制放量范围。
  4. 签名凭据由谁保管、如何进入流水线而不泄露。

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 常见问题对照

现象 常见原因 处置
安装后应用无法启动且系统提示来源不可信 未签名或未完成公证 完成两类签名与公证并核对安全机制评估结果
加固运行时启用后应用启动失败 缺少必要的权限声明 按实际能力补充声明后重新签名
历史版本在证书到期后校验失败 签名未加时间戳 签名时启用时间戳
打包后原生模块加载失败 模块未解包或与运行时版本不匹配 解包原生模块并按其运行时版本重新编译
打包后找不到资源文件 资源路径按开发时的相对层级书写 统一通过路径接口获取资源位置
安装包体积异常大 打入了开发依赖与非必需资源与全部语言包 收紧文件白名单并剔除多余语言包
部分用户安装包无法运行 架构不匹配 补充对应架构产物或发布通用包
发布新版本后客户端长时间检测不到 更新元数据被缓存 元数据不缓存或设置极短缓存
客户端下载到不完整产物 元数据先于产物上传 按"产物、差分索引、元数据"的顺序上传
更新安装后应用无法启动 新旧版本签名身份不一致或产物被篡改 统一签名身份并校验产物签名与摘要
更新失败导致应用不可用 未保留旧版本可启动 安装失败时保留旧版本并提供手动下载入口
需要回退但客户端不降级 更新机制默认只允许升级 发布版本号更高的旧代码包
测试版本下发到了正式用户 未做通道分离 稳定与测试使用不同更新地址

四、总结

  1. 桌面分发与网页部署的差别在分发形态、平台矩阵、系统信任与更新机制四处,工作量集中在打包与签名与更新服务。
  2. 打包分两段:前端构建工具负责资源组织,打包工具负责归档与平台适配与签名与安装包生成,两者职责不应混淆。
  3. 平台与架构矩阵应在项目早期确定,因为它决定签名凭据、构建执行机与测试矩阵。
  4. 归档格式减少文件数量并加快加载,但原生模块与需要以路径调用的外部程序必须解包,资源位置也应统一通过接口获取。
  5. 体积治理的手段是运行期依赖白名单与剔除语言包与压缩归档,收益同时体现在下载、安装与启动。
  6. 两类平台必须完成签名与公证,签名凭据经流水线密钥注入且必须加时间戳以覆盖证书到期场景。
  7. 自动更新由元数据、产物与客户端逻辑组成,增量更新依赖差分索引,检查时机应在启动后延迟并周期执行。
  8. 更新机制默认只允许升级,因此回滚采用"更高版本号重新发布旧代码"的方式,不能依赖客户端降级。
  9. 版本号、通道与灰度三者需要同时管理:通道隔离测试与正式,灰度控制放量范围并支持暂停。
  10. 发布顺序是"产物、差分索引、元数据",元数据不缓存、产物按版本命名可长期缓存,从而保证发布即时生效且下载高效。