electron-update-sdk

面向 Electron 主进程的更新 SDK，封装 Release 元数据预检、多更新源回退、版本比较、下载取消和重启安装。

SDK 是纯 ESM 包，不包含窗口、IPC、UI 或具体存储实现。应用只需注入当前版本、跳过版本存储以及状态订阅器。

依赖约束

• Node.js 18.11 或更高版本，用于内置 fetch。
• SDK 固定依赖并封装 electron-updater 6.8.9，应用项目无需单独安装或加载。
• SDK 不执行依赖安装、运行、构建或发布操作。

本地开发时，使用者需先在 SDK 目录手动安装 SDK 自身的依赖，再建立链接：

# 在 electron-update-sdk 目录
npm link

# 在 Electron 应用目录
npm link electron-update-sdk

公共 API

SDK 只公开三个命名导出：

import {
  ElectronUpdateClient,
  UpdateEventType,
  UpdateSourceFactory,
} from 'electron-update-sdk';

创建 Client

const updateClient = new ElectronUpdateClient({
  currentVersion: () => app.getVersion(),
  sources: [
    UpdateSourceFactory.github({
      owner: 'owner',
      repository: 'release-repository',
    }),
  ],
  skippedVersionStore: {
    read: () => settings.get('updates.skippedVersion', ''),
    write: (version) => settings.set('updates.skippedVersion', version),
  },
  runtime: {
    forceDevelopmentUpdates: () => !app.isPackaged,
  },
  network: {
    metadataTimeoutMs: 15_000,
  },
  timeouts: {
    checkMs: 15_000,
  },
  logger: console,
});

logger 同时接收 SDK 和底层 electron-updater 日志。生产环境应注入具有 debug/info/log/warn/error 方法的持久化日志器，以便保留 Cannot download differentially, fallback to full download 等差分回退原因。

SDK 仅在检查某个候选源时切换 feed。下载阶段沿用检查结果中保存的 provider， 避免重新创建 provider 后出现元数据与下载源不一致。

Windows 差分下载前，SDK 会删除根缓存目录中无法验证版本归属的 current.blockmap，但保留当前版本的 installer.exe。随后由 electron-updater 从已确认的更新源重新读取当前版本 blockmap，避免手动安装或跨版本更新后，旧 blockmap 与新安装包错配，造成差分下载完成后又回退整包下载。

订阅状态并执行操作

const unsubscribe = updateClient.subscribe((event) => {
  console.log(event.type, event.source, event.sources, event.data);
});

await updateClient.initialize();
await updateClient.check({ trigger: 'manual' });
await updateClient.download();
await updateClient.cancelDownload();
updateClient.skipVersion('1.2.3');
await updateClient.install();

unsubscribe();
updateClient.dispose();

download() 的返回值为 { ok: true, files }；下载失败时返回 { ok: false, code: 'download-failed', error }。同一 Client 上的并发下载请求 会加入同一个下载会话，不会再次调用底层下载器。

事件对象具有固定结构：

{
  type: 'checking',
  source: { id: 'github', name: 'GitHub' },
  sources: [],
  data: {}
}

目录结构

| 目录 | 职责 | | --- | --- | | src/core/ | SDK 门面与生命周期 | | src/checks/ | 更新检测、候选版本选择和多源回退 | | src/download/ | 下载、取消与缓存清理 | | src/events/ | 标准事件定义与订阅发布 | | src/metadata/ | Release 元数据和 latest.yml 解析 | | src/network/ | 带超时及禁用缓存的 HTTP 请求 | | src/providers/ | electron-updater 自定义 provider | | src/runtime/ | electron-updater 动态加载与缓存适配 | | src/sources/ | 更新源工厂与运行状态仓库 | | src/storage/ | 跳过版本存储适配 | | src/version/ | 语义化版本解析与比较 | | src/shared/ | 通用校验、日志和 URL 模板 |