Skip to main content

autoUpdater

使应用能够自动更新。

¥Enable apps to automatically update themselves.

进程：主进程

¥Process: Main

也可以看看：有关如何在应用中实现更新的详细指南。

¥See also: A detailed guide about how to implement updates in your application.

autoUpdater 是 EventEmitter。

¥autoUpdater is an EventEmitter.

平台公告​

¥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 模块基于 Squirrel.Mac 构建，这意味着你不需要任何特殊设置即可使其工作。对于服务器端的需求，可以阅读 服务器支持。请注意，应用传输安全 (ATS) 适用于更新过程中提出的所有请求。需要禁用 ATS 的应用可以将 NSAllowsArbitraryLoads 密钥添加到其应用的 plist 中。

¥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.

注意：你的应用必须经过签名才能在 macOS 上自动更新。这是 Squirrel.Mac 的要求。

¥Note: Your application must be signed for automatic updates on macOS. This is a requirement of Squirrel.Mac.

Windows​

在 Windows 上，你必须先将应用安装到用户的计算机中才能使用 autoUpdater，因此建议你使用 electron-winstaller、Electron Forge 或 grunt-electron-installer 包来生成 Windows 安装程序。

¥On Windows, you have to install your app into a user's machine before you can use the autoUpdater, so it is recommended that you use the electron-winstaller, Electron Forge or the grunt-electron-installer package to generate a Windows installer.

使用 electron-winstaller 或 Electron Forge 时，请确保不要尝试更新应用 第一次运行时（另请参阅 本期了解更多信息）。还建议使用 electron-squirrel-startup 获取应用的桌面快捷方式。

¥When using electron-winstaller or Electron Forge make sure you do not try to update your app the first time it runs (Also see this issue for more info). It's also recommended to use electron-squirrel-startup to get desktop shortcuts for your app.

使用 Squirrel 生成的安装程序将创建一个带有 应用用户模型 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 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.

与 Squirrel.Mac 一样，Windows 可以在 S3 或任何其他静态文件主机上托管更新。你可以阅读 Squirrel.Windows 的文档以获取有关 Squirrel.Windows 工作原理的更多详细信息。

¥Like Squirrel.Mac, Windows can host updates on S3 or any other static file host. You can read the documents of Squirrel.Windows to get more details about how Squirrel.Windows works.

事件​

¥Events

autoUpdater 对象发出以下事件：

¥The autoUpdater object emits the following events:

事件：'error'​

¥Event: 'error'

返回：

¥Returns:

  • error 错误

    ¥error Error

更新时出现错误时发出。

¥Emitted when there is an error while updating.

事件：'checking-for-update'​

¥Event: 'checking-for-update'

检查更新是否已开始时发出。

¥Emitted when checking if an update has started.

事件：'update-available'​

¥Event: 'update-available'

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

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

事件：'update-not-available'​

¥Event: 'update-not-available'

当没有可用更新时发出。

¥Emitted when there is no available update.

事件：'update-downloaded'​

¥Event: 'update-downloaded'

返回：

¥Returns:

  • event 事件

    ¥event Event

  • releaseNotes 字符串

    ¥releaseNotes string

  • releaseName 字符串

    ¥releaseName string

  • releaseDate 日期

    ¥releaseDate Date

  • updateURL 字符串

    ¥updateURL string

下载更新后发出。

¥Emitted when an update has been downloaded.

在 Windows 上仅 releaseName 可用。

¥On Windows only releaseName is available.

注意：处理此事件并不是绝对必要的。成功下载的更新仍将在下次应用启动时应用。

¥Note: It is not strictly necessary to handle this event. A successfully downloaded update will still be applied the next time the application starts.

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

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

该事件在用户调用 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)​

  • options 对象

    ¥options Object

    • url 字符串

      ¥url string

    • headers Record<string, string> (optional) macOS - HTTP 请求标头。

      ¥headers Record<string, string> (optional) macOS - HTTP request headers.

    • serverType 字符串（可选）macOS - 可以是 json 或 default，请参阅 Squirrel.Mac 自述文件以获取更多信息。

      ¥serverType string (optional) macOS - Can be json or default, see the Squirrel.Mac README for more information.

设置 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.

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

¥Note: If an update is available it will be downloaded automatically. Calling autoUpdater.checkForUpdates() twice will download the update two times.

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: It is not strictly necessary to call this function to apply an update, as a successfully downloaded update will always be applied the next time the application starts.