Table of Contents generated with DocToc

• @richie696/update-manager
  • 📋 目录
  • 架构设计
    • 核心设计原则
  • 快速开始
    • 安装
    • 基础用法
    • Framework 集成
  • 平台策略
    • Web 策略
    • Mobile 策略
    • Electron 策略
  • Framework 适配器
  • API 参考
    • UpdateManager
    • UnifiedVersionResponse
  • Delta 更新
  • 签名验证
  • 更新渠道
  • Electron 集成
    • 主进程
    • 渲染进程

@richie696/update-manager

📚 Monorepo 文档 · 📦 包结构 · 📦 npm · 💻 GitHub · 🐛 Issues · 🤝 贡献 · 🛡️ 安全 · 📄 License

全平台更新管理器，支持 Mobile (Capacitor/Capgo)、Desktop (Electron autoUpdater)、Web (version.json + SW)。一套 API 覆盖多端，通过子路径导出实现框架无关的按需引入。

📋 目录

• 架构设计
• 快速开始
• 平台策略
• Framework 适配器
• API 参考
• Delta 更新
• 签名验证
• 更新渠道
• Electron 集成

架构设计

┌─────────────────────────────┐
│       Application           │
│  (Angular / React / Vue 3)  │
└──────────────┬──────────────┘
               │ checkVersion()
               ▼
┌─────────────────────────────┐
│       UpdateManager         │  ← 统一入口
│                             │
│  ┌───────────────────────┐  │
│  │  VersionChecker       │  │  ← HTTP 请求服务端 /version
│  └───────────────────────┘  │
│             │               │
│             ▼               │
│  ┌───────────────────────┐  │
│  │  UnifiedVersionResponse│  │  ← 服务端返回统一协议
│  └───────────────────────┘  │
│             │               │
│     ┌───────┴───────┐       │
│     ▼               ▼       │
│  WebStrategy   MobileStrategy│
│  ElectronStrategy            │
│     │               │       │
│     ▼               ▼       │
│  下载 → 验证 → 应用         │
└─────────────────────────────┘

核心设计原则

1. 统一版本检测，差异化分发 — 一个 checkVersion() 接口，服务端返回协议后按平台 + 框架执行
2. Strategy 模式 — 每个平台有独立策略，运行时自动匹配
3. 渐进增强 — Web 端最低成本接入（version.json），移动端利用 Capgo，桌面端利用 autoUpdater
4. 零 SDK 依赖 — 纯 TypeScript 实现，按需引入，无强制外部依赖
5. 安全更新 — 包签名 (ECDSA) 验证，防篡改

快速开始

安装

pnpm add @richie696/update-manager
# 或
pnpm add @richie696/update-manager

基础用法

import { UpdateManager } from '@richie696/update-manager';

const manager = new UpdateManager({
  appId: 'com.example.app',
  version: '1.0.0',
  serverUrl: 'https://api.example.com/update',
});

// 检测更新
const result = await manager.checkVersion();

// 执行更新
if (result.hasUpdate) {
  await manager.downloadUpdate({
    onProgress: (progress) => console.log(`${progress.percent}%`),
  });
  await manager.applyUpdate();
}

Framework 集成

Angular:

import { provideUpdateManager } from '@richie696/update-manager/angular';

bootstrapApplication(AppComponent, {
  providers: [
    provideUpdateManager({
      appId: 'com.example.app',
      version: '1.0.0',
      serverUrl: 'https://api.example.com/update',
    }),
  ],
});

React:

import { UpdateProvider, useUpdate } from '@richie696/update-manager/react';

function App() {
  return (
    <UpdateProvider config={{ appId: 'com.example.app', version: '1.0.0', serverUrl: '...' }}>
      <Main />
    </UpdateProvider>
  );
}

function Main() {
  const { checkVersion, hasUpdate, downloadProgress, isDownloading } = useUpdate();
  // ...
}

Vue 3:

import { createApp } from 'vue';
import { createUpdatePlugin } from '@richie696/update-manager/vue';

const app = createApp(App);
app.use(createUpdatePlugin({
  appId: 'com.example.app',
  version: '1.0.0',
  serverUrl: 'https://api.example.com/update',
}));

平台策略

| 平台 | 策略类 | 更新方式 | 适用场景 | |------|--------|----------|----------| | Web | WebStrategy | version.json + 版本比对 → 提示刷新 | SPA 应用 | | Mobile | MobileStrategy | Capgo (Capacitor) 原生 OTA | Android / iOS App | | Electron | ElectronRendererStrategy | IPC → Electron Main → autoUpdater | 桌面应用 |

Web 策略

Web 策略通过请求 version.json 获取最新版本号，与本地的 localStorage 存储版本比对。

• 有更新 → 提示用户刷新或自动刷新（可配置）
• 支持 Service Worker 缓存控制

Mobile 策略

移动端通过 Capgo (@capgo/capacitor-updater) 实现原生 OTA 更新：

• 自动检测 Capgo 更新
• 支持静默下载 + 下次启动生效
• 支持紧急更新（forceUpdate）
• 回退 App Store / Google Play（可选）

Electron 策略

Electron 策略使用 IPC 通信桥接渲染进程 ↔ 主进程：

• 主进程运行 electron-updater 的 autoUpdater
• 支持全量 / 差分更新
• 支持强制更新与进度事件

Framework 适配器

| 框架 | 导入路径 | 特性 | |------|----------|------| | Angular | @richie696/update-manager/angular | provideUpdateManager() 函数式 DI + UpdateManagerService | | React | @richie696/update-manager/react | UpdateProvider + useUpdate() Hook + Context | | Vue 3 | @richie696/update-manager/vue | createUpdatePlugin() Plugin + Composable |

API 参考

UpdateManager

class UpdateManager {
  constructor(config: UpdateManagerConfig);

  // 检测版本
  checkVersion(): Promise<CheckVersionResult>;

  // 下载更新（支持进度回调、断点续传）
  downloadUpdate(options?: DownloadOptions): Promise<DownloadResult>;

  // 应用更新
  applyUpdate(): Promise<void>;

  // 获取当前更新状态
  getStatus(): UpdateStatus;

  // 取消下载
  cancelDownload(): Promise<void>;

  // 设置更新渠道（stable / beta / canary）
  setChannel(channel: UpdateChannel): void;

  // 获取可用更新历史
  getUpdateHistory(): UpdateRecord[];
}

UnifiedVersionResponse

interface UnifiedVersionResponse {
  appId: string;
  currentVersion: string;
  latestVersion: string;
  hasUpdate: boolean;
  updateType: UpdateType;        // 'major' | 'minor' | 'patch' | 'emergency'
  forceUpdate: boolean;
  forceUpdateLevel?: ForceUpdateLevel;
  releaseDate: string;
  releaseNotes: string;
  downloadUrl: string;
  deltaDownloadUrl?: string;
  checksum: string;
  signature: string;
  minAppVersion?: string;
  channel?: string;
}

Delta 更新

v1 支持 bsdiff 差分更新（Electron 平台）：

• 服务端需生成 bsdiff patch（新旧版本二进制对比）
• 客户端下载 patch 后合并生成完整包
• 减少用户下载流量，加速更新过程

签名验证

使用 ECDSA (P-256) 算法对更新包进行签名：

1. 服务端使用私钥对包内容的 SHA-256 进行签名
2. 客户端使用公钥验证签名合法性
3. 验证失败则拒绝应用更新
4. 公钥通过 UpdateManagerConfig.publicKey 传入

更新渠道

支持三种更新渠道，可在 UpdateManagerConfig 中配置：

| 渠道 | 适用场景 | |------|----------| | stable | 生产环境正式版本 | | beta | 内测体验版本 | | canary | 每日构建/实验版本 |

Electron 集成

主进程

// 在 Electron main 中引入
import '@richie696/update-manager/electron-main';
// 或手动使用
import { createElectronUpdater } from '@richie696/update-manager/electron-main';

createElectronUpdater({
  autoDownload: true,
  allowDowngrade: false,
  channel: 'stable',
});

渲染进程

渲染进程通过 IPC 自动与主进程通信，无需额外配置。

详细设计文档见 DESIGN.md