Skip to main content

autoUpdater

允许应用自动更新。

进程：主进程

🌐 Process: Main

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

autoUpdater 是一个 事件触发器。

平台公告​

🌐 Platform Notices

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

🌐 Currently, only macOS and Windows are supported. There is no built-in support for auto-updater on Linux, so it is recommended to use the distribution's package manager to update your app.

此外，每个平台上还存在一些细微的差异：

🌐 In addition, there are some subtle differences on each platform:

macOS​

在 macOS 上，autoUpdater 模块是基于 松鼠.麦克 构建的，这意味着你不需要任何特殊设置即可使其工作。对于服务器端的需求，你可以阅读 服务器支持。请注意，应用传输安全（ATS）适用于更新进程中发出的所有请求。需要禁用 ATS 的应用可以在其应用的 plist 中添加 NSAllowsArbitraryLoads 键。

🌐 On macOS, the autoUpdater module is built upon Squirrel.Mac, meaning you don't need any special setup to make it work. For server-side requirements, you can read Server Support. Note that App Transport Security (ATS) applies to all requests made as part of the update process. Apps that need to disable ATS can add the NSAllowsArbitraryLoads key to their app's plist.

info

你的应用必须签名才能在 macOS 上进行自动更新。 这是 Squirrel.Mac 的要求。

Windows​

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

🌐 On Windows, the autoUpdater module automatically selects the appropriate update mechanism based on how your app is packaged:

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

🌐 You don't need to configure which updater to use; Electron automatically detects the packaging format and uses the appropriate one.

Squirrel.Windows​

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

🌐 Apps built with Squirrel.Windows will trigger custom launch events that must be handled by your Electron application to ensure proper setup and teardown.

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

🌐 Squirrel.Windows apps will launch with the --squirrel-firstrun argument immediately after installation. During this time, Squirrel.Windows will obtain a file lock on your app, and autoUpdater requests will fail until the lock is released. In practice, this means that you won't be able to check for updates on first launch for the first few seconds. You can work around this by not checking for updates when process.argv contains the --squirrel-firstrun flag or by setting a 10-second timeout on your update checks (see electron/electron#7155 for more information).

使用 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 将无法正确将你的应用固定到任务栏。

🌐 The installer generated with Squirrel.Windows will create a shortcut icon with an Application User Model ID in the format of com.squirrel.PACKAGE_ID.YOUR_EXE_WITHOUT_DOT_EXE, examples are com.squirrel.slack.Slack and com.squirrel.code.Code. You have to use the same ID for your app with app.setAppUserModelId API, otherwise Windows will not be able to pin your app properly in task bar.

MSIX 包​

🌐 MSIX Packages

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

🌐 When your app is packaged as an MSIX, the autoUpdater module provides additional functionality:

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

事件​

🌐 Events

autoUpdater 对象会触发以下事件：

🌐 The autoUpdater object emits the following events:

Event: 'error'​

返回：

🌐 Returns:

  • error 错误

更新时出现错误时发出。

🌐 Emitted when there is an error while updating.

Event: 'checking-for-update'​

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

🌐 Emitted when checking for an available update has started.

Event: 'update-available'​

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

🌐 Emitted when there is an available update. The update is downloaded automatically.

Event: 'update-not-available'​

当没有可用更新时发出。

🌐 Emitted when there is no available update.

Event: 'update-downloaded'​

返回：

🌐 Returns:

  • event 活动
  • releaseNotes 字符串
  • releaseName 字符串
  • releaseDate 日期
  • updateURL 字符串

下载更新后发出。

🌐 Emitted when an update has been downloaded.

使用 Squirrel.Windows 只有 releaseName 可用。

🌐 With Squirrel.Windows only releaseName is available.

note

处理此事件并非严格必要。成功下载的更新仍将在下次应用启动时应用。

Event: 'before-quit-for-update'​

History
Version(s)Changes
None
API ADDED

在用户调用 quitAndInstall() 后会触发此事件。

🌐 This event is emitted after a user calls quitAndInstall().

当调用此 API 时，在所有窗口关闭之前不会触发 before-quit 事件。因此，如果你希望在进程退出时在窗口关闭之前执行某些操作，应监听此事件，同时也要监听 before-quit。

🌐 When this API is called, the before-quit event is not emitted before all windows are closed. As a result you should listen to this event if you wish to perform actions before the windows are closed while a process is quitting, as well as listening to before-quit.

方法​

🌐 Methods

autoUpdater 对象具有以下方法：

🌐 The autoUpdater object has the following methods:

autoUpdater.setFeedURL(options)​

History
Version(s)Changes
None

Added headers as a second parameter.

None

Changed API to accept a single options argument (contains url, headers, and serverType properties).

  • options 对象
    • url 字符串 - 更新服务器的 URL。对于 Windows MSIX，这可以是指向 MSIX 文件的直接链接（例如 https://example.com/update.msix）或返回更新信息的 JSON 接口（有关更多信息，请参阅 松鼠.麦克 的自述文件）。
    • headers Record<string, string> （可选）macOS - HTTP 请求头。
    • serverType 字符串（可选）macOS - 可以是 json 或 default，详情请参阅 松鼠.麦克 README。
    • allowAnyVersion 布尔值（可选） Windows - 如果为 true，允许 MSIX 包降级到较旧版本。 默认为 false。

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

🌐 Sets the url and initialize the auto updater.

autoUpdater.getFeedURL()​

返回 string - 当前更新源 URL。

🌐 Returns string - The current update feed URL.

autoUpdater.checkForUpdates()​

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

🌐 Asks the server whether there is an update. You must call setFeedURL before using this API.

note

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

autoUpdater.quitAndInstall()​

重新启动应用并在更新下载完成后安装更新。它应仅在 update-downloaded 事件触发后调用。

🌐 Restarts the app and installs the update after it has been downloaded. It should only be called after update-downloaded has been emitted.

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

🌐 Under the hood calling autoUpdater.quitAndInstall() will close all application windows first, and automatically call app.quit() after all windows have been closed.

note

严格来说，不必调用此函数来应用更新，因为已成功下载的更新将在应用下次启动时自动应用。