electron-updater-for-render 1.0.0

package/README.zh-CN.md

@@ -0,0 +1,359 @@
+# electron-updater-for-render
+
+[English](./README.md)
+
+专为 Electron 渲染进程设计的工业级混合式增量热更新框架（支持 Vue / React / 纯 HTML）。
+
+与 `electron-updater` 重新下载完整安装包的方案不同，本库通过替换 `.asar` 文件实现**渲染资源（HTML/CSS/JS）的无权限、无安装程序热更新**——用户完全无感知，秒级生效。
+
+---
+
+## 🚀 核心特性
+
+- **双轨更新模式**：内置原生弹窗自动更新 + 暴露 IPC 接口支持前端自定义进度 UI，两种方案自由切换
+- **强制更新控制**：云端下发 `forceUpdate: 'prompt'` 或 `'silent'`，应对 P0 级线上事故时一键锁死用户退路
+- **从容退场钩子**：`onBeforeRestart` 让渲染进程在 `app.relaunch()` 之前有充足时间保存草稿、提交日志
+- **并发互斥锁**：内置 `isDownloading` 单例锁，防止手动触发与开机自检同时争写同一 ASAR 文件
+- **智能冷库清道夫**：`maxVersionsToKeep` 自动淘汰最旧历史版本，保留可回滚备份，告别 C 盘无限膨胀
+- **Pipeline 流式下载**：Node.js `stream/promises pipeline` + `Transform` 管道，内存零泄漏，网络背压自动控制
+- **零配置版本探测**：默认自动读取 `process.cwd()/package.json` 中的版本号，无需任何额外配置
+- **独立打包命令**：普通 `npm run build` 不受任何影响，只有 `npm run build:update` 才会触发 ASAR 打包
+
+---
+
+## 📦 安装
+
+```bash
+npm install electron-updater-for-render
+
+# 打包阶段依赖（在渲染层项目中安装）
+npm install -D asar cross-env
+```
+
+---
+
+## 🗺️ 工作原理
+
+```
+┌─────────────────────────────────────────────────────┐
+│  渲染层项目（如 Vue 工程）                              │
+│  npm run build:update                               │
+│  → vite build → 打包 ASAR → 生成 latest.json        │
+└───────────────┬─────────────────────────────────────┘
+                │  上传 dist_updates/ 到服务器
+                ▼
+┌─────────────────────────────────────────────────────┐
+│  更新服务器（Nginx / OSS / CDN）                      │
+│  提供：latest.json + /1.0.2/renderer.asar           │
+└───────────────┬─────────────────────────────────────┘
+                │  应用启动时发起 HTTP 请求
+                ▼
+┌─────────────────────────────────────────────────────┐
+│  Electron 主进程                                     │
+│  updater.checkForUpdatesAndNotify()                 │
+│  → 检查版本 → 下载 ASAR → 重启应用                   │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🛠️ 完整接入指南
+
+### 第一步 — 渲染层项目：安装并配置 Vite 插件
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { electronRenderUpdater } from 'electron-updater-for-render/vite'
+
+export default defineConfig({
+  plugins: [
+    electronRenderUpdater({
+      outDir: './dist',              // 必填：Vite 构建输出目录
+      updatesDir: './dist_updates',  // 可选：更新包输出目录（默认 './dist_updates'）
+      // version: '1.2.3'            // 可选：显式指定版本号（优先级高于 package.json）
+      // packageJsonPath: './package.json'  // 可选：自定义 package.json 路径
+      // forceUpdate: 'prompt'       // 可选：'prompt' | 'silent'，仅 P0 紧急修复时使用
+    })
+  ]
+})
+```
+
+**版本号解析优先级：**
+1. `version` 字段（显式指定，优先级最高）
+2. `packageJsonPath` 所指向文件中的 `version`
+3. 自动检测：`process.cwd()/package.json`（默认，零配置）
+
+### 第二步 — 渲染层项目：配置独立的打包命令
+
+在 `package.json` 中新增 `build:update` 命令，与普通 `build` **完全分离**：
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "build:update": "cross-env ELECTRON_PACK_UPDATE=1 vite build"
+  }
+}
+```
+
+| 命令 | 行为 |
+|---|---|
+| `npm run build` | 普通前端打包，**不生成 ASAR**，与原有流程完全一致 |
+| `npm run build:update` | 构建前端产物 + 打包 ASAR + 生成 `latest.json`，用于发布更新 |
+
+### 第三步 — 部署更新文件到服务器
+
+执行 `npm run build:update` 后，`dist_updates/` 目录会生成：
+
+```
+dist_updates/
+├── latest.json          ← 版本清单（客户端拉取此文件判断是否需要更新）
+└── 1.0.2/
+    └── renderer.asar    ← 实际的更新载荷
+```
+
+**将 `dist_updates/` 目录下的全部内容上传至更新服务器：**
+
+```bash
+# 示例：同步到 S3 存储桶
+aws s3 sync dist_updates/ s3://your-bucket/auto-updates/
+
+# 示例：上传到 Nginx 服务器
+rsync -avz dist_updates/ user@your-server:/var/www/auto-updates/
+```
+
+客户端会依次请求：
+- `GET https://your-server.com/latest.json`  （获取版本清单）
+- `GET https://your-server.com/1.0.2/renderer.asar`  （下载更新包）
+
+---
+
+### 第四步 — Electron 外壳：配置主进程运行时
+
+```typescript
+// src/main/index.ts
+import { app, BrowserWindow, ipcMain } from 'electron'
+import { join } from 'path'
+import { RenderUpdater } from 'electron-updater-for-render'
+
+const updater = new RenderUpdater({
+  updateUrl: 'https://your-server.com/auto-updates', // 必填：更新服务器根地址
+  versionsDir: join(app.getPath('userData'), 'versions'), // 必填：本地版本存储目录
+  maxVersionsToKeep: 2,  // 可选：保留最近 2 个旧版本供回滚（默认 2）
+
+  // 可选：重启前给渲染层时间保存状态
+  onBeforeRestart: async () => {
+    const [win] = BrowserWindow.getAllWindows()
+    if (win) {
+      win.webContents.send('updater:before-restart')
+      await new Promise(resolve => setTimeout(resolve, 2000))
+    }
+  }
+})
+
+app.whenReady().then(async () => {
+  const mainWindow = new BrowserWindow({
+    webPreferences: { preload: join(__dirname, '../preload/index.js') }
+  })
+
+  // 优先加载已下载的热更新 ASAR，否则回退到开发服务器
+  const loadUrl = updater.getLoadUrl()
+  mainWindow.loadURL(loadUrl || 'http://localhost:5173')
+
+  // 延迟触发自动检测（支持拦截强制更新，autoPrompt 为 true 时会弹窗提示）
+  setTimeout(() => updater.checkForUpdatesAndNotify(), 3000)
+})
+
+// 暴露 IPC 接口，供前端界面主动控制更新流程
+ipcMain.handle('updater:check', () => updater.check())
+ipcMain.handle('updater:download', () =>
+  updater.download((percent) => {
+    BrowserWindow.getAllWindows()[0]?.webContents.send('updater:progress', percent)
+  })
+)
+ipcMain.handle('updater:install', () => {
+  app.relaunch()
+  app.quit()
+})
+```
+
+---
+
+### 第五步 — Preload 脚本
+
+```typescript
+// src/preload/index.ts
+import { contextBridge, ipcRenderer } from 'electron'
+
+contextBridge.exposeInMainWorld('updater', {
+  check: () => ipcRenderer.invoke('updater:check'),
+  download: () => ipcRenderer.invoke('updater:download'),
+  install: () => ipcRenderer.invoke('updater:install'),
+
+  onProgress: (callback: (percent: number) => void) => {
+    const fn = (_: any, p: number) => callback(p)
+    ipcRenderer.on('updater:progress', fn)
+    return () => ipcRenderer.removeListener('updater:progress', fn)
+  },
+
+  onBeforeRestart: (callback: () => void) => {
+    const fn = () => callback()
+    ipcRenderer.on('updater:before-restart', fn)
+    return () => ipcRenderer.removeListener('updater:before-restart', fn)
+  }
+})
+```
+
+---
+
+### 第六步 — 渲染层 UI（Vue 示例）
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted } from 'vue'
+
+const status = ref('')
+const progress = ref(0)
+const hasUpdate = ref(false)
+
+let removeProgress: (() => void) | null = null
+let removeRestart: (() => void) | null = null
+
+onMounted(() => {
+  // 监听重启通知，提前保存状态
+  removeRestart = window.updater.onBeforeRestart(() => {
+    status.value = '即将重启，保存状态中...'
+    localStorage.setItem('draft', JSON.stringify({ /* 你的状态 */ }))
+  })
+})
+
+onUnmounted(() => {
+  removeProgress?.()
+  removeRestart?.()
+})
+
+// 手动检查更新
+const checkUpdate = async () => {
+  status.value = '检查中...'
+  const result = await window.updater.check()
+  if (result.updateAvailable) {
+    hasUpdate.value = true
+    status.value = `发现新版本：v${result.version}`
+  } else {
+    status.value = '当前已是最新版本'
+  }
+}
+
+// 手动下载更新
+const downloadUpdate = async () => {
+  status.value = '下载中...'
+  removeProgress = window.updater.onProgress((p) => {
+    progress.value = p
+    status.value = `下载中 ${p.toFixed(0)}%`
+  })
+  await window.updater.download()
+  removeProgress?.()
+  status.value = '下载完成，可以安装'
+}
+
+// 安装并重启
+const installUpdate = () => {
+  window.updater.install()
+}
+</script>
+
+<template>
+  <div>
+    <p>{{ status }}</p>
+    <progress :value="progress" max="100" v-if="progress > 0" />
+    <button @click="checkUpdate">检查更新</button>
+    <button @click="downloadUpdate" v-if="hasUpdate">立即下载</button>
+    <button @click="installUpdate">安装并重启</button>
+  </div>
+</template>
+```
+
+---
+
+## ⚙️ API 参考
+
+### `BuilderOptions`（Vite 插件参数）
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `outDir` | `string` | ✅ | Vite 构建输出目录 |
+| `updatesDir` | `string` | — | 更新包输出目录，默认 `./dist_updates` |
+| `version` | `string` | — | 显式指定版本号，优先级高于 `packageJsonPath` |
+| `packageJsonPath` | `string` | — | 自定义 `package.json` 路径，不填则自动读取 `process.cwd()/package.json` |
+| `asarName` | `string` | — | ASAR 文件名，默认 `renderer.asar` |
+| `privateKeyPath` | `string` | — | RSA 私钥路径，用于为 ASAR 生成签名 |
+| `releaseNotesPath` | `string` | — | 更新日志 Markdown 文件路径 |
+| `forceUpdate` | `'prompt' \| 'silent'` | — | 强制更新模式，`'prompt'` 弹窗告知，`'silent'` 完全静默 |
+
+### `UpdaterOptions`（主进程参数）
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `updateUrl` | `string` | ✅ | 更新服务器根地址 |
+| `versionsDir` | `string` | ✅ | 本地 ASAR 版本存储目录 |
+| `publicKey` | `string` | — | RSA 公钥（PEM 格式），用于验证 ASAR 签名 |
+| `autoDownload` | `boolean` | — | 发现更新后自动下载，不弹窗询问。默认 `false` |
+| `autoPrompt` | `boolean` | — | 使用内置原生弹窗引导更新。默认 `true` |
+| `maxVersionsToKeep` | `number` | — | 本地保留的旧版本数量（不含当前），默认 `2` |
+| `onUpdateAvailable` | `function` | — | 检测到更新时的自定义钩子：`(info, doDownload) => void` |
+| `onDownloadProgress` | `function` | — | 下载进度回调：`(percent: number) => void` |
+| `onDownloadComplete` | `function` | — | 下载完成钩子：`(info, doInstall) => void` |
+| `onError` | `function` | — | 错误回调：`(error: Error) => void` |
+| `onBeforeRestart` | `async function` | — | `app.relaunch()` 前的异步钩子，可用于保存状态 |
+
+---
+
+## 🛡️ 强制更新（P0 应急使用）
+
+当线上出现资损、安全漏洞、核心功能崩溃等 P0 级故障时，通过 `forceUpdate` 剥夺用户的拒绝权：
+
+```typescript
+// vite.config.ts（打包前加上此行）
+electronRenderUpdater({
+  outDir: './dist',
+  forceUpdate: 'prompt'  // 或 'silent'
+})
+```
+
+| 模式 | 行为 |
+|---|---|
+| `'prompt'` | 弹出系统级警告弹窗，**只有一个确认按钮**，用户无法取消或跳过。点击后立即开始下载并重启 |
+| `'silent'` | 完全静默：后台自动下载、自动安装、自动重启，用户毫无感知 |
+
+> ⚠️ 本功能会**永久剥夺用户本次的延迟权**，请仅在真正的 P0 级生产事故中使用。
+
+---
+
+## 🔐 RSA 签名验证（可选，推荐生产环境启用）
+
+```bash
+# 生成密钥对
+openssl genrsa -out private.pem 2048
+openssl rsa -in private.pem -pubout -out public.pem
+```
+
+```typescript
+// vite.config.ts
+electronRenderUpdater({ outDir: './dist', privateKeyPath: './private.pem' })
+
+// main/index.ts
+import { readFileSync } from 'fs'
+new RenderUpdater({
+  updateUrl: '...',
+  versionsDir: '...',
+  publicKey: readFileSync('./public.pem', 'utf-8')
+})
+```
+
+---
+
+## License
+
+MIT