npm package: @imckl/electron-updater-enhanced
Description: 基于 electron-updater 的增强封装，支持强制更新，适用于 Vue 3 + Element Plus
Author: imckl
Latest version: 0.0.6

# @imckl/electron-updater-enhanced

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

## 特性

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

## 安装

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

## 快速开始

### 1. 主进程

```typescript
// 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

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

exposeUpdaterApi()
```

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

**electron-vite 配置**：

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

### 3. 渲染进程

```vue
<!-- 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. 类型声明

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

declare global {
  interface Window {
    electronUpdater: ElectronUpdaterApi
  }
}
```

## API

### 主进程

#### createUpdater(config)

创建更新器实例。

```typescript
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 实例：

```typescript
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。

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

#### 工具函数

```typescript
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` 字段支持强制更新：

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

### user-changelog.json

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

## License

MIT