@imckl/electron-updater-enhanced

基于 electron-updater 的增强封装，为 Electron + Vue 3 + Element Plus 项目提供开箱即用的自动更新功能。

特性

• 开箱即用：简单配置即可启用自动更新
• 强制更新：通过 minimumVersion 机制强制旧版本更新
• 云服务支持：腾讯云 COS、阿里云 OSS 等
• Vue 3 集成：Composable API + Element Plus 弹窗
• Changelog 集成：自动显示版本更新内容
• 完整类型：TypeScript 类型支持

安装

npm install @imckl/electron-updater-enhanced electron-updater

快速开始

1. 主进程

// src/main/index.ts
import { app, BrowserWindow } from 'electron'
import { createUpdater, registerUpdaterIpc } from '@imckl/electron-updater-enhanced/main'

const updater = createUpdater({
  serverUrl: 'https://your-bucket.cos.ap-<region>.myqcloud.com/updates/',
  referer: 'https://your-domain.com/',
})

app.on('ready', () => {
  const mainWindow = new BrowserWindow({
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
    },
  })

  // 注册 IPC handlers
  registerUpdaterIpc(updater)

  // 初始化更新器
  updater.init(mainWindow)

  // 生产环境：启动后 3 秒检查更新
  if (app.isPackaged) {
    setTimeout(() => updater.check(), 3000)
  }
})

2. Preload

// src/preload/index.ts
import { exposeUpdaterApi } from '@imckl/electron-updater-enhanced/preload'

exposeUpdaterApi()

⚠️ 重要：Electron preload 运行在沙盒环境，无法直接 require 第三方包。需要配置构建工具将本包打包进 preload。

electron-vite 配置：

// electron.vite.config.ts
export default defineConfig({
  preload: {
    build: {
      // 排除本包，将其打包进 preload
      externalizeDeps: {
        exclude: ['@imckl/electron-updater-enhanced'],
      },
    },
  },
})

3. 渲染进程

<!-- src/renderer/App.vue -->
<script setup lang="ts">
import { useAutoUpdate } from '@imckl/electron-updater-enhanced/renderer'

useAutoUpdate({
  messages: {
    normalTitle: '提示',
    normalContent: '更新已就绪，关闭应用后将自动更新',
    normalConfirm: '我已知晓',
    normalCancel: '立即更新',
    forceTitle: '重要更新',
    forceContent: '检测到重要更新，请保存工作后更新',
    forceConfirm: '立即更新',
    forceLater: '稍后',
    forceExtendHint: (remaining, minutes) =>
      `<br><br>点击「稍后」可延期 ${minutes} 分钟（剩余 ${remaining} 次）`,
  },
  forceUpdate: {
    maxExtends: 2,
    extendMinutes: 5,
  },
})
</script>

4. 类型声明

// src/env.d.ts
import type { ElectronUpdaterApi } from '@imckl/electron-updater-enhanced'

declare global {
  interface Window {
    electronUpdater: ElectronUpdaterApi
  }
}

API

主进程

createUpdater(config)

创建更新器实例。

interface UpdaterConfig {
  serverUrl: string        // 更新服务器 URL（必填）
  referer?: string         // 防盗链 Referer
  changelogUrl?: string    // Changelog URL（默认 serverUrl + 'user-changelog.json'）
  autoDownload?: boolean   // 是否自动下载（默认 false）
  autoInstallOnQuit?: boolean  // 退出时自动安装（默认 true）
  allowDevMode?: boolean   // 允许开发环境测试（默认 false）
}

返回的 Updater 实例：

interface Updater {
  init(window: BrowserWindow): void  // 初始化，绑定主窗口
  check(): void                       // 检查更新
  install(): void                     // 退出并安装
  getChangelog(): Changelog           // 获取本地 Changelog
  getChangelogRemote(): Promise<Changelog>  // 获取远程 Changelog
}

registerUpdaterIpc(updater)

注册 IPC handlers，需要在 app.ready 后调用。

渲染进程

useAutoUpdate(options)

Vue Composable，自动处理更新 UI。

interface AutoUpdateOptions {
  messages: AutoUpdateMessages  // UI 文案（必填）
  forceUpdate?: ForceUpdateConfig | false  // 强制更新配置
  onUpdateAvailable?: (info: UpdateInfo) => void
  onUpdateDownloaded?: (info: UpdateInfo) => void
  onError?: (error: string) => void
}

工具函数

import { compareVersions, isForceUpdateRequired, filterChangelogVersions } from '@imckl/electron-updater-enhanced/renderer'

// 版本比较
compareVersions('1.0.0', '1.0.1')  // -1 (a < b)

// 判断是否需要强制更新
isForceUpdateRequired('0.0.5', '0.0.6')  // true

// 筛选相关版本
filterChangelogVersions(versions, { currentVersion: '0.0.5', newVersion: '0.0.8' })

服务器配置

文件结构

updates/
├── latest.yml              # electron-builder 生成
├── YourApp-Setup-1.0.0.exe # 安装包
└── user-changelog.json     # 更新记录

latest.yml

需要添加 minimumVersion 字段支持强制更新：

version: 1.0.0
minimumVersion: 0.9.0   # 低于此版本强制更新
files:
  - url: YourApp-Setup-1.0.0.exe
    sha512: xxxxx

user-changelog.json

{
  "versions": [
    {
      "version": "1.0.0",
      "date": "2026-01-23",
      "notes": ["新增 XXX 功能", "修复 YYY 问题"]
    }
  ]
}

License

MIT