electron-updater-for-render 1.1.2-beta.5 → 1.1.2-beta.6

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 # electron-updater-for-render
 
-[English](./README.md)
+[English](./Readme.md)
 
 专为 Electron 渲染进程设计的工业级混合式增量热更新框架（支持 Vue / React / 纯 HTML）。
 
@@ -11,13 +11,17 @@
 ## 🚀 核心特性
 
 - **双轨更新模式**：内置原生弹窗自动更新 + 暴露 IPC 接口支持前端自定义进度 UI，两种方案自由切换
+- **三态检查系统**：`check()` 返回 `idle / available / ready` 三种状态，UI 始终知道应该显示"下载"还是"重启"，彻底消除重复下载弹窗
+- **就绪状态持久化**：用户点击"稍后安装"后，下载的更新会记录到磁盘。下次启动或刷新页面，UI 直接跳到"立即重启"——无需重新下载
+- **实时状态推送**：`onStatusChanged` 钩子让主进程在更新就绪时（如静默后台下载完成）主动通知渲染层，UI 即时刷新无需用户手动操作
 - **强制更新控制**：云端下发 `forceUpdate: 'prompt'` 或 `'silent'`，应对 P0 级线上事故时一键锁死用户退路
 - **从容退场钩子**：`onBeforeRestart` 让渲染进程在 `app.relaunch()` 之前有充足时间保存草稿、提交日志
 - **并发互斥锁**：内置 `isDownloading` 单例锁，防止手动触发与开机自检同时争写同一 ASAR 文件
-- **智能冷库清道夫**：`maxVersionsToKeep` 自动淘汰最旧历史版本，保留可回滚备份，告别 C 盘无限膨胀
+- **智能冷库清道夫**：`maxVersionsToKeep` 自动淘汰最旧历史版本，保留可回滚备份，告别磁盘无限膨胀
 - **Pipeline 流式下载**：Node.js `stream/promises pipeline` + `Transform` 管道，内存零泄漏，网络背压自动控制
 - **零配置版本探测**：默认自动读取 `process.cwd()/package.json` 中的版本号，无需任何额外配置
 - **独立打包命令**：普通 `npm run build` 不受任何影响，只有 `npm run build:update` 才会触发 ASAR 打包
+- **History 模式 SPA 支持**：内置自定义协议处理器（`app://`），支持 Vue/React History 路由模式，零配置零样板代码
 
 ---
 
@@ -27,7 +31,7 @@
 npm install electron-updater-for-render
 
 # 打包阶段依赖（在渲染层项目中安装）
-npm install -D asar
+npm install -D @electron/asar
 ```
 
 ---
@@ -38,7 +42,7 @@ npm install -D asar
 ┌─────────────────────────────────────────────────────┐
 │  渲染层项目（如 Vue 工程）                              │
 │  npm run build:update                               │
-│  → 原生 build 命令 → 调用 CLI打包 ASAR → 生成 latest.json │
+│  → 原生 build → CLI 打包 ASAR → 生成 latest.json     │
 └───────────────┬─────────────────────────────────────┘
                 │  上传 dist_updates/ 到服务器
                 ▼
@@ -50,18 +54,30 @@ npm install -D asar
                 ▼
 ┌─────────────────────────────────────────────────────┐
 │  Electron 主进程                                     │
-│  updater.checkForUpdatesAndNotify()                 │
-│  → 检查版本 → 下载 ASAR → 重启应用                   │
+│  updater.check() → 'idle' | 'available' | 'ready'  │
+│  → 下载 ASAR → setUpdatePending()                   │
+│  → onStatusChanged 推送 → 渲染层 UI 即时更新          │
+│  → 重启时：应用更新 → app.relaunch()                  │
 └─────────────────────────────────────────────────────┘
 ```
 
+### 三态更新生命周期
+
+| 状态 | 含义 | UI 行为 |
+|---|---|---|
+| `idle` | 未找到更新 | 显示"检查更新"按钮 |
+| `available` | 发现新版本，尚未下载 | 显示"立即下载"按钮 |
+| `ready` | 更新已下载，等待重启 | 显示"立即重启安装"按钮 |
+
+`ready` 状态会**持久化到磁盘**（`current.json`）。即使用户刷新页面或重新打开应用，UI 也能正确显示"立即重启"，而不会再次要求下载。
+
 ---
 
 ## 🛠️ 完整接入指南
 
 ### 第一步 — 渲染工程：配置并声明生成规则
 
-在您的任何前端项目根目录下（无论 Vite, Webpack，亦或普通网页）新建 `updater.config.ts`：
+在您的任何前端项目根目录下（无论 Vite、Webpack，亦或普通网页）新建 `updater.config.ts`：
 
 ```typescript
 import { defineConfig } from 'electron-updater-for-render/builder'
@@ -123,8 +139,8 @@ 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`  （下载更新包）
+- `GET https://your-server.com/latest.json`（获取版本清单）
+- `GET https://your-server.com/1.0.2/renderer.asar`（下载更新包）
 
 ---
 
@@ -148,6 +164,15 @@ const updater = new RenderUpdater({
       win.webContents.send('updater:before-restart')
       await new Promise(resolve => setTimeout(resolve, 2000))
     }
+  },
+
+  // 可选：当更新状态发生变化时（如后台下载完成），主动推送给渲染层
+  // 渲染层无需手动检查，按钮会自动切换到"立即重启"
+  onStatusChanged: (data) => {
+    const [win] = BrowserWindow.getAllWindows()
+    if (win) {
+      win.webContents.send('updater:status-changed', data)
+    }
   }
 })
 
@@ -166,12 +191,16 @@ app.whenReady().then(async () => {
 
 // 暴露 IPC 接口，供前端界面主动控制更新流程
 ipcMain.handle('updater:check', () => updater.check())
-ipcMain.handle('updater:download', () =>
-  updater.download((percent) => {
+
+// ⚠️ 重要：第一个参数必须是前端传来的 UpdateInfo 对象，第二个才是进度回调
+// 这样可以避免主进程重复请求 latest.json，也杜绝了参数错位导致的崩溃
+ipcMain.handle('updater:download', async (event, info) =>
+  updater.download(info, (percent) => {
     BrowserWindow.getAllWindows()[0]?.webContents.send('updater:progress', percent)
   })
 )
-ipcMain.handle('updater:install', () => {
+
+ipcMain.on('updater:install', () => {
   app.relaunch()
   app.quit()
 })
@@ -187,8 +216,12 @@ import { contextBridge, ipcRenderer } from 'electron'
 
 contextBridge.exposeInMainWorld('updater', {
   check: () => ipcRenderer.invoke('updater:check'),
-  download: () => ipcRenderer.invoke('updater:download'),
-  install: () => ipcRenderer.invoke('updater:install'),
+
+  // 将 check() 返回的 UpdateInfo 对象透传给主进程
+  // 主进程凭此对象直接下载，无需重新请求 latest.json
+  download: (info?: any) => ipcRenderer.invoke('updater:download', info),
+
+  install: () => ipcRenderer.send('updater:install'),
 
   onProgress: (callback: (percent: number) => void) => {
     const fn = (_: any, p: number) => callback(p)
@@ -200,75 +233,170 @@ contextBridge.exposeInMainWorld('updater', {
     const fn = () => callback()
     ipcRenderer.on('updater:before-restart', fn)
     return () => ipcRenderer.removeListener('updater:before-restart', fn)
+  },
+
+  // 监听主进程的主动状态推送
+  // 当后台下载完成（如用户点"稍后安装"之后）时，UI 会自动更新到"立即重启"
+  onStatusChanged: (callback: (data: { status: string; version: string }) => void) => {
+    const fn = (_: any, data: any) => callback(data)
+    ipcRenderer.on('updater:status-changed', fn)
+    return () => ipcRenderer.removeListener('updater:status-changed', fn)
   }
 })
 ```
 
 ---
 
-### 第六步 — 渲染层 UI（Vue 示例）
+### 第六步 — 渲染层 UI（Vue 完整示例）
+
+以下示例展示了完整的三态更新流程，包含：
+- **启动自动检测**——无需用户手动点击即可感知更新
+- **三态精准识别**——根据 `check()` 返回的 `status` 正确显示"下载"或"重启"
+- **实时状态同步**——后台下载完成后，主进程推送通知，UI 立即刷新
 
 ```vue
 <script setup lang="ts">
 import { ref, onMounted, onUnmounted } from 'vue'
 
-const status = ref('')
+// 状态：'idle' | 'checking' | 'available' | 'downloading' | 'ready' | 'no-update'
+const status = ref<'idle' | 'checking' | 'available' | 'downloading' | 'ready' | 'no-update'>('idle')
 const progress = ref(0)
-const hasUpdate = ref(false)
+const newVersion = ref('')
+const updateInfo = ref<any>(null)  // 存储完整的 UpdateInfo，供 download() 使用
+const errMsg = ref('')
 
 let removeProgress: (() => void) | null = null
 let removeRestart: (() => void) | null = null
+let removeStatusChanged: (() => void) | null = null
 
-onMounted(() => {
-  // 监听重启通知，提前保存状态
-  removeRestart = window.updater.onBeforeRestart(() => {
-    status.value = '即将重启，保存状态中...'
-    localStorage.setItem('draft', JSON.stringify({ /* 你的状态 */ }))
-  })
-})
-
-onUnmounted(() => {
-  removeProgress?.()
-  removeRestart?.()
-})
+const getUpdater = () => (window as any).updater
 
-// 手动检查更新
+// ── 检查更新 ───────────────────────────────────────────────────────────────
+// check() 返回 { status: 'idle' | 'available' | 'ready', version, info }
+// 若状态为 'ready'，说明更新已下载完毕只待重启，直接跳过下载流程
 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 updater = getUpdater()
+  if (!updater) return
+
+  status.value = 'checking'
+  try {
+    const res = await updater.check()
+    if (res.updateAvailable) {
+      newVersion.value = res.version
+      updateInfo.value = res.info
+      // 精确识别：'ready' 直接进入重启状态，不再显示下载按钮
+      status.value = res.status === 'ready' ? 'ready' : 'available'
+    } else {
+      status.value = 'no-update'
+    }
+  } catch (err: any) {
+    errMsg.value = '检查失败: ' + err.message
+    status.value = 'idle'
   }
 }
 
-// 手动下载更新
+// ── 下载更新 ───────────────────────────────────────────────────────────────
+// 将 check() 返回的 info 对象传给 download()，避免主进程重复请求 latest.json
 const downloadUpdate = async () => {
-  status.value = '下载中...'
-  removeProgress = window.updater.onProgress((p) => {
-    progress.value = p
-    status.value = `下载中 ${p.toFixed(0)}%`
+  const updater = getUpdater()
+  if (!updater) return
+
+  status.value = 'downloading'
+  progress.value = 0
+
+  removeProgress = updater.onProgress((percent: number) => {
+    progress.value = percent
   })
-  await window.updater.download()
-  removeProgress?.()
-  status.value = '下载完成，可以安装'
+
+  try {
+    await updater.download(updateInfo.value)
+    status.value = 'ready'
+  } catch (err: any) {
+    errMsg.value = '下载失败: ' + err.message
+    status.value = 'available'
+  } finally {
+    removeProgress?.()
+  }
 }
 
-// 安装并重启
+// ── 安装并重启 ─────────────────────────────────────────────────────────────
 const installUpdate = () => {
-  window.updater.install()
+  getUpdater()?.install()
+}
+
+// ── 监听主进程主动推送的状态变更 ───────────────────────────────────────────
+// 场景：用户点击"稍后安装"后，日后主进程 onStatusChanged 触发时
+// UI 无需用户做任何操作，按钮自动变为"立即重启"
+const initStatusListener = () => {
+  const updater = getUpdater()
+  if (updater?.onStatusChanged) {
+    return updater.onStatusChanged((data: { status: string; version: string }) => {
+      if (data.status === 'ready') {
+        status.value = 'ready'
+        newVersion.value = data.version
+      }
+    })
+  }
+  return null
 }
+
+// ── 监听重启前通知 ─────────────────────────────────────────────────────────
+const initRestartListener = () => {
+  const updater = getUpdater()
+  if (updater?.onBeforeRestart) {
+    return updater.onBeforeRestart(() => {
+      // 在此保存未提交的表单状态
+      console.log('应用即将重启，请保存状态...')
+    })
+  }
+  return null
+}
+
+// ── 生命周期 ───────────────────────────────────────────────────────────────
+onMounted(() => {
+  removeStatusChanged = initStatusListener()
+  removeRestart = initRestartListener()
+
+  // 启动后 2 秒自动检查，不阻塞首屏渲染
+  setTimeout(checkUpdate, 2000)
+})
+
+onUnmounted(() => {
+  removeProgress?.()
+  removeRestart?.()
+  removeStatusChanged?.()
+})
 </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 class="updater">
+    <div v-if="errMsg" class="error">{{ errMsg }}</div>
+
+    <!-- 无活跃更新任务 -->
+    <button v-if="status === 'idle' || status === 'no-update'" @click="checkUpdate">
+      {{ status === 'no-update' ? '当前已是最新，重新检查' : '主动检查新版本' }}
+    </button>
+
+    <!-- 检查中 -->
+    <span v-if="status === 'checking'">正在拉取更新配置...</span>
+
+    <!-- 发现新版本，尚未下载 -->
+    <div v-if="status === 'available'">
+      <p>🔥 发现新版本: v{{ newVersion }}</p>
+      <button @click="downloadUpdate">立即下载并缓存</button>
+    </div>
+
+    <!-- 下载中 -->
+    <div v-if="status === 'downloading'">
+      <p>正在下载... {{ progress.toFixed(1) }}%</p>
+      <progress :value="progress" max="100" />
+    </div>
+
+    <!-- 更新已就绪（刷新页面后此状态依然保持）-->
+    <div v-if="status === 'ready'">
+      <p>✅ v{{ newVersion }} 已就绪</p>
+      <button @click="installUpdate">立即重启并安装</button>
+    </div>
   </div>
 </template>
 ```
@@ -287,7 +415,7 @@ const installUpdate = () => {
 - **前端 (Router)**：使用 `createWebHashHistory()`。
 
 ### 2. History 模式（企业级方案）
-支持美观的 URL 和标准浏览器重载行为。由于 `file://` 不支持标准路解析，本库会自动启用自定义协议（默认 `app://`）进行转发。
+支持美观的 URL 和标准浏览器重载行为。由于 `file://` 不支持标准路由解析，本库会自动启用自定义协议（默认 `app://`）进行转发。
 
 - **主进程**：
   ```typescript
@@ -298,9 +426,9 @@ const installUpdate = () => {
     protocol: 'my-app'       // 可选：自定义协议名 (默认 'app')
   })
   ```
-  > 💡 **全自动化：** 协议注册和特权赋权逻辑已在库内部**全自动处理**，您无需在顶层编写任何 `registerSchemesAsPrivileged` 等繁琐代码。
+  > 💡 **全自动化**：协议注册和特权赋权逻辑已在库内部**全自动处理**，您无需编写任何 `registerSchemesAsPrivileged` 等繁琐代码。
 
-- **前端构建工具 (Vite, Webpack, 等)**：**关键配置** —— 您必须将构建工具的 **公共路径 (Public Path / Base)** 设置为 `/`。这是为了确保生成的资源引用（JS/CSS/图片）为绝对路径，防止在深层路由（如 `/home/settings`）下刷新页面时出现资源加载 404。
+- **前端构建工具（Vite、Webpack 等）**：**关键配置** —— 必须将 **公共路径 (Public Path / Base)** 设置为 `/`，确保资源引用为绝对路径，防止在深层路由下刷新出现 404。
   - **Vite**：`base: '/'`
   - **Webpack**：`output.publicPath: '/'`
 - **前端路由 (Router)**：使用 `createWebHistory()`。
@@ -313,7 +441,7 @@ const installUpdate = () => {
 
 | 参数 | 类型 | 必填 | 说明 |
 |---|---|---|---|
-| `outDir` | `string` | ✅ | Vite 构建输出目录 |
+| `outDir` | `string` | ✅ | 构建输出目录 |
 | `updatesDir` | `string` | — | 更新包输出目录，默认 `./dist_updates` |
 | `version` | `string` | — | 显式指定版本号，优先级高于 `packageJsonPath` |
 | `packageJsonPath` | `string` | — | 自定义 `package.json` 路径，不填则自动读取 `process.cwd()/package.json` |
@@ -331,14 +459,30 @@ const installUpdate = () => {
 | `publicKey` | `string` | — | RSA 公钥（PEM 格式），用于验证 ASAR 签名 |
 | `autoDownload` | `boolean` | — | 发现更新后自动下载，不弹窗询问。默认 `false` |
 | `autoPrompt` | `boolean` | — | 使用内置原生弹窗引导更新。默认 `true` |
-| `maxVersionsToKeep` | `number` | — | 本地保留的旧版本数量（不含当前），默认 `2` |
+| `maxVersionsToKeep` | `number` | — | 本地保留的旧版本数量，默认 `2` |
+| `routerMode` | `'hash' \| 'history'` | — | 路由模式选择。默认 `'hash'` |
+| `protocol` | `string` | — | History 模式下的自定义协议名。默认 `'app'` |
 | `onUpdateAvailable` | `function` | — | 检测到更新时的自定义钩子：`(info, doDownload) => void` |
 | `onDownloadProgress` | `function` | — | 下载进度回调：`(percent: number) => void` |
 | `onDownloadComplete` | `function` | — | 下载完成钩子：`(info, doInstall) => void` |
+| `onStatusChanged` | `function` | — | 状态变更推送钩子：`(data: { status: 'ready' \| 'available' \| 'idle', version: string }) => void` |
 | `onError` | `function` | — | 错误回调：`(error: Error) => void` |
 | `onBeforeRestart` | `async function` | — | `app.relaunch()` 前的异步钩子，可用于保存状态 |
-| `routerMode` | `'hash' \| 'history'` | — | 路由模式选择。默认 `'hash'` |
-| `protocol` | `string` | — | History 模式下的自定义协议名。默认 `'app'` |
+
+### `RenderUpdater` 实例方法
+
+| 方法 | 返回值 | 说明 |
+|---|---|---|
+| `check()` | `Promise<CheckResult>` | 检查更新。返回 `{ updateAvailable, status, version, info }`，其中 `status` 为 `'idle' \| 'available' \| 'ready'` |
+| `download(info?, onProgress?)` | `Promise<void>` | 下载更新。将 `check()` 返回的 `info` 传入，可避免重复请求 latest.json |
+| `getLoadUrl()` | `string` | 返回最新 ASAR 的加载地址（`app://renderer/` 或 `file://...`），未安装任何更新时返回空字符串 |
+| `installAndRestart()` | `Promise<void>` | 应用待安装更新并重启应用 |
+| `checkForUpdatesAndNotify()` | `Promise<void>` | 一键式：检查 + 弹窗 + 下载 + 安装，使用内置原生弹窗 |
+| `setUpdatePending(version)` | `void` | 将某版本标记为已下载待重启，同时触发 `onStatusChanged` |
+| `useVersion(version)` | `void` | 立即切换磁盘和内存双重版本指针 |
+| `activeVersion` | `string`（getter） | 当前内存中正在运行的版本（本次会话） |
+| `pendingVersion` | `string`（getter） | 磁盘上最新已下载版本 |
+| `isUpdatePending` | `boolean`（getter） | 若 `pendingVersion > activeVersion` 则为 `true` |
 
 ---
 
@@ -347,7 +491,7 @@ const installUpdate = () => {
 当线上出现资损、安全漏洞、核心功能崩溃等 P0 级故障时，通过 `forceUpdate` 剥夺用户的拒绝权：
 
 ```typescript
-// updater.config.ts (加入此行)
+// updater.config.ts
 export default defineConfig({
   outDir: './dist',
   forceUpdate: 'prompt'  // 或 'silent'
@@ -356,7 +500,7 @@ export default defineConfig({
 
 | 模式 | 行为 |
 |---|---|
-| `'prompt'` | 弹出系统级警告弹窗，**只有一个确认按钮**，用户无法取消或跳过。点击后立即开始下载并重启 |
+| `'prompt'` | 弹出系统级警告弹窗，**只有一个确认按钮**，用户无法取消或跳过，点击后立即开始下载并重启 |
 | `'silent'` | 完全静默：后台自动下载、自动安装、自动重启，用户毫无感知 |
 
 > ⚠️ 本功能会**永久剥夺用户本次的延迟权**，请仅在真正的 P0 级生产事故中使用。