electron-updater-for-render 2.0.0-beta.1 → 2.0.1

package/README.zh-CN.md

@@ -11,9 +11,9 @@
 ## 🚀 核心特性
 
 - **双轨更新模式**：内置原生弹窗自动更新 + 暴露 IPC 接口支持前端自定义进度 UI，两种方案自由切换
-- **三态检查系统**：`check()` 返回 `idle / available / ready` 三种状态，UI 始终知道应该显示"下载"还是"重启"，彻底消除重复下载弹窗
-- **就绪状态持久化**：用户点击"稍后安装"后，下载的更新会记录到磁盘。下次启动或刷新页面，UI 直接跳到"立即重启"——无需重新下载
-- **实时状态推送**：`onStatusChanged` 钩子让主进程在更新就绪时（如静默后台下载完成）主动通知渲染层，UI 即时刷新无需用户手动操作
+- **三态检查系统**：`check()` 明确返回 `idle / available / ready` 三种状态，帮助前端 UI 精确区分“无更新”、“全网首发下载”与“已就绪待重启”阶段，实现丝滑的状态流转
+- **就绪状态持久化**：智能识别本地已下载的更新缓存。即使用户暂不安装或页面发生刷新，更新状态依然保持“待重启”就绪态，保障断点体验的连续性
+- **实时状态推送**：`onStatusChanged` 钩子让主进程在更新就绪时主动通知渲染层完成 UI 刷新
 - **强制更新控制**：云端下发 `forceUpdate: 'prompt'` 或 `'silent'`，应对 P0 级线上事故时一键锁死用户退路
 - **从容退场钩子**：`onBeforeRestart` 让渲染进程在 `app.relaunch()` 之前有充足时间保存草稿、提交日志
 - **并发互斥锁**：内置 `isDownloading` 单例锁，防止手动触发与开机自检同时争写同一 ASAR 文件
@@ -21,7 +21,12 @@
 - **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 路由模式，零配置零样板代码
+- **History 模式支持**：内置支持 Vue/React 的 History 路由模式。
+- **多页应用 (MPA) 支持**：支持通过 `getLoadUrl(entry)` 加载不同的入口文件。
+- **极简 SDK 接入**：提供 `/main`, `/preload`, `/renderer` 导出，内置 `getRouterBase` 路由基准路径探测工具。
+- **精准灰度分发**：支持基于 `deviceId` 的环境身份匹配，配合 `updater.config.ts` 中的 `rolloutRule` 可实现百分百定点静默空投。
+- **Semver 内测通道**：基于 `allowPrerelease` 提供生产环境与内测环境的天然逻辑隔离，保障正式服用户免受 Beta 版干扰。
+- **动态网关鉴权**：通过 `requestOptions` 可在 HTTP 请求中自定义 Headers（如 Oauth / Bearer Token）及 Query 参数。
 
 ---
 
@@ -85,6 +90,9 @@ import { defineConfig } from 'electron-updater-for-render/builder'
 export default defineConfig({
   outDir: './dist',              // 必填：您的构建输出目录
   updatesDir: './dist_updates',  // 可选：更新包输出目录（默认 './dist_updates'）
+  // rolloutRule: {
+  //   deviceIds: ['YOUR_DEVICE_ID'] // 可选：灰度定向分发，仅指明白名单设备可更新
+  // },
   // version: '1.2.3'            // 可选：显式指定版本号（优先级高于 package.json）
   // packageJsonPath: './package.json'  // 可选：自定义 package.json 路径
   // forceUpdate: 'prompt'       // 可选：'prompt' | 'silent'，仅 P0 紧急修复时使用
@@ -148,62 +156,48 @@ rsync -avz dist_updates/ user@your-server:/var/www/auto-updates/
 
 ```typescript
 // src/main/index.ts
-import { app, BrowserWindow, ipcMain } from 'electron'
+import { app, BrowserWindow } from 'electron'
 import { join } from 'path'
-import { RenderUpdater } from 'electron-updater-for-render'
+import { RenderUpdater, setupUpdaterIPC } from 'electron-updater-for-render/main'
 
 const updater = new RenderUpdater({
   updateUrl: 'https://your-server.com/auto-updates', // 必填：更新服务器根地址
   versionsDir: join(app.getPath('userData'), 'versions'), // 必填：本地版本存储目录
+  
+  // 身份标识：配合 rolloutRule 实现灰度定向空投
+  identity: { deviceId: 'YOUR_DEVICE_UUID' },
+  // 频道管理：是否接收内测包（版本号包含 -beta/-rc 等后缀）
+  allowPrerelease: true,
+  // 网关定制：在请求中挂载自定义 Header（如鉴权）
+  requestOptions: {
+    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
+  },
+
   maxVersionsToKeep: 2,  // 可选：保留最近 2 个旧版本供回滚（默认 2）
 
-  // 可选：重启前给渲染层时间保存状态
+  // 可选：延缓重启时间。配合前端的 onBeforeRestart 钩子，给予 Vue 保存表单状态的时间
   onBeforeRestart: async () => {
-    const [win] = BrowserWindow.getAllWindows()
-    if (win) {
-      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)
-    }
+    await new Promise(resolve => setTimeout(resolve, 2000))
   }
 })
 
+// 🎉 一键自动打通全链路 IPC 总线
+// 它不仅暴露方法，还会自动将主进程的 progress, status, restart 生命周期广播给所有渲染层
+setupUpdaterIPC(updater)
+
 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')
+  // 加载最新下载好的 ASAR，若无更新则回退至本地 dist。
+  // 支持多页应用入口传入 (默认为 'index.html')
+  const loadUrl = updater.getLoadUrl('login/index.html')
+  mainWindow.loadURL(loadUrl || `file://${join(__dirname, '../renderer/login/index.html')}`)
 
   // 延迟触发自动检测（支持拦截强制更新，autoPrompt 为 true 时会弹窗提示）
   setTimeout(() => updater.checkForUpdatesAndNotify(), 3000)
 })
-
-// 暴露 IPC 接口，供前端界面主动控制更新流程
-ipcMain.handle('updater:check', () => updater.check())
-
-// ⚠️ 重要：第一个参数必须是前端传来的 UpdateInfo 对象，第二个才是进度回调
-// 这样可以避免主进程重复请求 latest.json，也杜绝了参数错位导致的崩溃
-ipcMain.handle('updater:download', async (event, info) =>
-  updater.download(info, (percent) => {
-    BrowserWindow.getAllWindows()[0]?.webContents.send('updater:progress', percent)
-  })
-)
-
-ipcMain.on('updater:install', () => {
-  app.relaunch()
-  app.quit()
-})
 ```
 
 ---
@@ -213,36 +207,10 @@ ipcMain.on('updater:install', () => {
 ```typescript
 // src/preload/index.ts
 import { contextBridge, ipcRenderer } from 'electron'
+import { exposeUpdaterPreload } from 'electron-updater-for-render/preload'
 
-contextBridge.exposeInMainWorld('updater', {
-  check: () => ipcRenderer.invoke('updater:check'),
-
-  // 将 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)
-    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 会自动更新到"立即重启"
-  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)
-  }
-})
+// 必须暴露至 window.updaterAPI 命名空间，因为这是 getUpdater() 的默认查找路径
+contextBridge.exposeInMainWorld('updaterAPI', exposeUpdaterPreload(ipcRenderer))
 ```
 
 ---
@@ -257,6 +225,11 @@ contextBridge.exposeInMainWorld('updater', {
 ```vue
 <script setup lang="ts">
 import { ref, onMounted, onUnmounted } from 'vue'
+import { getUpdater, getRouterBase } from 'electron-updater-for-render/renderer'
+
+// 自动探测当前 Window 上下文对应的 History Base
+const routerBase = getRouterBase() 
+const updater = getUpdater()
 
 // 状态：'idle' | 'checking' | 'available' | 'downloading' | 'ready' | 'no-update'
 const status = ref<'idle' | 'checking' | 'available' | 'downloading' | 'ready' | 'no-update'>('idle')
@@ -269,15 +242,12 @@ let removeProgress: (() => void) | null = null
 let removeRestart: (() => void) | null = null
 let removeStatusChanged: (() => void) | null = null
 
-const getUpdater = () => (window as any).updater
+const updater = getUpdater()
 
 // ── 检查更新 ───────────────────────────────────────────────────────────────
 // check() 返回 { status: 'idle' | 'available' | 'ready', version, info }
 // 若状态为 'ready'，说明更新已下载完毕只待重启，直接跳过下载流程
 const checkUpdate = async () => {
-  const updater = getUpdater()
-  if (!updater) return
-
   status.value = 'checking'
   try {
     const res = await updater.check()
@@ -298,13 +268,10 @@ const checkUpdate = async () => {
 // ── 下载更新 ───────────────────────────────────────────────────────────────
 // 将 check() 返回的 info 对象传给 download()，避免主进程重复请求 latest.json
 const downloadUpdate = async () => {
-  const updater = getUpdater()
-  if (!updater) return
-
   status.value = 'downloading'
   progress.value = 0
 
-  removeProgress = updater.onProgress((percent: number) => {
+  removeProgress = updater.onDownloadProgress((percent: number) => {
     progress.value = percent
   })
 
@@ -321,14 +288,13 @@ const downloadUpdate = async () => {
 
 // ── 安装并重启 ─────────────────────────────────────────────────────────────
 const installUpdate = () => {
-  getUpdater()?.install()
+  updater.installAndRestart()
 }
 
 // ── 监听主进程主动推送的状态变更 ───────────────────────────────────────────
 // 场景：用户点击"稍后安装"后，日后主进程 onStatusChanged 触发时
 // UI 无需用户做任何操作，按钮自动变为"立即重启"
 const initStatusListener = () => {
-  const updater = getUpdater()
   if (updater?.onStatusChanged) {
     return updater.onStatusChanged((data: { status: string; version: string }) => {
       if (data.status === 'ready') {
@@ -342,7 +308,6 @@ const initStatusListener = () => {
 
 // ── 监听重启前通知 ─────────────────────────────────────────────────────────
 const initRestartListener = () => {
-  const updater = getUpdater()
   if (updater?.onBeforeRestart) {
     return updater.onBeforeRestart(() => {
       // 在此保存未提交的表单状态
@@ -407,31 +372,49 @@ onUnmounted(() => {
 
 本库完美支持 Electron 常用的文件加载模式（Hash）和现代单页应用路由模式（History）。
 
-### 1. Hash 模式（默认推荐）
-这是最稳健的选择，使用 Electron 标准的 `file://` 协议。
+### 1. Hash 模式 (推荐方案：零配置、零侵入)
+这是 Electron 环境下的**工业级标准实践**。它对物理路径不敏感，不需要配置任何 Base，前端项目完全不需要引入插件的任何 JS 逻辑。
 
-- **主进程**：无需任何额外配置（`routerMode` 默认为 `'hash'`）。
+- **主进程**：无需额外配置（`routerMode` 默认为 `'hash'`）。
 - **前端 (Vite)**：`vite.config.ts` 中的 `base` 设为 `'./'`（或不填）。
 - **前端 (Router)**：使用 `createWebHashHistory()`。
+- **优点**：真正的“零感知”，前端代码与热更新逻辑完全解耦。
 
-### 2. History 模式（企业级方案）
-支持美观的 URL 和标准浏览器重载行为。由于 `file://` 不支持标准路由解析，本库会自动启用自定义协议（默认 `app://`）进行转发。
+### 2. History 模式 (高级方案)
+支持美观的 URL 和标准浏览器刷新行为。由于 MPA 存在物理路径认知偏差，需要对齐基准路径（Base）。
 
 - **主进程**：
   ```typescript
   new RenderUpdater({
-    updateUrl: '...',
-    versionsDir: '...',
-    routerMode: 'history',   // 开启 History 路由支持
-    protocol: 'my-app'       // 可选：自定义协议名 (默认 'app')
+    // ...
+    routerMode: 'history',
+    protocol: 'my-app'  // 可选：自定义协议名 (默认 'app')
+  })
+  ```
+
+- **渲染层 (Router) - 选项 A：使用自动化助手 (推荐)**
+  引入插件提供的轻量级工具函数，自动探测当前窗口的物理基准：
+  ```typescript
+  import { getRouterBase } from 'electron-updater-for-render/renderer'
+  const router = createRouter({
+    history: createWebHistory(getRouterBase()), // 自动对齐 app:// 协议下的物理路径
+    routes: [...]
+  })
+  ```
+
+- **渲染层 (Router) - 选项 B：手动对齐 (零侵入)**
+  如果您不想在前端引入任何插件代码，可以手动指定与 `getLoadUrl()` 传入路径一致的字符串（需以 `.html/` 结尾）：
+  ```typescript
+  const router = createRouter({
+    history: createWebHistory('/index.html/'), 
+    routes: [...]
   })
   ```
-  > 💡 **全自动化**：协议注册和特权赋权逻辑已在库内部**全自动处理**，您无需编写任何 `registerSchemesAsPrivileged` 等繁琐代码。
 
-- **前端构建工具（Vite、Webpack 等）**：**关键配置** —— 必须将 **公共路径 (Public Path / Base)** 设置为 `/`，确保资源引用为绝对路径，防止在深层路由下刷新出现 404。
-  - **Vite**：`base: '/'`
-  - **Webpack**：`output.publicPath: '/'`
-- **前端路由 (Router)**：使用 `createWebHistory()`。
+### 3. 多页应用 (MPA) 支持
+- **多窗口多入口**：支持为不同窗口指定不同的 HTML 入口。
+- **History 模式刷新**：支持在 History 模式下进行页面刷新。
+- **基准路径探测**：配合 `getRouterBase()` 自动识别当前的路由基准路径。
 
 ---
 
@@ -443,6 +426,7 @@ onUnmounted(() => {
 |---|---|---|---|
 | `outDir` | `string` | ✅ | 构建输出目录 |
 | `updatesDir` | `string` | — | 更新包输出目录，默认 `./dist_updates` |
+| `rolloutRule` | `object` | — | 灰度分发规则字典。如 `{ deviceIds: ['UUID'] }` |
 | `version` | `string` | — | 显式指定版本号，优先级高于 `packageJsonPath` |
 | `packageJsonPath` | `string` | — | 自定义 `package.json` 路径，不填则自动读取 `process.cwd()/package.json` |
 | `asarName` | `string` | — | ASAR 文件名，默认 `renderer.asar` |
@@ -456,6 +440,9 @@ onUnmounted(() => {
 |---|---|---|---|
 | `updateUrl` | `string` | ✅ | 更新服务器根地址 |
 | `versionsDir` | `string` | ✅ | 本地 ASAR 版本存储目录 |
+| `identity` | `object` | — | 客户端身份标识，包含 `deviceId`，用于请求与灰度匹配 |
+| `allowPrerelease`| `boolean` | — | 是否允许检查预发布版本（遵循 semver 规则，如带 `-beta` 后缀） |
+| `requestOptions` | `object` | — | 自定义 HTTP 请求配置，包含 `headers` 和 `query` 参数 |
 | `publicKey` | `string` | — | RSA 公钥（PEM 格式），用于验证 ASAR 签名 |
 | `autoDownload` | `boolean` | — | 发现更新后自动下载，不弹窗询问。默认 `false` |
 | `autoPrompt` | `boolean` | — | 使用内置原生弹窗引导更新。默认 `true` |
@@ -471,14 +458,14 @@ onUnmounted(() => {
 
 ### `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` |
+| `check()` | `Promise<CheckResult>` | 检查更新。返回 `{ updateAvailable, status, version, info }`。状态为 `'idle' \| 'available' \| 'ready'` |
+| `download(info?, onProgress?)` | `Promise<void>` | 下载更新。建议传入 `check()` 返回的 `info` 对象以防止版本竞争 |
+| `getLoadUrl(entry?)` | `string` | 返回加载最新 ASAR 的 URL (`app://renderer/` 或 `file://...`)。`entry` 默认为 `index.html`。若无更新则返回空字符串 |
+| `installAndRestart()` | `Promise<void>` | 应用更新并重启应用 |
+| `checkForUpdatesAndNotify()` | `Promise<void>` | 一站式：检查 + 提示 + 下载 + 安装（使用内置原生对话框） |
+| `setUpdatePending(version)` | `void` | 将某版本标记为已就绪并等待重启。会触发 `onStatusChanged` |
 | `useVersion(version)` | `void` | 立即切换磁盘和内存双重版本指针 |
 | `activeVersion` | `string`（getter） | 当前内存中正在运行的版本（本次会话） |
 | `pendingVersion` | `string`（getter） | 磁盘上最新已下载版本 |

package/Readme.md

@@ -11,9 +11,9 @@ Unlike `electron-updater` which re-downloads the entire app installer, this libr
 ## 🚀 Features
 
 - **Dual-Track Update Mode**: Built-in native OS dialogs *or* a fully custom frontend progress UI via IPC — your choice
-- **Three-State Check System**: `check()` returns `idle / available / ready` — the UI always knows whether to show "Download" or "Restart", eliminating redundant download prompts
-- **Ready-to-Install State**: When a user clicks "Later", the downloaded update is remembered on disk. On next launch/refresh, the UI automatically jumps to "Restart Now" — no re-download needed
-- **Real-time Status Push**: `onStatusChanged` hook lets the main process proactively notify the renderer when an update becomes ready (e.g. after silent background download)
+- **Three-State Check System**: `check()` distinctly returns `idle / available / ready`, allowing the UI to accurately distinguish between "No Updates", "Download Required", and "Ready to Restart" for a seamless state transition flow
+- **Ready-State Persistence**: Intelligently detects locally cached complete downloads. Even if the user delays installation or refreshes the page, the update state remains "Ready", ensuring an uninterrupted user journey
+- **Real-time Status Push**: The `onStatusChanged` hook enables the main process to proactively notify the renderer layer to refresh the UI when updates are locally ready
 - **Force Update**: Push `forceUpdate: 'prompt'` or `'silent'` from your server for P0 hotfixes that bypass the "Later" button entirely
 - **Graceful Restart Hook**: `onBeforeRestart` async hook lets the renderer save unsaved state before `app.relaunch()`
 - **Concurrency Lock**: Prevents race conditions between auto-check-on-boot and manual-trigger-on-click
@@ -21,7 +21,12 @@ Unlike `electron-updater` which re-downloads the entire app installer, this libr
 - **Stream Pipeline Download**: Node.js `stream/promises pipeline` + `Transform` — zero memory leaks, full backpressure support
 - **Zero-config Version Detection**: Auto-reads version from `process.cwd()/package.json` — no extra config required
 - **Separate Build Commands**: Normal `npm run build` is untouched. Only `npm run build:update` triggers ASAR packaging
-- **History Mode SPA Support**: Built-in custom protocol handler (`app://`) for Vue/React History mode routing — zero boilerplate
+- **History Mode Support**: Built-in support for Vue/React History router mode.
+- **Multi-Page Application (MPA)**: Support for loading multiple entry points via `getLoadUrl(entry)`.
+- **Simplified SDK**: Unified exports for `/main`, `/preload`, and `/renderer`, including `getRouterBase`.
+- **Precision Canary Releases**: Use `identity.deviceId` and `rolloutRule` to drop updates silently to a whitelist of device IDs.
+- **Semver Beta Channels**: Built-in Beta/RC channel toggling via `allowPrerelease` guarantees Stable users are isolated from beta patches.
+- **Dynamic Request Gateways**: Send custom Authenticated Headers (e.g., Oauth/Bearer tokens) and Queries via `requestOptions` when checking for updates.
 
 ---
 
@@ -84,6 +89,9 @@ import { defineConfig } from 'electron-updater-for-render/builder'
 export default defineConfig({
   outDir: './dist',              // Required: Your build output directory
   updatesDir: './dist_updates',  // Optional: where to write update packages (default: './dist_updates')
+  // rolloutRule: {
+  //   deviceIds: ['YOUR_DEVICE_ID'] // Optional: Whitelist of device IDs for Canary/Staged rollouts
+  // },
   // version: '1.2.3'           // Optional: explicit version (overrides package.json)
   // packageJsonPath: './package.json'  // Optional: custom package.json path
   // forceUpdate: 'prompt'      // Optional: 'prompt' | 'silent' — for P0 mandatory rollouts ONLY
@@ -146,63 +154,48 @@ The server must serve these files over HTTP(S). The client will fetch:
 
 ```typescript
 // src/main/index.ts
-import { app, BrowserWindow, ipcMain } from 'electron'
+import { app, BrowserWindow } from 'electron'
 import { join } from 'path' 
-import { RenderUpdater } from 'electron-updater-for-render'
+import { RenderUpdater, setupUpdaterIPC } from 'electron-updater-for-render/main'
 
 const updater = new RenderUpdater({
   updateUrl: 'https://your-server.com/auto-updates', // Required: base URL for updates
   versionsDir: join(app.getPath('userData'), 'versions'), // Required: local version storage
+  
+  // Cloud Rollout Rules Support
+  identity: { deviceId: 'USER_LOCAL_UUID' },
+  // Beta Channel Support
+  allowPrerelease: true,
+  // Custom Authenticated Gateway
+  requestOptions: {
+    headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
+  },
+
   maxVersionsToKeep: 2, // Optional: keep 2 old versions for rollback (default: 2)
 
-  // Optional: give the renderer time to save state before restart
+  // Optional: Delay the restart by 2 seconds to give the Vue renderer time to save state
   onBeforeRestart: async () => {
-    const [win] = BrowserWindow.getAllWindows()
-    if (win) {
-      win.webContents.send('updater:before-restart')
-      await new Promise(resolve => setTimeout(resolve, 2000))
-    }
-  },
-
-  // Optional: proactively push status changes to the renderer UI
-  // Triggered when a pending update is recorded (e.g. after "Later" is clicked)
-  onStatusChanged: (data) => {
-    const [win] = BrowserWindow.getAllWindows()
-    if (win) {
-      win.webContents.send('updater:status-changed', data)
-    }
+    await new Promise(resolve => setTimeout(resolve, 2000))
   }
 })
 
+// 🎉 Automatically sets up the entire IPC bus in one line
+// It exposes API handles and automatically broadcasts progress, status, and restart events to all webContents
+setupUpdaterIPC(updater)
+
 app.whenReady().then(async () => {
   const mainWindow = new BrowserWindow({
     webPreferences: { preload: join(__dirname, '../preload/index.js') }
-    // ...
   })
 
-  // Load the latest downloaded ASAR, fallback to dev server if no update downloaded yet
-  const loadUrl = updater.getLoadUrl()
-  mainWindow.loadURL(loadUrl || 'http://localhost:5173')
+  // Load the latest downloaded ASAR, fallback to local dist if no update is available
+  // Supports multi-page entries (default: 'index.html')
+  const loadUrl = updater.getLoadUrl('login/index.html')
+  mainWindow.loadURL(loadUrl || `file://${join(__dirname, '../renderer/login/index.html')}`)
 
   // Auto-check on startup (respects forceUpdate, shows dialogs if autoPrompt: true)
   setTimeout(() => updater.checkForUpdatesAndNotify(), 3000)
 })
-
-// Expose manual update controls for custom frontend UI
-ipcMain.handle('updater:check', () => updater.check())
-
-// ⚠️ IMPORTANT: The first argument must be UpdateInfo (forwarded from the renderer),
-//               and the second argument is the progress callback.
-ipcMain.handle('updater:download', async (event, info) =>
-  updater.download(info, (percent) => {
-    BrowserWindow.getAllWindows()[0]?.webContents.send('updater:progress', percent)
-  })
-)
-
-ipcMain.on('updater:install', () => {
-  app.relaunch()
-  app.quit()
-})
 ```
 
 ---
@@ -212,36 +205,10 @@ ipcMain.on('updater:install', () => {
 ```typescript
 // src/preload/index.ts
 import { contextBridge, ipcRenderer } from 'electron'
+import { exposeUpdaterPreload } from 'electron-updater-for-render/preload'
 
-contextBridge.exposeInMainWorld('updater', {
-  check: () => ipcRenderer.invoke('updater:check'),
-
-  // Forward the UpdateInfo object returned by check() so the main process
-  // knows which version to download without re-fetching 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)
-    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)
-  },
-
-  // Listen to proactive status pushes from the main process
-  // (e.g. when a background download finishes after user clicked "Later")
-  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)
-  }
-})
+// Expose the API under the 'updaterAPI' namespace, as expected by getUpdater()
+contextBridge.exposeInMainWorld('updaterAPI', exposeUpdaterPreload(ipcRenderer))
 ```
 
 ---
@@ -256,6 +223,11 @@ The following example demonstrates the complete update flow with:
 ```vue
 <script setup lang="ts">
 import { ref, onMounted, onUnmounted } from 'vue'
+import { getUpdater, getRouterBase } from 'electron-updater-for-render/renderer'
+
+// Automatically detect the correct context-aware History base for MPA
+const routerBase = getRouterBase() 
+const updater = getUpdater()
 
 // Status: 'idle' | 'checking' | 'available' | 'downloading' | 'ready' | 'no-update'
 const status = ref<'idle' | 'checking' | 'available' | 'downloading' | 'ready' | 'no-update'>('idle')
@@ -268,15 +240,12 @@ let removeProgress: (() => void) | null = null
 let removeRestart: (() => void) | null = null
 let removeStatusChanged: (() => void) | null = null
 
-const getUpdater = () => (window as any).updater
+const updater = getUpdater()
 
 // ── Check for updates ──────────────────────────────────────────────────────
 // check() returns { status: 'idle' | 'available' | 'ready', version, info }
 // 'ready' means an update is already downloaded and waiting for restart.
 const checkUpdate = async () => {
-  const updater = getUpdater()
-  if (!updater) return
-
   status.value = 'checking'
   try {
     const res = await updater.check()
@@ -298,13 +267,10 @@ const checkUpdate = async () => {
 // Pass the UpdateInfo object from check() so the main process doesn't need
 // to re-fetch latest.json, preventing version mismatches.
 const downloadUpdate = async () => {
-  const updater = getUpdater()
-  if (!updater) return
-
   status.value = 'downloading'
   progress.value = 0
 
-  removeProgress = updater.onProgress((percent: number) => {
+  removeProgress = updater.onDownloadProgress((percent: number) => {
     progress.value = percent
   })
 
@@ -321,14 +287,13 @@ const downloadUpdate = async () => {
 
 // ── Install & restart ──────────────────────────────────────────────────────
 const installUpdate = () => {
-  getUpdater()?.install()
+  updater.installAndRestart()
 }
 
 // ── Real-time status push from main process ───────────────────────────────
 // When a download completes in the background, the main process fires
 // onStatusChanged. We update the UI immediately without any user action.
 const initStatusListener = () => {
-  const updater = getUpdater()
   if (updater?.onStatusChanged) {
     return updater.onStatusChanged((data: { status: string; version: string }) => {
       if (data.status === 'ready') {
@@ -342,7 +307,6 @@ const initStatusListener = () => {
 
 // ── Graceful restart ───────────────────────────────────────────────────────
 const initRestartListener = () => {
-  const updater = getUpdater()
   if (updater?.onBeforeRestart) {
     return updater.onBeforeRestart(() => {
       // Save any unsaved state here before the app relaunches
@@ -407,31 +371,49 @@ onUnmounted(() => {
 
 The library supports both standard Electron file-loading (Hash) and modern SPA routing (History) via custom protocols.
 
-### 1. Hash Mode (Default)
-Recommended for simple apps. It uses standard `file://` protocol.
+### 1. Hash Mode (Recommended: Zero-Config, Zero-Intrusion)
+The **industry standard** for Electron applications. It is resilient to physical path changes, requires no base configuration, and needs zero plugin-related JS in your frontend.
 
-- **Main Process**: No extra config needed (defaults to `hash`).
+- **Main Process**: No extra config needed (defaults to `'hash'`).
 - **Renderer (Vite)**: Set `base: './'` (or omit) in `vite.config.ts`.
 - **Renderer (Router)**: Use `createWebHashHistory()`.
+- **Pros**: Pure decoupling; your frontend project remains completely unaware of the updater's existence.
 
-### 2. History Mode (Modern)
-Supports clean URLs and standard browser refresh behavior. Uses a custom protocol (default `app://`) to bypass `file://` limitations.
+### 2. History Mode (Advanced)
+Supports clean URLs and native browser refresh behavior. Due to physical path context in MPAs, the router needs to be aligned with the base path.
 
 - **Main Process**: 
   ```typescript
   new RenderUpdater({
-    updateUrl: '...',
-    versionsDir: '...',
-    routerMode: 'history',   // Enable history mode
-    protocol: 'my-app'       // Optional: custom protocol name (default: 'app')
+    // ...
+    routerMode: 'history',
+    protocol: 'my-app'  // Optional: custom protocol name (default: 'app')
+  })
+  ```
+
+- **Renderer (Router) - Option A: Use Automated Helper (Recommended)**
+  Use our lightweight helper to automatically sense the physical base of the current window:
+  ```typescript
+  import { getRouterBase } from 'electron-updater-for-render/renderer'
+  const router = createRouter({
+    history: createWebHistory(getRouterBase()), // Auto-aligns with the app:// protocol path
+    routes: [...]
+  })
+  ```
+
+- **Renderer (Router) - Option B: Manual Alignment (Zero-Intrusion)**
+  If you prefer not to import any plugin JS, you can manually provide a string that matches the path passed to `getLoadUrl()` (must end with `.html/`):
+  ```typescript
+  const router = createRouter({
+    history: createWebHistory('/index.html/'), 
+    routes: [...]
   })
   ```
-  > 💡 **No Boilerplate**: Protocol registration and privileged scheme setup are **automated** internally. You don't need to call `registerSchemesAsPrivileged` manually.
 
-- **Renderer (Build Tool — Vite, Webpack, etc.)**: **CRITICAL** — set your build tool's public base path to `/` for absolute asset URLs. This prevents 404 errors when refreshing on deep-nested routes.
-  - **Vite**: `base: '/'`
-  - **Webpack**: `output.publicPath: '/'`
-- **Renderer (Router)**: Use `createWebHistory()`.
+### 3. Multi-Page Application (MPA)
+- **Multi-window Support**: Load different entry points for different windows.
+- **History Refresh Support**: Supports browser refresh in History mode.
+- **Base Path Detection**: Use `getRouterBase()` to automatically identify the current routing base.
 
 ---
 
@@ -443,6 +425,7 @@ Supports clean URLs and standard browser refresh behavior. Uses a custom protoco
 |---|---|---|---|
 | `outDir` | `string` | ✅ | Vite/Webpack build output directory |
 | `updatesDir` | `string` | — | Output directory for update packages. Default: `./dist_updates` |
+| `rolloutRule` | `object` | — | Target whitelists: `{ deviceIds: string[] }`. |
 | `version` | `string` | — | Explicit version string, overrides `packageJsonPath` |
 | `packageJsonPath` | `string` | — | Custom path to `package.json`. Defaults to `process.cwd()/package.json` |
 | `asarName` | `string` | — | ASAR filename. Default: `renderer.asar` |
@@ -456,6 +439,9 @@ Supports clean URLs and standard browser refresh behavior. Uses a custom protoco
 |---|---|---|---|
 | `updateUrl` | `string` | ✅ | Base URL where update files are hosted |
 | `versionsDir` | `string` | ✅ | Local directory to store downloaded ASAR versions |
+| `identity` | `object` | — | Fingerprint for rollouts logic (must include `deviceId`). |
+| `allowPrerelease` | `boolean` | — | Skips prerelease tags if false. |
+| `requestOptions` | `object` | — | Custom HTTP headers and query params. |
 | `publicKey` | `string` | — | RSA public key (PEM) for signature verification |
 | `autoDownload` | `boolean` | — | Auto-download without asking. Default: `false` |
 | `autoPrompt` | `boolean` | — | Show built-in native dialogs. Default: `true` |
@@ -475,7 +461,7 @@ Supports clean URLs and standard browser refresh behavior. Uses a custom protoco
 |---|---|---|
 | `check()` | `Promise<CheckResult>` | Check for updates. Returns `{ updateAvailable, status, version, info }`. Status is `'idle' \| 'available' \| 'ready'` |
 | `download(info?, onProgress?)` | `Promise<void>` | Download the update. Pass the `info` object from `check()` to avoid redundant network requests |
-| `getLoadUrl()` | `string` | Returns the URL to load the latest ASAR (`app://renderer/` or `file://...`). Empty string if no update downloaded |
+| `getLoadUrl(entry?)` | `string` | Returns the URL to load the latest ASAR (`app://renderer/` or `file://...`). `entry` defaults to `index.html`. Returns empty string if no update downloaded |
 | `installAndRestart()` | `Promise<void>` | Apply the pending update and relaunch the app |
 | `checkForUpdatesAndNotify()` | `Promise<void>` | All-in-one: check + prompt + download + install with built-in native dialogs |
 | `setUpdatePending(version)` | `void` | Mark a version as downloaded and pending restart. Also fires `onStatusChanged` |

package/dist/main/index.cjs

@@ -103,13 +103,42 @@ var RouterHandler = class _RouterHandler {
             return new Response("ASAR Not Found", { status: 404 });
           }
           let targetFile = import_path.default.join(asarPath, relativePath);
-          const ext = import_path.default.extname(relativePath);
-          if (!relativePath || relativePath === "/") {
-            targetFile = import_path.default.join(asarPath, "index.html");
-          } else if (ext === "") {
-            targetFile = import_path.default.join(asarPath, "index.html");
-          } else if (!import_fs.default.existsSync(targetFile)) {
-            targetFile = import_path.default.join(asarPath, "index.html");
+          const isFileExist = import_fs.default.existsSync(targetFile) && import_fs.default.statSync(targetFile).isFile();
+          if (!isFileExist) {
+            let rawPath = relativePath.endsWith("/") ? relativePath.slice(0, -1) : relativePath;
+            let ext = import_path.default.extname(rawPath).toLowerCase();
+            if (ext && ext !== ".html") {
+              return new Response("Not Found", { status: 404 });
+            }
+            let fallbackSearchPath = rawPath;
+            let foundFallback = false;
+            while (true) {
+              let checkFile = "";
+              if (fallbackSearchPath !== "") {
+                checkFile = import_path.default.join(asarPath, fallbackSearchPath.endsWith(".html") ? fallbackSearchPath : fallbackSearchPath + ".html");
+                if (import_fs.default.existsSync(checkFile) && import_fs.default.statSync(checkFile).isFile()) {
+                  targetFile = checkFile;
+                  foundFallback = true;
+                  break;
+                }
+              }
+              checkFile = import_path.default.join(asarPath, fallbackSearchPath, "index.html");
+              if (import_fs.default.existsSync(checkFile) && import_fs.default.statSync(checkFile).isFile()) {
+                targetFile = checkFile;
+                foundFallback = true;
+                break;
+              }
+              if (fallbackSearchPath === "") break;
+              const lastSlashIndex = fallbackSearchPath.lastIndexOf("/");
+              if (lastSlashIndex === -1) {
+                fallbackSearchPath = "";
+              } else {
+                fallbackSearchPath = fallbackSearchPath.substring(0, lastSlashIndex);
+              }
+            }
+            if (!foundFallback) {
+              return new Response("Not Found", { status: 404 });
+            }
           }
           const response = await import_electron.net.fetch((0, import_url.pathToFileURL)(targetFile).toString());
           const headers = new Headers(response.headers);
@@ -322,15 +351,24 @@ var RenderUpdater = class {
   get isUpdatePending() {
     return import_semver.default.gt(this._diskVersion || "0.0.0", this._activeVersion || "0.0.0");
   }
-  getLoadUrl() {
+  /**
+   * 获取加载 URL。
+   * @param entry 入口文件路径，默认为 'index.html'。
+   * 对于多页应用 (MPA)，可以传入 'login/index.html' 等。
+   */
+  getLoadUrl(entry = "index.html") {
     try {
       if (this._activeVersion && this._activeVersion !== "0.0.0") {
         const asarPath = import_path2.default.join(this.versionsDir, this._activeVersion, "renderer.asar");
         if (import_original_fs.default.existsSync(asarPath)) {
           if (this.routerMode === "history") {
-            return `${this.protocolName}://renderer/`;
+            if (entry === "index.html" || entry === "/index.html") {
+              return `${this.protocolName}://renderer/`;
+            }
+            const normalizedEntry = entry.startsWith("/") ? entry.slice(1) : entry;
+            return `${this.protocolName}://renderer/${normalizedEntry}/`;
           }
-          return `file://${asarPath}/index.html`;
+          return `file://${asarPath}/${entry}`;
         }
       }
     } catch (e) {
@@ -628,22 +666,28 @@ ${info.releaseNotes || "\u65E0\u8BE6\u7EC6\u8BB0\u5F55\u3002"}`,
 };
 function setupUpdaterIPC(updater) {
   import_electron3.ipcMain.handle("updater:check", () => updater.check());
-  import_electron3.ipcMain.handle("updater:download", () => updater.download());
+  import_electron3.ipcMain.handle("updater:download", (_, info) => updater.download(info));
   import_electron3.ipcMain.handle("updater:installAndRestart", () => updater.installAndRestart());
   import_electron3.ipcMain.on("updater:useVersion", (_, version) => updater.useVersion(version));
+  const originalOnDownloadProgress = updater.onDownloadProgress;
   updater.onDownloadProgress = (percent) => {
+    if (originalOnDownloadProgress) originalOnDownloadProgress(percent);
     const { webContents } = require("electron");
     webContents.getAllWebContents().forEach((wc) => {
       wc.send("updater:onDownloadProgress", percent);
     });
   };
+  const originalOnStatusChanged = updater.onStatusChanged;
   updater.onStatusChanged = (status) => {
+    if (originalOnStatusChanged) originalOnStatusChanged(status);
     const { webContents } = require("electron");
     webContents.getAllWebContents().forEach((wc) => {
       wc.send("updater:onStatusChanged", status);
     });
   };
+  const originalOnBeforeRestart = updater.onBeforeRestart;
   updater.onBeforeRestart = () => {
+    if (originalOnBeforeRestart) originalOnBeforeRestart();
     const { webContents } = require("electron");
     webContents.getAllWebContents().forEach((wc) => {
       wc.send("updater:onBeforeRestart");

package/dist/main/index.d.ts

@@ -30,7 +30,12 @@ export declare class RenderUpdater {
     get activeVersion(): string;
     get pendingVersion(): string;
     get isUpdatePending(): boolean;
-    getLoadUrl(): string;
+    /**
+     * 获取加载 URL。
+     * @param entry 入口文件路径，默认为 'index.html'。
+     * 对于多页应用 (MPA)，可以传入 'login/index.html' 等。
+     */
+    getLoadUrl(entry?: string): string;
     check(): Promise<{
         updateAvailable: boolean;
         version?: string;

package/dist/main/index.js

@@ -75,13 +75,42 @@ var RouterHandler = class _RouterHandler {
             return new Response("ASAR Not Found", { status: 404 });
           }
           let targetFile = path.join(asarPath, relativePath);
-          const ext = path.extname(relativePath);
-          if (!relativePath || relativePath === "/") {
-            targetFile = path.join(asarPath, "index.html");
-          } else if (ext === "") {
-            targetFile = path.join(asarPath, "index.html");
-          } else if (!fs.existsSync(targetFile)) {
-            targetFile = path.join(asarPath, "index.html");
+          const isFileExist = fs.existsSync(targetFile) && fs.statSync(targetFile).isFile();
+          if (!isFileExist) {
+            let rawPath = relativePath.endsWith("/") ? relativePath.slice(0, -1) : relativePath;
+            let ext = path.extname(rawPath).toLowerCase();
+            if (ext && ext !== ".html") {
+              return new Response("Not Found", { status: 404 });
+            }
+            let fallbackSearchPath = rawPath;
+            let foundFallback = false;
+            while (true) {
+              let checkFile = "";
+              if (fallbackSearchPath !== "") {
+                checkFile = path.join(asarPath, fallbackSearchPath.endsWith(".html") ? fallbackSearchPath : fallbackSearchPath + ".html");
+                if (fs.existsSync(checkFile) && fs.statSync(checkFile).isFile()) {
+                  targetFile = checkFile;
+                  foundFallback = true;
+                  break;
+                }
+              }
+              checkFile = path.join(asarPath, fallbackSearchPath, "index.html");
+              if (fs.existsSync(checkFile) && fs.statSync(checkFile).isFile()) {
+                targetFile = checkFile;
+                foundFallback = true;
+                break;
+              }
+              if (fallbackSearchPath === "") break;
+              const lastSlashIndex = fallbackSearchPath.lastIndexOf("/");
+              if (lastSlashIndex === -1) {
+                fallbackSearchPath = "";
+              } else {
+                fallbackSearchPath = fallbackSearchPath.substring(0, lastSlashIndex);
+              }
+            }
+            if (!foundFallback) {
+              return new Response("Not Found", { status: 404 });
+            }
           }
           const response = await net.fetch(pathToFileURL(targetFile).toString());
           const headers = new Headers(response.headers);
@@ -294,15 +323,24 @@ var RenderUpdater = class {
   get isUpdatePending() {
     return semver.gt(this._diskVersion || "0.0.0", this._activeVersion || "0.0.0");
   }
-  getLoadUrl() {
+  /**
+   * 获取加载 URL。
+   * @param entry 入口文件路径，默认为 'index.html'。
+   * 对于多页应用 (MPA)，可以传入 'login/index.html' 等。
+   */
+  getLoadUrl(entry = "index.html") {
     try {
       if (this._activeVersion && this._activeVersion !== "0.0.0") {
         const asarPath = path2.join(this.versionsDir, this._activeVersion, "renderer.asar");
         if (fs2.existsSync(asarPath)) {
           if (this.routerMode === "history") {
-            return `${this.protocolName}://renderer/`;
+            if (entry === "index.html" || entry === "/index.html") {
+              return `${this.protocolName}://renderer/`;
+            }
+            const normalizedEntry = entry.startsWith("/") ? entry.slice(1) : entry;
+            return `${this.protocolName}://renderer/${normalizedEntry}/`;
           }
-          return `file://${asarPath}/index.html`;
+          return `file://${asarPath}/${entry}`;
         }
       }
     } catch (e) {
@@ -600,22 +638,28 @@ ${info.releaseNotes || "\u65E0\u8BE6\u7EC6\u8BB0\u5F55\u3002"}`,
 };
 function setupUpdaterIPC(updater) {
   ipcMain.handle("updater:check", () => updater.check());
-  ipcMain.handle("updater:download", () => updater.download());
+  ipcMain.handle("updater:download", (_, info) => updater.download(info));
   ipcMain.handle("updater:installAndRestart", () => updater.installAndRestart());
   ipcMain.on("updater:useVersion", (_, version) => updater.useVersion(version));
+  const originalOnDownloadProgress = updater.onDownloadProgress;
   updater.onDownloadProgress = (percent) => {
+    if (originalOnDownloadProgress) originalOnDownloadProgress(percent);
     const { webContents } = __require("electron");
     webContents.getAllWebContents().forEach((wc) => {
       wc.send("updater:onDownloadProgress", percent);
     });
   };
+  const originalOnStatusChanged = updater.onStatusChanged;
   updater.onStatusChanged = (status) => {
+    if (originalOnStatusChanged) originalOnStatusChanged(status);
     const { webContents } = __require("electron");
     webContents.getAllWebContents().forEach((wc) => {
       wc.send("updater:onStatusChanged", status);
     });
   };
+  const originalOnBeforeRestart = updater.onBeforeRestart;
   updater.onBeforeRestart = () => {
+    if (originalOnBeforeRestart) originalOnBeforeRestart();
     const { webContents } = __require("electron");
     webContents.getAllWebContents().forEach((wc) => {
       wc.send("updater:onBeforeRestart");

package/dist/preload/index.cjs

@@ -26,18 +26,24 @@ module.exports = __toCommonJS(preload_exports);
 function exposeUpdaterPreload(ipcRenderer) {
   return {
     check: () => ipcRenderer.invoke("updater:check"),
-    download: () => ipcRenderer.invoke("updater:download"),
+    download: (info) => ipcRenderer.invoke("updater:download", info),
     installAndRestart: () => ipcRenderer.invoke("updater:installAndRestart"),
     useVersion: (version) => ipcRenderer.send("updater:useVersion", version),
     // 监听事件
     onDownloadProgress: (callback) => {
-      ipcRenderer.on("updater:onDownloadProgress", (_, percent) => callback(percent));
+      const fn = (_, percent) => callback(percent);
+      ipcRenderer.on("updater:onDownloadProgress", fn);
+      return () => ipcRenderer.removeListener("updater:onDownloadProgress", fn);
     },
     onStatusChanged: (callback) => {
-      ipcRenderer.on("updater:onStatusChanged", (_, data) => callback(data));
+      const fn = (_, data) => callback(data);
+      ipcRenderer.on("updater:onStatusChanged", fn);
+      return () => ipcRenderer.removeListener("updater:onStatusChanged", fn);
     },
     onBeforeRestart: (callback) => {
-      ipcRenderer.on("updater:onBeforeRestart", () => callback());
+      const fn = () => callback();
+      ipcRenderer.on("updater:onBeforeRestart", fn);
+      return () => ipcRenderer.removeListener("updater:onBeforeRestart", fn);
     }
   };
 }

package/dist/preload/index.d.ts

@@ -1,13 +1,13 @@
 import type { IpcRenderer } from 'electron';
 export declare function exposeUpdaterPreload(ipcRenderer: IpcRenderer): {
     check: () => Promise<any>;
-    download: () => Promise<any>;
+    download: (info?: any) => Promise<any>;
     installAndRestart: () => Promise<any>;
     useVersion: (version: string) => void;
-    onDownloadProgress: (callback: (percent: number) => void) => void;
+    onDownloadProgress: (callback: (percent: number) => void) => () => Electron.IpcRenderer;
     onStatusChanged: (callback: (data: {
         status: "ready" | "available" | "idle";
         version: string;
-    }) => void) => void;
-    onBeforeRestart: (callback: () => void) => void;
+    }) => void) => () => Electron.IpcRenderer;
+    onBeforeRestart: (callback: () => void) => () => Electron.IpcRenderer;
 };

package/dist/preload/index.js

@@ -2,18 +2,24 @@
 function exposeUpdaterPreload(ipcRenderer) {
   return {
     check: () => ipcRenderer.invoke("updater:check"),
-    download: () => ipcRenderer.invoke("updater:download"),
+    download: (info) => ipcRenderer.invoke("updater:download", info),
     installAndRestart: () => ipcRenderer.invoke("updater:installAndRestart"),
     useVersion: (version) => ipcRenderer.send("updater:useVersion", version),
     // 监听事件
     onDownloadProgress: (callback) => {
-      ipcRenderer.on("updater:onDownloadProgress", (_, percent) => callback(percent));
+      const fn = (_, percent) => callback(percent);
+      ipcRenderer.on("updater:onDownloadProgress", fn);
+      return () => ipcRenderer.removeListener("updater:onDownloadProgress", fn);
     },
     onStatusChanged: (callback) => {
-      ipcRenderer.on("updater:onStatusChanged", (_, data) => callback(data));
+      const fn = (_, data) => callback(data);
+      ipcRenderer.on("updater:onStatusChanged", fn);
+      return () => ipcRenderer.removeListener("updater:onStatusChanged", fn);
     },
     onBeforeRestart: (callback) => {
-      ipcRenderer.on("updater:onBeforeRestart", () => callback());
+      const fn = () => callback();
+      ipcRenderer.on("updater:onBeforeRestart", fn);
+      return () => ipcRenderer.removeListener("updater:onBeforeRestart", fn);
     }
   };
 }

package/dist/renderer/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/renderer/index.ts
 var renderer_exports = {};
 __export(renderer_exports, {
+  getRouterBase: () => getRouterBase,
   getUpdater: () => getUpdater
 });
 module.exports = __toCommonJS(renderer_exports);
@@ -33,7 +34,17 @@ function getUpdater(namespace = "updaterAPI") {
   }
   return api;
 }
+function getRouterBase() {
+  if (typeof window === "undefined") return "/";
+  const pathname = window.location.pathname;
+  const htmlIndex = pathname.toLowerCase().lastIndexOf(".html");
+  if (htmlIndex !== -1) {
+    return pathname.substring(0, htmlIndex + 6);
+  }
+  return "/";
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  getRouterBase,
   getUpdater
 });

package/dist/renderer/index.d.ts

@@ -6,18 +6,25 @@ export interface UpdaterClientAPI {
         info?: UpdateInfo;
         status: 'idle' | 'available' | 'ready';
     }>;
-    download(): Promise<void>;
+    download(info?: UpdateInfo): Promise<void>;
     installAndRestart(): Promise<void>;
     useVersion(version: string): void;
-    onDownloadProgress(callback: (percent: number) => void): void;
+    onDownloadProgress(callback: (percent: number) => void): () => void;
     onStatusChanged(callback: (data: {
         status: 'ready' | 'available' | 'idle';
         version: string;
-    }) => void): void;
-    onBeforeRestart(callback: () => void): void;
+    }) => void): () => void;
+    onBeforeRestart(callback: () => void): () => void;
 }
 /**
  * Ensures the updater preload API is accessible and typed.
  * This should only be used in the renderer process (e.g. standard Vue/React contexts).
  */
 export declare function getUpdater(namespace?: string): UpdaterClientAPI;
+/**
+ * 自动探测当前页面的路由基准路径 (Base URL)
+ * 专门用于解决多页面 (MPA) 在 History 模式下刷新后 404 的问题。
+ * 例如：当 Electron 加载的是 app://renderer/login/index.html/ 时，
+ * 本函数将返回 "/login/index.html/"，您可以直接将其传给 createWebHistory()。
+ */
+export declare function getRouterBase(): string;

package/dist/renderer/index.js

@@ -9,6 +9,16 @@ function getUpdater(namespace = "updaterAPI") {
   }
   return api;
 }
+function getRouterBase() {
+  if (typeof window === "undefined") return "/";
+  const pathname = window.location.pathname;
+  const htmlIndex = pathname.toLowerCase().lastIndexOf(".html");
+  if (htmlIndex !== -1) {
+    return pathname.substring(0, htmlIndex + 6);
+  }
+  return "/";
+}
 export {
+  getRouterBase,
   getUpdater
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "electron-updater-for-render",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.1",
   "description": "A lightweight incremental updater for Electron renderer processes",
   "type": "module",
   "bin": {