Electron Updater API 参考

本页面文档了 Electron Updater 所有可用的方法、事件和配置选项。

核心方法

通知应用就绪()

通知应用就绪() 必须在每次应用启动时调用。

await updater.notifyAppReady();

注意

注意 appReadyTimeout 如果在

(默认10秒)，更新将被视为失败，应用将回滚到上一个版本。

从 URL 下载一个包。

const bundle = await updater.download({
  url: 'https://example.com/bundle.zip',
  version: '1.0.1',
  checksum: 'sha256-hash', // Optional but recommended
  sessionKey: '...', // For encrypted bundles
});

参数：

选项	类型	必填	描述
url	string	是	从 URL 下载包的地址
version	string	是	包版本标识符
checksum	string	否	用于验证的SHA256校验和
sessionKey	string	否	会话密钥（用于加密包）

返回值： BundleInfo 包含下一个选项的对象 id, version, status

next(options)

下一次应用重启时加载的包队列。

await updater.next({ id: 'bundle-id' });

参数：

选项	类型	必填	描述
id	字符串	是	包ID

set(options)

立即切换到一个捆绑包并重新加载应用程序。

await updater.set({ id: 'bundle-id' });

参数：

选项	类型	必填	描述
id	字符串	是	激活捆绑包的ID

reload()

手动重新加载当前应用程序的包。

await updater.reload();

delete(options)

从存储中删除一个包。

await updater.delete({ id: 'bundle-id' });

参数：

选项	类型	必填	描述
id	字符串	是	删除的 Bundle ID

reset(options)

重置为内置版本或最后一次成功的 Bundle。

// Reset to builtin
await updater.reset({ toLastSuccessful: false });

// Reset to last successful bundle
await updater.reset({ toLastSuccessful: true });

参数：

选项	类型	必填	描述
toLastSuccessful	布尔值	否	如果为真，则重置为最后一次成功的捆绑包而不是内置的

捆绑包信息

current()

获取当前捆绑包和原生版本的信息。

const info = await updater.current();
// { bundle: { id, version, status }, native: '1.0.0' }

list(options)

列出所有下载的捆绑包。

const bundles = await updater.list();
// [{ id, version, status, downloaded, checksum }, ...]

getNextBundle()

获取下一次重启时的包

const next = await updater.getNextBundle();
// { id, version, status } or null

getFailedUpdate()

获取最后一次失败的更新信息（用于调试回滚）

const failed = await updater.getFailedUpdate();
// { id, version, reason } or null

getBuiltinVersion()

获取与应用程序二进制文件一起发布的版本

const version = await updater.getBuiltinVersion();
// '1.0.0'

检查更新

getLatest(options)

检查服务器上可用的最新版本。

const latest = await updater.getLatest();

if (latest.url && !latest.error) {
  // Update available
  console.log('New version:', latest.version);
  console.log('Download URL:', latest.url);
} else if (latest.error) {
  console.error('Error checking updates:', latest.error);
}

返回:

属性	类型	描述
url	字符串	下载地址（无更新时为空）
version	__CAPGO_KEEP_0__	可用版本
checksum	__CAPGO_KEEP_0__	SHA256校验和
sessionKey	__CAPGO_KEEP_0__	加密会话密钥
error	__CAPGO_KEEP_0__	检查失败时的错误消息
message	__CAPGO_KEEP_0__	服务器消息

频道管理

设置频道（options）

将设备分配到特定的频道。

await updater.setChannel({ channel: 'beta' });

取消频道（options）

移除频道分配并使用默认值。

await updater.unsetChannel();

获取频道（）

获取当前频道分配。

const channel = await updater.getChannel();
// { channel: 'production', status: 'set' }

listChannels()

获取所有可用的渠道。

const channels = await updater.listChannels();
// ['production', 'beta', 'staging']

延迟条件

控制下载更新的应用时间。

setMultiDelay(options)

设置更新应用之前必须满足的条件。

// Wait for app to be backgrounded
await updater.setMultiDelay({
  delayConditions: [{ kind: 'background' }]
});

// Wait until specific date
await updater.setMultiDelay({
  delayConditions: [{ kind: 'date', value: '2024-12-25T00:00:00Z' }]
});

// Wait for app to be killed and restarted
await updater.setMultiDelay({
  delayConditions: [{ kind: 'kill' }]
});

// Multiple conditions (all must be met)
await updater.setMultiDelay({
  delayConditions: [
    { kind: 'background' },
    { kind: 'date', value: '2024-12-25T00:00:00Z' }
  ]
});

延迟条件类型:

类型	值	描述
background	可选延迟时间（毫秒）	等待应用程序进入后台
kill	-	等待应用程序被杀死并重新启动
date	ISO 日期字符串	等待特定日期/时间
nativeVersion	版本字符串	等待原生应用程序更新

cancelDelay()

立即清除延迟条件并在下一次检查时立即应用更新。

await updater.cancelDelay();

设备识别

获取设备ID

复制到剪贴板

const deviceId = await updater.getDeviceId();
// 'uuid-xxxx-xxxx-xxxx'

设置设备的自定义标识符（用于分析）

设备识别

await updater.setCustomId({ customId: 'user-123' });

配置

设置更新 URL

在运行时更改更新服务器 URL。

await updater.setUpdateUrl({ url: 'https://my-server.com/updates' });

注意

需要 allowModifyUrl: true 在构造函数选项中

设置统计 URL

修改统计报告URL。

await updater.setStatsUrl({ url: 'https://my-server.com/stats' });

setChannelUrl(options)

修改渠道管理URL。

await updater.setChannelUrl({ url: 'https://my-server.com/channel' });

setAppId(options)

在运行时修改App ID。

await updater.setAppId({ appId: 'com.example.newapp' });

注意

需要 allowModifyAppId: true 在构造函数选项中。

获取App ID()

获取当前App ID。

const appId = await updater.getAppId();

调试

设置调试菜单（options）

启用或禁用调试菜单。

await updater.setDebugMenu({ enabled: true });

是否启用调试菜单()

检查是否启用了调试菜单。

const enabled = await updater.isDebugMenuEnabled();

事件

使用以下事件监听更新 addListener:

updater.addListener('eventName', (event) => {
  // Handle event
});

可用事件

事件	事件载荷	简介
download	{ percent, status }	下载进度更新
updateAvailable	{ bundle }	新版本可用
noNeedUpdate	{ message }	已是最新
downloadComplete	{ bundle }	下载成功
downloadFailed	{ bundle, error }	下载失败
breakingAvailable	{ bundle }	不兼容的更新可用（需要原生更新）
updateFailed	{ bundle, reason }	更新安装失败
appReloaded	{}	应用已重新加载
appReady	{}	notifyAppReady() 被调用

示例：全事件处理

// Progress tracking
updater.addListener('download', (event) => {
  updateProgressBar(event.percent);
});

// Update available notification
updater.addListener('updateAvailable', (event) => {
  showNotification(`Update ${event.bundle.version} available!`);
});

// Handle completion
updater.addListener('downloadComplete', async (event) => {
  // Queue for next restart
  await updater.next({ id: event.bundle.id });
  showNotification('Update will apply on next restart');
});

// Handle failures
updater.addListener('updateFailed', (event) => {
  console.error('Update failed:', event.reason);
  reportError(event);
});

构造函数选项

Electron Updater 的完整配置选项 ElectronUpdater:

const updater = new ElectronUpdater({
  // Required
  appId: 'com.example.app',

  // Version override
  version: '1.0.0', // Override builtin version detection

  // Server URLs
  updateUrl: 'https://plugin.capgo.app/updates',
  channelUrl: 'https://plugin.capgo.app/channel_self',
  statsUrl: 'https://plugin.capgo.app/stats',

  // Behavior
  autoUpdate: true,           // Enable automatic update checks
  appReadyTimeout: 10000,     // Milliseconds before rollback (default: 10000)
  autoDeleteFailed: true,     // Auto-delete failed bundles
  autoDeletePrevious: true,   // Auto-delete old bundles
  resetWhenUpdate: true,      // Reset to builtin on native update

  // Channels
  defaultChannel: 'production',

  // Direct Update Mode
  directUpdate: false,        // 'atInstall' | 'onLaunch' | 'always' | false

  // Security
  publicKey: '...',           // RSA public key for E2E encryption

  // Dynamic Configuration
  allowModifyUrl: false,      // Allow runtime URL changes
  allowModifyAppId: false,    // Allow runtime App ID changes
  persistCustomId: false,     // Persist custom ID across updates
  persistModifyUrl: false,    // Persist URL changes

  // Debug
  debugMenu: false,           // Enable debug menu (Ctrl+Shift+D)
  disableJSLogging: false,    // Disable console logs

  // Periodic Updates
  periodCheckDelay: 0,        // Seconds between auto-checks (0 = disabled, min 600)
});

从 Electron Updater API 开始继续：参考

如果您正在使用 Electron Updater API 参考 来规划仪表板和 API 操作，连接它与 使用 @capgo/electron-updater 为 Using @capgo/electron-updater 中的本机功能 API 简介 API 实现细节 介绍 __CAPGO_KEEP_0__ 实现细节 API 键 API 实现细节 __CAPGO_KEEP_0__ 实现细节 设备