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 的 Squirrel.Windows 制作器 来生成 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 electron-winstaller or Electron Forge's Squirrel.Windows maker to generate a Windows installer.

使用 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.

事件

¥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 记录<字符串，字符串>（可选）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.