跳转至

autoUpdater

允许应用自动更新自身。

进程：主进程

另请参阅：关于如何在应用中实现更新的详细指南。

autoUpdater 是一个 EventEmitter。

平台说明

目前，仅支持 macOS 和 Windows。Linux 上没有内置的自动更新支持，因此建议使用发行版的包管理器来更新你的应用。

此外，各平台存在一些细微差异：

macOS

在 macOS 上，autoUpdater 模块基于 Squirrel.Mac 构建，这意味着你无需任何特殊配置即可使其工作。对于服务器端要求，你可以阅读 服务器支持。请注意，App Transport Security（ATS）适用于更新过程中发出的所有请求。需要禁用 ATS 的应用可以在其应用的 plist 中添加 NSAllowsArbitraryLoads 键。

[!IMPORTANT] 你的应用必须经过签名，才能在 macOS 上自动更新。这是 Squirrel.Mac 的要求。

更新 ZIP 会流式写入磁盘，而不是保存在内存中。当服务器以 ETag 或 Last-Modified 头响应并支持 Range 请求时，因网络变化、休眠或应用退出而中断的下载，会在下次更新检查时从停止处继续，包括重新启动后；否则它会重新开始。更新条目（更新服务器的响应，或 serverType: 'json' 源中的 updateTo 对象）可以在 url 旁边声明 sha256（十六进制摘要）和 size（字节）；不匹配的下载会在解包前被丢弃，并触发 error。

更新条目还可以携带 delta，这是一个包含 from_version、url、sha256 和 size 的对象，提供来自某个较早构建的二进制补丁。当 from_version 等于正在运行的应用的 CFBundleVersion 时，将下载该补丁而不是 ZIP，将其应用到正在运行的应用副本，并且结果会经过与解包 ZIP 相同的代码签名验证；如果任何步骤失败，则会在同一次检查中下载 ZIP。补丁使用 Sparkle 的 BinaryDelta create 从实际发布的 bundle 生成；有关约束条件，请参阅 Squirrel.Mac 的 README。

Windows

在 Windows 上，autoUpdater 模块会根据应用的打包方式自动选择适当的更新机制：

你无需配置使用哪个更新器；Electron 会自动检测打包格式并使用相应的更新器。

Squirrel.Windows

使用 Squirrel.Windows 构建的应用会触发自定义启动事件，你的 Electron 应用必须处理这些事件，以确保正确初始化和清理。

Squirrel.Windows 应用会在安装后立即以 --squirrel-firstrun 参数启动。在此期间，Squirrel.Windows 会对你的应用获取文件锁，在锁释放之前，autoUpdater 请求将会失败。实际上，这意味着在首次启动后的最初几秒内，你将无法检查更新。你可以通过在 process.argv 包含 --squirrel-firstrun 标志时不检查更新，或为更新检查设置 10 秒超时来规避此问题（更多信息见 electron/electron#7155）。

使用 Squirrel.Windows 生成的安装程序会创建一个带有应用程序用户模型 ID的快捷方式图标，其格式为 com.squirrel.PACKAGE_ID.YOUR_EXE_WITHOUT_DOT_EXE，示例为 com.squirrel.slack.Slack 和 com.squirrel.code.Code。你必须使用 app.setAppUserModelId API 为你的应用设置相同的 ID，否则 Windows 将无法在任务栏中正确固定你的应用。

MSIX 包

当你的应用打包为 MSIX 时，autoUpdater 模块提供额外功能：

  • 在 setFeedURL() 中使用 allowAnyVersion 选项，以允许更新到旧版本（降级）
  • 支持直接的 MSIX 文件链接或 JSON 更新源（类似于 Squirrel.Mac 格式）

事件

autoUpdater 对象会发出以下事件：

事件：'error'

返回：

  • error Error

在更新过程中发生错误时发出。

事件：'checking-for-update'

在开始检查可用更新时发出。

事件：'update-available'

当有可用更新时发出。更新会自动下载。

事件：'update-not-available'

当没有可用更新时发出。

事件：'update-downloaded'

返回：

  • event Event
  • releaseNotes string
  • releaseName string
  • releaseDate Date
  • updateURL string

当更新已下载时发出。

在 Squirrel.Windows 中，只有 releaseName 可用。

[!NOTE] 严格来说，无需处理此事件。成功下载的更新仍会在应用下次启动时应用。

事件：'before-quit-for-update'

  • options 对象
  • url 字符串 - 更新服务器 URL。对于 Windows MSIX，这可以是 MSIX 文件的直接链接（例如 https://example.com/update.msix），也可以是返回更新信息的 JSON 端点（更多信息请参见 Squirrel.Mac README）。
  • headers Record\<string, string>（可选） macOS - HTTP 请求头。
  • serverType 字符串（可选） macOS - 可以是 json 或 default，更多信息请参见 Squirrel.Mac README。
  • allowAnyVersion 布尔值（可选） Windows - 如果为 true，则允许 MSIX 包降级到旧版本。 默认为 false。

设置 url 并初始化自动更新器。

autoUpdater.getFeedURL()

返回 string - 当前更新源 URL。

autoUpdater.checkForUpdates()

询问服务器是否有更新。在使用此 API 之前，必须调用 setFeedURL。

[!NOTE] 如果有可用更新，它将被自动下载。 两次调用 autoUpdater.checkForUpdates() 会下载两次更新。

autoUpdater.quitAndInstall()

在更新下载完成后，重启应用并安装更新。 它只应在 update-downloaded 发出后调用。

在内部，调用 autoUpdater.quitAndInstall() 会先关闭所有应用窗口，并在所有窗口关闭后自动调用 app.quit()。

[!NOTE] 严格来说，调用此函数并非应用更新所必需， 因为成功下载的更新总会在应用下次启动时应用。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 el/electron