第一个现场很普通:程序从 1.4.2 升到 1.5.0,安装完成,客户电话来了——设备列表空了,账号也要重新登录。远程一看,数据库和配置文件都写在安装目录里,新版本安装时旧目录被替换,备份也没留。开发机上从来没出过这个问题,因为开发机一直跑在源码目录里,根本没走过一遍真正的安装流程。

第二个现场:安装包发到客户群里,下载完点开,Windows 弹出蓝色的「Windows 已保护你的电脑」,默认按钮是「不运行」。客户的 IT 回了一句话:没有数字签名,不允许装。程序本身没有任何问题,卡在信任这一步。

第三个现场:更新到一半,现场停电。来电后程序打不开,提示缺文件;想装回旧版本也不行,因为新版本已经写了一半,数据库还多出了一张表。这三个现场指向同一件事:更新不是「下载一个新包、覆盖旧文件」,它要同时处理用户数据、安装权限、文件完整性和版本回退。

这篇以 Electron 的 electron-updater 和 electron-builder 为主讲一条完整的发布链路:版本与通道怎么配、NSIS 两种安装模式差在哪、签名到底解决了什么、灰度与回滚怎么做、数据库迁移放在哪一步。本机装了 Electron 45.2.3,但进程启动即崩(0xC0000005);electron-builder 没有安装,所以更新链路只做到配置与命令核对,真实更新、签名与回滚未验证,具体版本行为以你实际构建为准。

先把三种「数据」分开

更新出事,绝大多数不是更新器写错了,是数据放错了地方。一个桌面程序至少有三类数据,生命周期完全不同:

程序文件exe、dll、前端资源、运行时。属于某个版本,更新时整批替换,可以随时丢弃重装。放在安装目录。
用户数据数据库、配置、登录态、缓存、用户生成的文件。属于用户,跨版本必须保留。放在 %APPDATA% 或 %LOCALAPPDATA% 下按产品名分目录。
更新缓存下载下来的安装包、增量块、校验文件。属于一次更新行为,下载完成或安装完成后可以清理,坏了重下即可。

「升级一次数据全没了」的根因,通常是把第二类塞进了第一类。安装程序替换目录时不会区分哪个文件是用户数据。另一条路径是卸载时勾了「同时删除用户数据」,而更新内部走了卸载再安装;electron-builder 的 NSIS 默认不删,但把 deleteAppDataOnUninstall 打开后,升级就可能变成清空。

所以第一步不是选工具,是画一张表:每个文件属于谁、升级时保留还是替换、卸载时删不删。这张表定了,选 per-user 还是 per-machine、迁移放哪才有依据。测试也必须测「覆盖安装」,并且用一份有真实数据的旧版本去升,只测全新安装永远发现不了数据丢失。

不要为了「干净」在更新脚本里删除整个用户数据目录。清理缓存和清空业务数据是两件事,前者可以自动做,后者必须由用户明确确认。这两件事在代码里经常只差一个路径变量,出事时却不可逆。

版本号、通道与更新源

electron-updater 判断「有没有新版本」,靠运行时读到的当前版本和更新源上的元数据。package.json 的 version 会被写进程序,元数据由 electron-builder 打包时生成,通常叫 latest.yml。两边对不上,就会出现发了新包、客户端却说已是最新。

版本号用语义化版本(semver):主版本.次版本.修订号。修 bug 升修订号,加功能升次版本,破坏兼容升主版本。更新器按数值比较,1.10.0 大于 1.9.0,不是按字符串比。预发布版本带后缀,比如 1.5.0-beta.1,默认不会被稳定通道的用户收到,这正好可以用来做内测。

通道(channel)决定「哪群用户拿到哪个版本」:latest 给全量,beta 给内测,internal 给公司内部。每个通道对应一套元数据文件,客户端启动时告诉更新器自己属于哪个通道。灰度不需要复杂算法,按客户分组给不同更新源就能分批放量。

更新源用静态文件服务就够了:generic 只要求一个能通过 HTTPS 访问的目录,里面放安装包、latest.yml 和增量块文件。GitHub Releases 也可以,但企业内网更常见的是对象存储或 CDN。地址必须 HTTPS,且不能让渲染进程随意修改。

electron-builder 打包时会在资源目录里生成一份 app-update.yml,里面记录更新源。这份文件是构建产物,不要手写、不要和构建配置里的 publish 对着改,否则会出现「代码里配了 A,程序实际去 B 查」的怪事。

还有一个前提:electron-updater 只在打包后的程序里工作,开发模式下 app.isPackaged 为 false,npm start 里测不出更新是正常的。

场景走查:把 1.0.0 升到 1.0.1

需求:做一个最小的 Electron 程序,先装 1.0.0,再发布 1.0.1,让已安装的 1.0.0 自己发现、下载、重启并变成 1.0.1,同时用户数据目录里的内容保持不变。这里用一个本地静态服务器模拟更新源。

先准备依赖和脚本。构建工具放开发依赖,更新器放运行依赖,因为它要打进包里:

npm init -y
npm install electron electron-updater
npm install -D electron-builder
npx electron-builder --version

package.json 里最少要有版本、入口和打包脚本。版本号就是更新的基准,每次发版必须改:

{
  "name": "device-hub",
  "version": "1.0.0",
  "main": "main.js",
  "scripts": {
    "start": "electron .",
    "dist": "electron-builder --win nsis"
  },
  "dependencies": {
    "electron-updater": "^6.0.0"
  }
}

构建配置单独放一个 electron-builder.yml。下面这份是「可以开始用」的典型配置,不是最优配置:publish 指向本地或线上的静态目录,nsis 选 assisted 安装、默认 per-user,允许用户改安装路径。

appId: com.example.devicehub
productName: DeviceHub
directories:
  output: release
  buildResources: build
files:
  - dist/**/*
  - package.json
win:
  target:
    - target: nsis
      arch: [x64]
  certificateFile: build/cert.pfx
  certificatePassword: ${env.CSC_KEY_PASSWORD}
nsis:
  oneClick: false
  perMachine: false
  allowToChangeInstallationDirectory: true
  createDesktopShortcut: true
publish:
  provider: generic
  url: https://dl.example.com/devicehub/
  channel: latest

主进程里接上更新器。要点有三个:只在打包后启用、不让它自动下载(把「什么时候装」的决定权留给用户或策略)、下载完成后调用 quitAndInstall 退出并安装。

const { app, BrowserWindow } = require("electron");
const { autoUpdater } = require("electron-updater");
const path = require("node:path");

function createWindow() {
  const win = new BrowserWindow({
    width: 1100,
    height: 720,
    webPreferences: {
      preload: path.join(__dirname, "preload.js"),
      contextIsolation: true,
      nodeIntegration: false
    }
  });
  win.loadFile("dist/index.html");
  return win;
}

app.whenReady().then(() => {
  const win = createWindow();

  if (!app.isPackaged) return;

  autoUpdater.autoDownload = false;

  autoUpdater.on("update-available", (info) => {
    win.webContents.send("update-state", { state: "available", version: info.version });
  });

  autoUpdater.on("download-progress", (p) => {
    win.webContents.send("update-state", { state: "progress", percent: p.percent });
  });

  autoUpdater.on("update-downloaded", () => {
    win.webContents.send("update-state", { state: "ready" });
  });

  autoUpdater.on("error", (err) => {
    win.webContents.send("update-state", { state: "error", message: err.message });
  });

  autoUpdater.checkForUpdates();
});

安装与发布按这个顺序走。第一步,构建 1.0.0,把 release 目录里的安装包和 latest.yml 放进静态服务器的目录:

npm run dist
mkdir update-feed
copy release\DeviceHub-Setup-1.0.0.exe update-feed\
copy release\latest.yml update-feed\
npx http-server update-feed -p 8080 --cors

第二步,装 1.0.0,启动一次,在 %APPDATA%\DeviceHub 放一个标记文件,关掉程序。第三步,把版本改成 1.0.1 重新 npm run dist,把新包和 latest.yml 覆盖到 update-feed;构建时的 publish.url 指向本地服务(正式环境必须 HTTPS)。

预期结果:启动 1.0.0,主进程发现「新版本 1.0.1」;界面依次收到 available、进度、ready;调用 quitAndInstall 后程序退出、安装、重启,版本变成 1.0.1,marker.txt 还在。per-user 安装全程不应出现 UAC。

几个容易卡住的地方:更新器读的是打包时写入的版本,改了 package.json 不重新打包等于没改;latest.yml 必须可访问,路径大小写和缓存头都会影响结果;本地 http 只能验证流程,验证不了 HTTPS 与信任链。

增量更新这块,electron-updater 在 NSIS 下会尝试用块文件做差分下载;服务端缺块文件或客户端缓存被清时自动回退全量。不要承诺「每次只下几 MB」,是否命中取决于版本差异和缓存。

NSIS 的两种安装模式

Windows 上最常见的是 NSIS 安装器,它有两种身份:per-user 和 per-machine。选哪种不是偏好问题,是权限模型问题,而且一旦装出去就很难改。

per-user(每用户安装)

装到 %LOCALAPPDATA%\Programs 下,不需要管理员权限,更新时也不需要提权。每个 Windows 用户各装一份,互不干扰。适合互联网分发、没有 IT 统一管控的场景。

per-machine(每台机器安装)

装到 Program Files,装一次全机器可用,安装和更新都需要 UAC 提权。适合企业统一部署,但自动更新在无人值守时可能因为提权失败而卡住。

最麻烦的不是选错,是混用。用户先 per-user 装了一份,IT 又 per-machine 装了一份,桌面上两个快捷方式分别指向 LocalAppData 和 Program Files。更新器只更新当前进程对应的安装,另一个副本不动,用户点旧图标看到的还是旧版本。排查先看 process.execPath。

两个配置细节:allowToChangeInstallationDirectory 只在 oneClick: false 时有效;卸载是否删除用户数据由 deleteAppDataOnUninstall 控制,默认保留,更新流程会触发卸载时务必确认它是关的。

签名:SmartScreen 到底在看什么

代码签名解决「这个文件是谁做的、发布后有没有被改过」。Windows 用 Authenticode:对文件做摘要,用证书私钥签名,把证书链和签名附在文件上。系统验证时重算摘要、验签、顺链找到受信任的根。签名还带时间戳,证书到期后仍能证明签名时证书有效。

没签名的安装包,SmartScreen 显示「未知发布者」并默认阻止;有签名但证书新、下载量小的程序也可能先被警告,等信誉积累才消失。签名不是免死金牌,它只是把程序从「可疑」变成「可评估」。EV 证书在社区反馈里通常更快建立信任,但没有官方保证。

用命令行签名,核心参数是摘要算法、时间戳服务和证书:

signtool sign /fd sha256 /td sha256 ^
  /tr http://timestamp.digicert.com ^
  /f build\cert.pfx /p %CSC_KEY_PASSWORD% ^
  "release\DeviceHub-Setup-1.0.1.exe"

时间戳服务地址要选可用的,不同 CA 提供的地址不同,具体以证书提供方为准(待确认)。签名要对「最终用户会执行的那个文件」做:安装包本身,以及安装包解出来的主程序。只签安装包、不签里面的 exe,安装后主程序仍然是未签名状态,杀毒软件和系统策略照样会找麻烦。

证书不要提交到仓库,放在密钥库或硬件令牌里,通过 CSC_LINK 和 CSC_KEY_PASSWORD 这类环境变量传给构建;证书密码不要打印到日志。

验证签名不能只看「有没有」,要看状态:

Get-AuthenticodeSignature "release\DeviceHub-Setup-1.0.1.exe" |
  Format-List Status, SignerCertificate

预期 Status 是 Valid,证书 Subject 和公司信息一致。NotSigned 说明签名没跑,HashMismatch 说明签名后文件被改,UnknownError 多半是证书链或时间戳问题。

macOS 只点到为止:需要 Apple Developer 账号,codesign 签名、notarytool 公证、再把票据 staple 到安装包;少了公证,用户会看到「无法验证开发者」。electron-builder 能串起流程,但账号和证书要提前准备。

签名保护的是「文件没被篡改」,不保护「更新源被换掉」。electron-updater 会用元数据里的 sha512 校验下载到的安装包,但如果攻击者能改 latest.yml,他也能把哈希改成自己包的哈希。更新源的写权限和签名私钥一样,都是发布链路里最敏感的东西。

灰度、回滚、迁移与断电

灰度发布的目的不是「显得专业」,是缩小坏版本的爆炸半径。先内部通道观察,再放给少数客户,没问题再全量;工具不一定提供百分比分流,可以按客户分组给不同的更新源。关键是能随时停止放量:撤下安装包或改回 latest.yml,新检查的客户端就不再升级。

回滚比灰度难。electron-updater 默认不允许降级。最稳的补救是发一个版本号更高的修复版;来不及就临时打开 allowDowngrade,但旧版本可能读不懂新版本迁移过的数据库。先想清楚数据能不能退,再谈回滚。

数据库迁移放在更新后的首次启动,不要放进安装器。安装器可能以管理员身份运行,而用户数据属于当前普通用户;一台机器可能多个用户,各自都要迁移;安装完成不等于马上启动,放在启动时才能保证迁移用的代码就是即将使用这份数据的代码。安装器只替换程序文件。

迁移要满足四条:先备份、在一个事务里完成、记录 schema 版本、可重复执行。备份放在用户数据目录旁边并带旧版本号;事务保证失败不留半张表;schema 版本让程序知道数据是哪个版本写的;重复执行不会重复加列。失败时明确报错并停在安全状态。

-- 用 SQLite 的 user_version 记录 schema 版本,示意
-- 迁移前先复制一份 device.db 到 device.db.bak-1.4.2
BEGIN;
-- 按当前 user_version 逐段执行 ALTER / CREATE
PRAGMA user_version = 2;
COMMIT;

断电要分两个阶段看。下载阶段相对安全:安装包落到临时目录,校验通过才安装,断电最多缓存损坏,重下即可。安装阶段才是风险窗口:文件正在替换,断电或杀毒软件锁文件都可能留下新旧混杂的目录。NSIS 没有「要么全成要么全回」的保证,所以要有补救路径:安装包可重复执行、程序启动自检关键文件、服务端保留上一个可用版本。

「更新到一半断电起不来」,第一步是确认损坏在哪一层:程序文件缺失就重装同版本;数据库损坏就从备份恢复;两者都坏了才考虑回滚。把这三条写进运维文档,比在代码里加重试有用。

现象、原因与第一步

现象真实原因第一步查什么
升级后用户数据全没了数据库或配置写在安装目录,被新版本覆盖看数据文件路径是否在 userData 下,安装器配置有没有删用户数据
SmartScreen 提示未知发布者安装包或主程序未签名,签名没有时间戳用 Get-AuthenticodeSignature 看 Status,确认签的是最终文件
发了新包,客户端说已是最新版本号没改、没重新打包,或通道元数据没更新对比 package.json 版本、安装包文件名和 latest.yml 里的版本
更新完成,重启还是旧版本per-user 与 per-machine 混装,快捷方式指向另一个副本看 process.execPath 和快捷方式目标路径
下载完成但安装没反应per-machine 更新需要提权,无人值守时被拦看安装日志和 UAC 相关事件,确认安装模式
开发环境检查更新报错未打包,app.isPackaged 为 false确认测试用的是安装后的程序,不是 npm start
更新后程序打不开、提示缺文件安装阶段被中断,目录里新旧文件混杂检查安装目录文件时间戳,重装同版本验证是否恢复
卸载后配置和登录态丢失开启了卸载删除用户数据,或数据本来就在安装目录看 deleteAppDataOnUninstall,检查数据实际路径

边界与代价

第一,签名有持续成本。证书要买、要续,私钥要放在硬件令牌或云密钥库里;换证书意味着信誉重新积累,老客户可能又看到警告。签名证明发布者身份,不证明程序没有漏洞。

第二,自动更新扩大了攻击面。更新器是程序里唯一能「下载并执行代码」的组件,更新源、元数据、私钥任何一环被控制,影响都是全量用户。写权限要单独管控,元数据走 HTTPS,客户端不要接受页面传来的更新地址。

第三,测试矩阵比普通功能大。要覆盖全新安装、覆盖安装、跨版本升级、两种安装模式、无网络、代理、杀毒拦截、安装中断、迁移成功与失败,每一条都要真跑过。

第四,electron-updater 的能力有边界。它没有内置的百分比灰度和自动回滚;差分下载依赖块文件和缓存,不保证每次命中;主要面向打包后的 NSIS、AppImage 等目标。这些是工具范围,不是缺陷,方案设计时要当成既定条件。

第五,macOS 与 Windows 的发布链路差别很大。签名体系、公证流程、安装包格式、权限模型都不同,不能把 Windows 的经验直接套过去。Linux 的分发又是另一套,本文没有展开。

第六,用户数据迁移是单向的,旧版本读不懂新 schema,这是回滚最大的障碍。「先备份再迁移」要落成代码:备份真实存在、能恢复、流程演练过。没演练过的备份等于没有备份。

小结与练习

更新这件事可以压成四句话:程序文件和用户数据必须分开;版本号是更新的唯一依据,通道决定谁能拿到;签名解决信任,更新源安全解决完整性;迁移放在更新后的首次启动,并且先备份、再事务、可重复。把这四件做对,剩下的才是工具细节。

当天可以自己验证的练习:

  1. 按上面的走查做一遍 1.0.0 到 1.0.1 的本地更新,记录四个事件出现的顺序,确认升级后用户数据目录里的标记文件还在。
  2. 把版本号改回 1.0.0 再打包,观察客户端是否还说「已是最新」,理解版本号的作用。
  3. 用自签名证书给安装包签名,安装时观察 SmartScreen 的反应,再和未签名的情况对比,理解「签名」和「信誉」不是一回事。
  4. 把 perMachine 改成 true 重新构建,记录安装路径变化和 UAC 提示出现的时机。
  5. 在下载中途强制结束进程,再在安装中途强制结束安装器,分别检查程序目录和用户数据,写下一份恢复步骤。

下一篇讲内存、启动与安装包体积。包能发出去了,接下来要面对客户最直接的三个抱怨:安装包太大不想下、启动要等好几秒、开一天内存涨到吓人。这些数字背后分别是谁在占,怎么量,哪些能优化、哪些只能接受。