electron-updater

一句话：electron-builder 配套的自动更新库，为打包后的应用提供多渠道（GitHub/通用服务器/S3）、差量（Windows）、跨平台的自更新能力。与 electron-builder 同仓库（14.6k stars）。

与官方 autoUpdater 的关系

	官方 `autoUpdater`（electron 内置）	`electron-updater`（本库）
依赖	无，框架自带	配合 electron-builder 打包产物使用
更新源	需自建符合 feed 协议的服务端	内置 `generic`（静态文件）/`github`/`s3` 等多种 provider
差量更新	无	Windows NSIS 支持（基于 blockmap）
平台格式	macOS 要 zip；Windows 要 Squirrel/Nuts 格式	跟随 electron-builder 产物（nsis/dmg/zip/AppImage）
典型搭配	`update-electron-app`（05-packaging-distribution）	electron-builder + 本库

核心机制：打包时生成更新清单 latest.yml（Windows）/ latest-mac.yml（macOS）/ latest-linux.yml（Linux），随安装包一起发布；运行时 autoUpdater 拉清单对比版本 → 下载 → 安装。

Feed 协议结构（generic）

协议就是纯静态文件，没有 JSON API：

检查更新：GET <feedURL>/<channel>.yml —— Windows latest.yml / macOS latest-mac.yml / Linux latest-linux.yml；channel 设为 beta 则请求 beta.yml。请求带 Cache-Control: no-cache
yml 结构：

version: 0.1.262
files:
  - url: app-setup.exe        # 相对（基于 feedURL 拼接）或绝对地址
    sha512: base64...
    size: 170958776
    blockMapSize: 12345       # Windows 差量用
path: app-setup.exe           # 顶层兼容字段
sha512: base64...
releaseDate: '2026-08-31T06:44:09.000Z'

版本按 semver 比较，远端更高才触发 update-available
Windows 差量更新会额外请求 <url>.blockmap，再用 HTTP Range 请求只下变更块 → 服务端必须支持 Accept-Ranges
下载完成后校验 sha512，不匹配即失败
更新源地址来自安装目录内的 app-update.yml（打包时按 publish 配置写入），开发模式对应 dev-app-update.yml

快速接入

应用侧（运行时依赖，不是 dev）：

npm install electron-updater

主进程最小示例：

const { app } = require('electron')
const { autoUpdater } = require('electron-updater')
 
app.whenReady().then(() => {
  autoUpdater.autoDownload = false        // 建议先提示用户再下载
  autoUpdater.checkForUpdates()
 
  autoUpdater.on('update-available', (info) => {
    // info.version 来自 latest.yml；此处弹窗确认
    autoUpdater.downloadUpdate()
  })
  autoUpdater.on('download-progress', ({ percent }) => {
    console.log(`下载进度: ${percent}%`)
  })
  autoUpdater.on('update-downloaded', () => {
    autoUpdater.quitAndInstall()           // 退出并安装；也可推迟到用户下次启动
  })
  autoUpdater.on('error', (err) => console.error('更新失败', err))
})

一键模式（自动下载并通知，适合内网强制更新）：

autoUpdater.checkForUpdatesAndNotify()

更新源配置

方式 1：electron-builder 的 `publish` 配置（推荐）

打包配置里声明，发布时自动生成 app-update.yml 打进安装包：

# electron-builder.yml
publish:
  - provider: github
    owner: my-org
    repo: my-app

支持的 provider：

provider	场景
`github`	公网开源项目，直接读 GitHub Releases
`generic`	任意静态文件服务器（内网最常用）：`url: https://update.internal.example.com/app/`
`s3`	AWS S3 桶

npm run dist            # 只打包，不发布（产物含 latest*.yml）
npx electron-builder --publish never   # 同上
# 手动把 out/ 里的安装包 + latest*.yml 传到静态服务器对应目录即可

方式 2：运行时动态指定

autoUpdater.setFeedURL({
  provider: 'generic',
  url: 'https://update.example.com/releases/'
})

适合开发/测试环境切源。注意：未打包的 electron . 开发模式下更新逻辑不生效（可用 UPDATER_FORCE_DEV=true 强制，仅调试用）。

常用选项与事件

属性/事件	说明
`autoDownload`	发现新版本是否自动下载（默认 `true`，建议设 `false` 给用户确认）
`autoInstallOnAppQuit`	已下载的安装包退出时静默安装
`allowDowngrade`	允许降级（默认只升不降，版本按 semver 比较）
`channel`	更新通道（如 `beta`），对应 `beta.yml`
`fullChangelog`	下载完整更新日志
`update-available` / `update-not-available`	版本对比结果回调
`download-progress`	下载进度（bytesPerSecond/percent）
`update-downloaded`	下载完成，可调 `quitAndInstall()`
`error`	任何阶段错误（网络、校验、权限）

平台要点

平台	要求与行为
Windows	NSIS 安装包；差量更新依赖打包生成的 `*.blockmap` 文件，必须随包上传
macOS	需要 `.zip`（dmg 仅首次安装）；必须签名，否则更新失败；`quitAndInstall` 前确保窗口已关闭
Linux	主要支持 AppImage；deb/rpm 走系统包管理器自更新，不在本库范围

与 update-electron-app 对比（选型）

	`update-electron-app`	`electron-updater`
更新源	仅 GitHub Releases（经 update.electronjs.org）	多种，含内网静态服务器
接入成本	一行代码	需配置 `publish` + 事件处理
差量更新	无	Windows 有
适用	开源 + GitHub 发布	私有仓库、企业内网、多通道

常见坑

latest.yml 忘记随安装包上传 → 一直 update-not-available
macOS 只发了 dmg 没发 zip → 无法更新
版本号没升（package.json version 不变）→ 清单对比认为无新版
内网服务器未配 CORS/HTTPS → 下载失败，看 error 事件里的具体原因
Windows 差量更新失效 → 检查 blockmap 是否上传、新旧版本是否都启用

实战示例：腾讯云 COS 做更新源

COS 是静态文件服务，天然适配 generic provider。feed 与安装包分目录、清单里 url 改写为绝对地址是常见做法（electron-updater 遇绝对 URL 直接使用）：

bucket/
├── feed/default/
│   ├── latest.yml            # mac 为 latest-mac.yml
│   └── update-policy.json    # 自定义灰度/强更策略（非内置协议）
└── artifacts/default/<version>/
    ├── app-setup.exe
    └── app-setup.exe.blockmap   # 必须随包上传，否则无差量

autoUpdater.setFeedURL({ provider: 'generic', url: 'https://<bucket>.cos.<region>.myqcloud.com/feed/default/' })

要点：

上传顺序：安装包+blockmap → latest.yml → 自定义 policy 文件最后，避免”策略说有新版但下载 404”窗口期
COS 响应默认无 Cache-Control，套 CDN 后清单可能被缓存导致更新延迟，清单类文件建议设 no-cache
update-policy.json（minSupportedVersion/rolloutPercent/blocked）需客户端自实现；灰度判定用 hash(deviceId) % 100 保持稳定
mac 更新必须提供 latest-mac.yml（zip + 签名），缺了则 mac 端永远收不到更新

灰度发布（Staged Rollout）

内置能力：直接在 latest.yml 加 stagingPercentage 字段（0-100）：

version: 1.1.0
sha512: ...
stagingPercentage: 10

注意：实现是概率性的——基于本地持久化的随机 user id 计算桶位，用户量大才准，无服务端配合无法精确控量。

自定义 policy 文件（如 update-policy.json，含 minSupportedVersion/rolloutPercent/blocked）不在协议内，客户端需自行拉取判定：

自定义字段	协议对应
`rolloutPercent`	`stagingPercentage`
`minSupportedVersion` / `blocked`	无，需自实现
`notes`	yml 内置 `releaseNotes`

自定义方案的优势：改策略无需重新生成清单。

zhaoweiguo 的知识库

目录

electron-updater

与官方 autoUpdater 的关系

Feed 协议结构（generic）

快速接入

更新源配置

方式 1：electron-builder 的 `publish` 配置（推荐）

方式 2：运行时动态指定

常用选项与事件

平台要点

与 update-electron-app 对比（选型）

常见坑

实战示例：腾讯云 COS 做更新源

灰度发布（Staged Rollout）

相关

关系图谱

目录

反向链接

zhaoweiguo 的知识库

目录

electron-updater

与官方 autoUpdater 的关系

Feed 协议结构（generic）

快速接入

更新源配置

方式 1：electron-builder 的 publish 配置（推荐）

方式 2：运行时动态指定

常用选项与事件

平台要点

与 update-electron-app 对比（选型）

常见坑

实战示例：腾讯云 COS 做更新源

灰度发布（Staged Rollout）

相关

关系图谱

目录

反向链接

方式 1：electron-builder 的 `publish` 配置（推荐）