Electron Updater 入门指南

本指南将带你完成配置 @capgo/electron-updater 以在 Electron 应用中实现 JavaScript/HTML/CSS 的 Live Update。

提示

已经在 Capacitor 中使用 Capgo 了吗？Electron Updater 使用相同的 Capgo Cloud 后端，因此你可以在同一个 dashboard 中管理移动端和桌面端应用。

前提条件

• Electron 20.0.0 或更高版本
• Node.js 18 或更高版本
• 一个 Capgo 账号（请前往注册 capgo.app)

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/electron-updater` plugin in my project.

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

1. 安装软件包：

   npm install @capgo/electron-updater

2. 从 Capgo dashboard 获取您的 App ID。如果您尚未创建应用，请运行：

   npx @capgo/cli@latest init

快速入门

import { requireUpdater } from '@capgo/electron-updater/renderer';

const updater = requireUpdater();
await updater.notifyAppReady();

常见坑点

• 调用 notifyAppReady() 在启动初期——即配置的超时时间内——在缓慢的 UI 初始化之前。
• 确保与主进程中的 Capgo 签名一致。
• 在发布前设置好更新 channel。

配置

Electron Updater 需要在三个地方进行配置：主进程 (main process)、预加载脚本 (preload script) 和渲染进程 (renderer process)。

主进程

main.ts

import { app, BrowserWindow } from 'electron';
import * as path from 'path';
import {
  ElectronUpdater,
  setupIPCHandlers,
  setupEventForwarding,
} from '@capgo/electron-updater';

// Create updater instance with your Capgo App ID
const updater = new ElectronUpdater({
  appId: 'YOUR_CAPGO_APP_ID', // e.g., 'com.example.myapp'
  autoUpdate: true,
});

app.whenReady().then(async () => {
  const mainWindow = new BrowserWindow({
    width: 1200,
    height: 800,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,
    },
  });

  // Initialize updater with window and builtin path
  const builtinPath = path.join(__dirname, 'www/index.html');
  await updater.initialize(mainWindow, builtinPath);

  // Setup IPC communication between main and renderer
  setupIPCHandlers(updater);
  setupEventForwarding(updater, mainWindow);

  // Load the current bundle (either builtin or downloaded update)
  await mainWindow.loadFile(updater.getCurrentBundlePath());
});

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

预加载脚本

preload.ts

import { exposeUpdaterAPI } from '@capgo/electron-updater/preload';

// Expose the updater API to the renderer process
exposeUpdaterAPI();

渲染进程

// renderer.ts (or in your app's entry point)
import { requireUpdater } from '@capgo/electron-updater/renderer';

const updater = requireUpdater();

// CRITICAL: Call this on every app launch!
// This confirms the bundle loaded successfully and prevents rollback
await updater.notifyAppReady();

console.log('App ready, current bundle:', await updater.current());

注意

您 必须 调用 notifyAppReady() 在应用启动后的 10 秒内（可通过以下方式配置 appReadyTimeout）。如果未调用，更新程序将认为更新失败，并回滚至上一个版本。

检查更新

使用 autoUpdate: true，更新程序会自动检查更新。你也可以手动触发检查：

// Check for updates manually
const latest = await updater.getLatest();

if (latest.url && !latest.error) {
  console.log('Update available:', latest.version);

  // Download the update
  const bundle = await updater.download({
    url: latest.url,
    version: latest.version,
    checksum: latest.checksum,
  });

  console.log('Downloaded bundle:', bundle.id);

  // Option 1: Queue for next restart
  await updater.next({ id: bundle.id });

  // Option 2: Apply immediately and reload
  // await updater.set({ id: bundle.id });
}

监听事件

通过事件追踪更新进度和状态：

// Download progress
updater.addListener('download', (event) => {
  console.log(`Download progress: ${event.percent}%`);
});

// Update available
updater.addListener('updateAvailable', (event) => {
  console.log('New version available:', event.bundle.version);
});

// Download completed
updater.addListener('downloadComplete', (event) => {
  console.log('Download finished:', event.bundle.id);
});

// Update failed
updater.addListener('updateFailed', (event) => {
  console.error('Update failed:', event.bundle.version);
});

部署更新

使用 Capgo CLI 上传更新：

# Build your app
npm run build

# Upload to Capgo
npx @capgo/cli@latest bundle upload --channel=production

你的 Electron 应用将在下次检查时自动检测并下载新的 bundle。

调试菜单

在开发期间启用调试菜单：

const updater = new ElectronUpdater({
  appId: 'YOUR_CAPGO_APP_ID',
  debugMenu: true, // Enable debug menu
});

按下 Ctrl+Shift+D (或 Cmd+Shift+D 在 Mac 上) 以打开调试菜单并：

• 查看当前 bundle 信息
• 在可用 bundle 之间切换
• 重置为内置版本
• 查看设备和 channel 信息

配置选项

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

  // Server URLs (defaults to Capgo Cloud)
  updateUrl: 'https://plugin.capgo.app/updates',
  channelUrl: 'https://plugin.capgo.app/channel_self',
  statsUrl: 'https://plugin.capgo.app/stats',

  // Behavior
  autoUpdate: true,           // Enable auto-updates
  appReadyTimeout: 10000,     // MS before rollback (default: 10s)
  autoDeleteFailed: true,     // Delete failed bundles
  autoDeletePrevious: true,   // Delete old bundles after successful update

  // Channels
  defaultChannel: 'production',

  // Security
  publicKey: '...',           // For end-to-end encryption

  // Debug
  debugMenu: false,           // Enable debug menu
  disableJSLogging: false,    // Disable console logs

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

下一步

• API 参考 - 探索所有可用方法
• 通道 - 了解部署渠道
• 回滚 - 了解回滚保护机制

继续学习 Electron Updater 入门指南

如果你正在使用 Electron Updater 入门指南 要规划原生插件工作，请将其与 使用 @capgo/electron-updater 在“使用 @capgo/electron-updater”中实现原生能力， Capgo 插件目录 查看 Capgo 插件目录中的产品工作流， Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节， 添加或更新插件 关于“添加或更新插件”中的实现细节，以及 Ionic Enterprise 插件替代方案 关于“Ionic Enterprise 插件替代方案”中的产品工作流。