自动更新

自动更新通过 electron-updater 包启用。理想情况下，自动更新配置为在 CI 管道中运行，以自动配置新版本。有关如何为自动化部署配置本地或 CI 环境的信息，请参阅发布配置。

自动更新的工作方式如下

您配置包以构建发布元数据 (latest.yml)
Electron builder 将实际的发布目标和元数据文件上传到配置的目标（通用服务器除外，您必须手动上传）
您配置 Electron 应用程序以使用自动更新，该更新查询发布服务器以查找可能的新版本

阅读本指南的其余部分以配置所有内容。

macOS 上需要代码签名

macOS 应用程序必须签名才能使自动更新工作。

可自动更新的目标¶

macOS：DMG。
Linux：AppImage、DEB、Pacman（beta 版）和 RPM。
Windows：NSIS。

所有这些目标都是默认的，不需要自定义配置。（虽然可以传入额外的配置，例如请求标头。）

信息

不支持 Squirrel.Windows。 如果您使用默认的 NSIS 目标，则 Windows 上支持简化的自动更新，但 Squirrel.Windows 不支持。您可以轻松迁移到 NSIS。
macOS 的 zip 目标是必需的，对于 Squirrel.Mac 也是如此，否则无法创建 latest-mac.yml，这将导致 autoUpdater 错误。macOS 的默认目标是 dmg+zip，因此无需显式指定目标。

electron-updater 和内置 autoUpdater 之间的区别¶

与 Electron 的内置 auto-updater 相比，electron-updater 包提供了不同的功能。以下是区别

不需要专用发布服务器。
代码签名验证不仅在 macOS 上，而且在 Windows 上也是如此。
所有必需的元数据文件和工件都会自动生成和发布。
所有平台都支持下载进度和分阶段发布。
开箱即用地支持不同的提供商：（GitHub Releases、Amazon S3、DigitalOcean Spaces、Keygen 和通用 HTTP(s) 服务器）。
您只需要 2 行代码即可使其工作。

快速设置指南¶

安装 electron-updater 作为应用程序依赖项。
根据您要托管发布文件的位置，配置publish选项。
构建您的应用程序并检查构建目录是否包含构建应用程序旁边的元数据 .yml 文件。对于大多数发布目标，构建步骤还将上传文件，但通用服务器选项除外，您必须手动上传构建的版本和元数据。

使用 electron-updater 中的 autoUpdater 而不是 electron

CommonJS

const { autoUpdater } = require("electron-updater")

ESM

import { autoUpdater } from "electron-updater"

TypeScript

import electronUpdater, { type AppUpdater } from 'electron-updater';

export function getAutoUpdater(): AppUpdater {
   // Using destructuring to access autoUpdater due to the CommonJS module of 'electron-updater'.
   // It is a workaround for ESM compatibility issues, see https://github.com/electron-userland/electron-builder/issues/7976.
   const { autoUpdater } = electronUpdater;
   return autoUpdater;
}

调用 autoUpdater.checkForUpdatesAndNotify()。或者，如果您需要自定义行为，请实现 electron-updater 事件，请查看下面的示例。

注意

不要调用 setFeedURL。 electron-builder 会在构建时自动为您在 resources 中创建 app-update.yml 文件（此文件是内部文件，您无需了解它）。

示例¶

使用系统通知的 TypeScript 示例

import { autoUpdater } from "electron-updater"

export default class AppUpdater {
  constructor() {
    const log = require("electron-log")
    log.transports.file.level = "debug"
    autoUpdater.logger = log
    autoUpdater.checkForUpdatesAndNotify()
  }
}

完整示例，展示如何使用。
通过菜单封装手动更新。

直接实例化 updater 的自定义选项¶

如果您想要更多地控制 updater 配置（例如，用于授权目的的请求标头），您可以直接实例化 updater。

import { NsisUpdater } from "electron-updater"
// Or MacUpdater, AppImageUpdater

export default class AppUpdater {
    constructor() {
        const options = {
            requestHeaders: {
                // Any request headers to include here
            },
            provider: 'generic',
            url: 'https://example.com/auto-updates'
        }

        const autoUpdater = new NsisUpdater(options)
        autoUpdater.addAuthHeader(`Bearer ${token}`)
        autoUpdater.checkForUpdatesAndNotify()
    }
}

调试¶

您无需监听所有事件即可了解哪里出了问题。只需设置 logger。electron-log 是推荐的（这是一个额外的依赖项，您可以根据需要安装）。

autoUpdater.logger = require("electron-log")
autoUpdater.logger.transports.file.level = "info"

请注意，为了开发/测试更新的 UI/UX 而无需打包应用程序，您需要在项目的根目录中创建一个名为 dev-app-update.yml 的文件，该文件与 electron-builder 配置中的 publish 设置匹配（但在 yaml 格式中）。但不建议这样做，最好为已安装的应用程序测试自动更新（尤其是在 Windows 上）。建议使用 Minio 作为本地服务器来测试更新。

兼容性¶

生成的元数据文件格式会不时更改，但兼容性保持到版本 1。如果您启动一个新项目，建议将 electronUpdaterCompatibility 设置为当前最新的格式版本（>= 2.16）。

选项 electronUpdaterCompatibility 设置 electron-updater 兼容性 semver 范围。可以为每个平台指定。

例如 >= 2.16，>=1.0.0。默认为 >=2.15

1.0.0 latest-mac.json
2.15.0 path
2.16.0 files

分阶段发布¶

分阶段发布允许您将最新版本的应用程序分发给一部分用户，您可以随着时间的推移增加这部分用户，类似于 Google Play 等平台上的发布。

分阶段发布通过手动编辑 latest.yml / latest-mac.yml（频道更新信息文件）来控制。

version: 1.1.0
path: TestApp Setup 1.1.0.exe
sha512: Dj51I0q8aPQ3ioaz9LMqGYujAYRbDNblAQbodDRXAMxmY6hsHqEl3F6SvhfJj5oPhcqdX1ldsgEvfMNXGUXBIw==
stagingPercentage: 10

更新将发布给 10% 的用户群。

如果您想撤回分阶段发布，因为它运行不佳，您必须将版本号增加到高于损坏的版本。因为您的一些用户将使用损坏的 1.0.1 版本，所以发布新的 1.0.1 版本将导致他们停留在损坏的版本上。

额外生成和上传的文件¶

latest.yml（macOS 为 latest-mac.yml，Linux 为 latest-linux.yml）将为除 bintray 之外的所有提供商生成和上传（因为不需要，bintray 不使用 latest.yml）。

私有 GitHub 更新仓库¶

您可以通过设置 GH_TOKEN 环境变量（在用户机器上）和 private 选项，将私有仓库用于 electron-updater 的更新。如果设置了 GH_TOKEN，electron-updater 将使用 GitHub API 进行更新，从而允许私有仓库工作。

警告

私有 GitHub 提供商仅适用于非常特殊的情况 — 不适用于所有用户，也不适合所有用户。

注意

GitHub API 目前的速率限制为每个用户每小时 5000 个请求。一次更新检查最多使用 3 个请求。

事件¶

autoUpdater 对象发出以下事件

事件：`error`¶

error 错误

更新时发生错误时发出。

事件：`checking-for-update`¶

在检查更新是否已启动时发出。

事件：`update-available`¶

info UpdateInfo（对于通用和 github 提供商）| VersionInfo（对于 Bintray 提供商）

当有可用更新时发出。如果 autoDownload 为 true，则会自动下载更新。

事件：`update-not-available`¶

当没有可用更新时发出。

info UpdateInfo（对于通用和 github 提供商）| VersionInfo（对于 Bintray 提供商）

事件：`download-progress`¶

progress ProgressInfo
bytesPerSecond
percent
total
transferred

在进度时发出。

事件：`update-downloaded`¶

info UpdateInfo — 对于通用和 github 提供商。 VersionInfo 对于 Bintray 提供商。

UpdateInfo¶

Electron-Builder / electron-updater / UpdateInfo

扩展自¶

UpdateDownloadedEvent

属性¶

files¶

readonly files: UpdateFileInfo[]

minimumSystemVersion?¶

readonly optional minimumSystemVersion: string

应用程序运行所需的最低系统版本。示例值：macOS 23.1.0，Windows 10.0.22631。与 os.release() 值相同，这是一个内核版本。

path¶

readonly path: string

已弃用¶

releaseDate¶

releaseDate: string

发布日期。

releaseName?¶

optional releaseName: null | string

发布名称。

releaseNotes?¶

optional releaseNotes: null | string | ReleaseNoteInfo[]

发行说明。如果 updater.fullChangelog 设置为 true，则为列表，否则为 string。

sha512¶

readonly sha512: string

已弃用¶

stagingPercentage?¶

readonly optional stagingPercentage: number

分阶段发布百分比，0-100。

version¶

readonly version: string

版本。

自动更新

可自动更新的目标¶

electron-updater 和内置 autoUpdater 之间的区别¶

快速设置指南¶

示例¶

直接实例化 updater 的自定义选项¶

调试¶

兼容性¶

分阶段发布¶

额外生成和上传的文件¶

私有 GitHub 更新仓库¶

事件¶

事件：error¶

事件：checking-for-update¶

事件：update-available¶

事件：update-not-available¶

事件：download-progress¶

事件：update-downloaded¶

UpdateInfo¶

扩展自¶

属性¶

files¶

minimumSystemVersion?¶

path¶

已弃用¶

releaseDate¶

releaseName?¶

releaseNotes?¶

sha512¶

已弃用¶

stagingPercentage?¶

version¶

事件：`error`¶

事件：`checking-for-update`¶

事件：`update-available`¶

事件：`update-not-available`¶

事件：`download-progress`¶

事件：`update-downloaded`¶