electron-updater + 腾讯云 COS 实战教程（Windows）

目标：从零完成一次完整的自动更新闭环——打包 v1.0.0 → 上传 COS → Windows 安装 → 发 v1.1.0 → 旧版应用自动发现、下载、安装新版。

配套 demo 源码：raw/repos/electron-updater-demo/。原理与选项速查见 electron-updater。

原理（1 分钟）

打包时：electron-builder 生成 安装包 + .blockmap + latest.yml
发布时：三者上传到 COS 同一目录（即 generic feed）
运行时：应用请求 <feedURL>/latest.yml → 比较 version → 下载 exe → 校验 sha512 → quitAndInstall

准备工作

项	要求
Node.js	LTS 版（`node -v` 确认）
测试机	一台 Windows 机器（安装包只能在 Windows 安装运行）
构建机	Windows 或 macOS 均可（macOS 可交叉构建 win NSIS，demo 用默认图标无需 wine）
COS bucket	已创建；记下访问域名，形如 `https://<bucket>-<appid>.cos.<region>.myqcloud.com`
读写权限	建议「公有读私有写」，否则客户端匿名下载会 403

约定更新目录：update-demo/（即 feedURL 的路径前缀）。

Step 1：准备示例项目

把 raw/repos/electron-updater-demo/ 拷到你的工作目录，共 6 个文件：

electron-updater-demo/
├── package.json          # scripts + electron-updater 运行时依赖
├── electron-builder.yml  # 打包与发布配置
├── main.js               # 主进程：更新逻辑
├── preload.js            # 安全暴露 IPC
├── index.html            # 界面：版本/状态/进度/安装按钮
└── README.md

Step 2：改两处配置

① electron-builder.yml 的 publish.url 换成你的 COS 地址（末尾斜杠保留）：

publish:
  - provider: generic
    url: https://your-bucket-1250000000.cos.ap-guangzhou.myqcloud.com/update-demo/

该配置打包时写入安装包内的 app-update.yml，改地址必须重新打包。

② package.json 的 version 就是更新比较的版本号（当前 1.0.0）。

其余关键代码位置（对照着读一遍）：

main.js — autoUpdater.autoDownload = false + 五个事件监听 + quitAndInstall()
preload.js — contextBridge 暴露 updater API（符合 06-security-performance 安全模型）
index.html — 渲染进度条与「重启并安装」按钮

Step 3：打包 v1.0.0

npm install
npm run dist        # electron-builder --win，产物在 dist/

国内网络先设镜像（详见 07-environment-variables）：

export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
export ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/

dist/ 下本次需要上传的三个文件：

文件	作用
`UpdaterDemo-1.0.0-setup.exe`	安装包
`UpdaterDemo-1.0.0-setup.exe.blockmap`	Windows 差量更新索引，必须随包上传
`latest.yml`	更新清单（版本 + sha512 + 文件名）

打开 latest.yml 确认 version: 1.0.0、files[0].url 是上面的 exe 文件名。

Step 4：上传 COS

用控制台网页上传最简单：进入 bucket → 创建 update-demo/ 目录 → 上传三个文件。（命令行可用 coscmd：coscmd upload latest.yml update-demo/ 等。）

上传后设置清单不缓存，避免以后发版时读到旧清单：控制台选中 latest.yml → 自定义 Headers → Cache-Control: no-cache。

逐个验证可公网访问（浏览器打开或 curl -I）：

https://<bucket>-<appid>.cos.<region>.myqcloud.com/update-demo/latest.yml
https://<bucket>-<appid>.cos.<region>.myqcloud.com/update-demo/UpdaterDemo-1.0.0-setup.exe

Step 5：Windows 安装 v1.0.0

在 Windows 上下载并运行 UpdaterDemo-1.0.0-setup.exe（demo 未签名，SmartScreen 点「仍要运行」）
启动应用，2 秒后状态显示 「已是最新版本」——说明 feed 通了、清单解析正常
点「检查更新」按钮可随时重查

若显示错误，先看界面报错文本，对照文末排查表。

Step 6：发布 v1.1.0

package.json 的 version 改为 1.1.0（不升版本就不会触发更新）
顺手改一行界面文字（如标题加 v1.1）便于肉眼确认
重新 npm run dist
上传新产物到同一 update-demo/ 目录，顺序很重要：
- 先传 UpdaterDemo-1.1.0-setup.exe + .blockmap
- 最后传 latest.yml（覆盖旧清单）
反了会出现「清单说有新版但 exe 还 404」的窗口期。

Step 7：验证完整更新

在 Windows 上打开已安装的 1.0.0 应用：

点「检查更新」→ 状态变为「发现新版本 1.1.0，开始下载」
出现下载进度百分比
下载完成后点「重启并安装」→ 应用退出，NSIS 静默安装，重新启动
界面显示 当前版本：1.1.0，标题也变了 → 闭环完成

常见问题排查

现象	原因 / 处理
一直「已是最新版本」	版本没升；`publish.url` 与实际上传目录不一致；`latest.yml` 未覆盖成功
`error: net::ERR_NAME_NOT_RESOLVED` 或 403	域名写错；bucket 不是公有读
下载后报 sha512 校验失败	重传了 exe 但没重新生成/上传 `latest.yml`（清单里的哈希是打包时算的）
更新能装但每次都全量下载	`.blockmap` 没上传（不影响更新成功，只是失去差量）
发版后部分机器迟迟不更新	CDN/浏览器缓存了旧清单；清单设 `no-cache`，套 CDN 时对 `.yml` 配不缓存
`npm start` 里看不到更新效果	正常：开发模式无 `app-update.yml`，必须用已安装的打包产物测试
安装时提示权限错误	安装目录权限问题；demo 已设 `oneClick: false` 可选安装目录

下一步

更新通道（beta/灰度 stagingPercentage）、macOS/Linux 差异、事件选项全表 → electron-updater
NSIS 安装包定制（图标/协议注册/静默参数）→ electron-builder
打包安全清单 → 06-security-performance

zhaoweiguo 的知识库

目录