Electron Updater API 参考

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

核心方法

notifyAppReady()

确认已成功加载包并防止自动回滚。 复制到剪贴板

await updater.notifyAppReady();

如果在

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

下载(options)

从 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

下一步(options)

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

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

参数：

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

页面：Capgo解决方案营销页面。角色：短UI标签或导航项。位置：解决方案/测试页面.astro。消息键 `solutions_beta_testing_compare_native_tf` (解决方案测试比较本地化)。

设置选项（options）

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

参数:

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

激活包ID

重新加载当前包

await updater.reload();

删除(options)

从存储中删除一个包。

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

参数：

选项	类型	Required	必填
id	描述	Yes	删除的包ID

重置（options）

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

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

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

参数：

选项	类型	Required	必填
toLastSuccessful	描述	No	如果为 true，则重置为最后一次成功的捆绑包而不是内置捆绑包

捆绑包信息

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 }, ...]

获取所有下载的捆绑包

下一次重启时获取的包

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)

Check the server for the latest available version.

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);
}

Returns:

Property	Type	Description
url	string	Download URL (empty if no update)
version	string	可用版本
checksum	字符串	SHA256校验和
sessionKey	字符串	加密会话密钥
error	字符串	检查失败时的错误消息
message	字符串	服务器消息

频道管理

设置渠道(options)

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

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

unsetChannel(options)

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

await updater.unsetChannel();

getChannel()

获取当前频道分配。

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

listChannels()

获取此应用程序的所有可用频道。

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

延迟条件

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

设置多次延迟(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	版本字符串	等待原生应用程序更新

取消延迟()

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

await updater.cancelDelay();

设备识别

getDeviceId()

获取设备的唯一标识符。

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

设置自定义 ID(options)

配置

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

Configuration

设置更新 URL

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

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

注意

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

设置统计 URL

更改统计报告 URL。

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

设置渠道地址（options）

更改渠道管理地址

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

设置App ID（options）

在运行时更改App ID

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

注意

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

getAppId()

获取当前 App ID。

const appId = await updater.getAppId();

调试

调试菜单(setDebugMenu(options))

启用或禁用调试菜单。

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

isDebugMenuEnabled()

检查是否启用调试菜单

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 __CAPGO_KEEP_0__ 参考 用于计划仪表板和 API 操作的 Electron Updater 使用 @API/electron-updater 使用 @capgo/electron-updater 的原生功能 capgo 概述 继续使用 Electron Updater API 参考 对于 API 的实现细节概述 简介 Capgo {0}键 API 键 为 API 的实现细节提供。 Capgo {0}设备 编辑页面