Electron 自动更新（electron-updater）完整流程梳理

在 Electron 应用开发中，“自动更新”是一个非常实用但又容易踩坑的功能。本文从实际工程角度出发，梳理基于 electron-updater + electron-builder 的完整更新流程，以及关键原理和实现方式。

---

一、整体架构

自动更新本质是一个非常简单的模型：

客户端（Electron App）
        ↓
请求 latest.yml
        ↓
版本对比
        ↓
下载新安装包
        ↓
安装更新

其中：

• electron-builder：负责打包 & 生成更新文件
• electron-updater：负责检查更新、下载、安装（逻辑层）
• 服务器：仅提供静态文件（无需额外服务）

---

二、打包阶段（electron-builder）

执行打包命令后：

npm run build

会生成以下关键文件：

dist/
  ├── app-1.0.3.exe
  ├── app-1.0.3.exe.blockmap
  └── latest.yml

latest.yml 是什么？

它是更新系统的核心索引文件，内容类似：

version: 1.0.3
files:
  - url: app-1.0.3.exe
    sha512: xxxx
path: app-1.0.3.exe
sha512: xxxx
releaseDate: '2026-03-27T10:00:00.000Z'

作用：

• 标记“当前最新版本”
• 指定下载地址
• 提供校验信息（sha512）

---

三、服务器部署

你只需要一个静态文件服务器即可，例如：

• OSS / S3
• Nginx
• CDN

目录结构：

/update/
  ├── latest.yml
  ├── app-1.0.3.exe
  └── app-1.0.3.exe.blockmap

访问路径：

https://your-server/update/latest.yml

---

四、客户端配置

1. package.json 配置

{
  "build": {
    "publish": [
      {
        "provider": "generic",
        "url": "https://your-server/update/"
      }
    ]
  }
}

---

2. 检查更新

import { autoUpdater } from 'electron-updater'

autoUpdater.checkForUpdates()

执行后：

1. 请求 latest.yml
2. 对比版本号
3. 判断是否需要更新

---

五、更新流程（事件驱动）

electron-updater 通过事件驱动整个流程：

autoUpdater.on('checking-for-update', () => {})

autoUpdater.on('update-available', () => {})

autoUpdater.on('update-not-available', () => {})

autoUpdater.on('download-progress', () => {})

autoUpdater.on('update-downloaded', () => {})

完整流程：

checkForUpdates()
   ↓
checking-for-update
   ↓
update-available（有更新）
   ↓
下载更新
   ↓
download-progress
   ↓
update-downloaded
   ↓
quitAndInstall()

---

六、UI 与逻辑的职责划分

electron-updater 负责：

• 检查更新
• 下载文件
• 校验完整性
• 安装更新

你需要自己实现：

• 更新提示 UI
• 是否下载
• 进度展示
• 是否立即安装

---

七、典型实现（推荐方案）

main 进程

autoUpdater.on('update-available', () => {
  mainWindow.webContents.send('update-available')
})

autoUpdater.on('download-progress', (progress) => {
  mainWindow.webContents.send('update-progress', progress)
})

autoUpdater.on('update-downloaded', () => {
  mainWindow.webContents.send('update-downloaded')
})

---

renderer 进程

ipcRenderer.on('update-available', () => {
  // 显示弹窗
})

ipcRenderer.on('update-progress', (_, progress) => {
  // 更新进度条
})

ipcRenderer.on('update-downloaded', () => {
  // 提示安装
})

---

八、三种更新策略

1. 静默更新

启动 → 自动下载 → 下载完成提示安装

---

2. 半自动（推荐）

发现更新 → 用户确认 → 下载 → 安装

---

3. 强制更新

发现更新 → 必须更新

（需自行实现）

---

九、常见问题

1. 为什么不触发更新？

可能原因：

• version 没变化
• latest.yml 未更新
• URL 配置错误
• 开发环境未打包

---

2. 是否需要写更新接口？

不需要。

标准流程只需要：

静态服务器 + latest.yml

---

3. 是否能自动监听文件变化？

不能。

更新检测是主动触发的：

autoUpdater.checkForUpdates()

---

十、总结

自动更新的本质可以概括为一句话：

通过 latest.yml 作为索引，客户端主动检查版本 → 下载新安装包 → 完成更新

核心要点：

• 不需要后端服务
• latest.yml 是关键
• UI 必须自己实现
• 更新检测是主动触发

---

十一、实践建议

对于中小项目：

• 直接使用 OSS / CDN
• 不要一开始做灰度发布
• 优先保证流程稳定

等业务复杂后再考虑：

• 灰度更新
• 强制更新
• 权限控制

---

这套方案已经可以覆盖 90% 的 Electron 应用更新场景。