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

package/README.zh-CN.md

@@ -275,6 +275,38 @@ const installUpdate = () => {
 
 ---
 
+## 🛣️ 路由模式配置 (Hash vs History)
+
+本库完美支持 Electron 常用的文件加载模式（Hash）和现代单页应用路由模式（History）。
+
+### 1. Hash 模式（默认推荐）
+这是最稳健的选择，使用 Electron 标准的 `file://` 协议。
+
+- **主进程**：无需任何额外配置（`routerMode` 默认为 `'hash'`）。
+- **前端 (Vite)**：`vite.config.ts` 中的 `base` 设为 `'./'`（或不填）。
+- **前端 (Router)**：使用 `createWebHashHistory()`。
+
+### 2. History 模式（企业级方案）
+支持美观的 URL 和标准浏览器重载行为。由于 `file://` 不支持标准路解析，本库会自动启用自定义协议（默认 `app://`）进行转发。
+
+- **主进程**：
+  ```typescript
+  new RenderUpdater({
+    updateUrl: '...',
+    versionsDir: '...',
+    routerMode: 'history',   // 开启 History 路由支持
+    protocol: 'my-app'       // 可选：自定义协议名 (默认 'app')
+  })
+  ```
+  > 💡 **全自动化：** 协议注册和特权赋权逻辑已在库内部**全自动处理**，您无需在顶层编写任何 `registerSchemesAsPrivileged` 等繁琐代码。
+
+- **前端构建工具 (Vite, Webpack, 等)**：**关键配置** —— 您必须将构建工具的 **公共路径 (Public Path / Base)** 设置为 `/`。这是为了确保生成的资源引用（JS/CSS/图片）为绝对路径，防止在深层路由（如 `/home/settings`）下刷新页面时出现资源加载 404。
+  - **Vite**：`base: '/'`
+  - **Webpack**：`output.publicPath: '/'`
+- **前端路由 (Router)**：使用 `createWebHistory()`。
+
+---
+
 ## ⚙️ API 参考
 
 ### `BuilderOptions`（CLI 配置参数）
@@ -305,6 +337,8 @@ const installUpdate = () => {
 | `onDownloadComplete` | `function` | — | 下载完成钩子：`(info, doInstall) => void` |
 | `onError` | `function` | — | 错误回调：`(error: Error) => void` |
 | `onBeforeRestart` | `async function` | — | `app.relaunch()` 前的异步钩子，可用于保存状态 |
+| `routerMode` | `'hash' \| 'history'` | — | 路由模式选择。默认 `'hash'` |
+| `protocol` | `string` | — | History 模式下的自定义协议名。默认 `'app'` |
 
 ---
 

package/Readme.md

@@ -271,6 +271,38 @@ const installUpdate = () => {
 
 ---
 
+## 🛣️ Routing Modes (Hash vs History)
+
+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.
+
+- **Main Process**: No extra config needed (defaults to `hash`).
+- **Renderer (Vite)**: Set `base: './'` (or omit) in `vite.config.ts`.
+- **Renderer (Router)**: Use `createWebHashHistory()`.
+
+### 2. History Mode (Modern)
+Supports clean URLs and standard browser refresh behavior. It uses a custom protocol (default `app://`) to bypass `file://` limitations.
+
+- **Main Process**: 
+  ```typescript
+  new RenderUpdater({
+    updateUrl: '...',
+    versionsDir: '...',
+    routerMode: 'history',   // Enable history mode
+    protocol: 'my-app'       // Optional: custom protocol name (default: 'app')
+  })
+  ```
+  > 💡 **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** — You must set your build tool's **Public Path** or **Base** to `/` to ensure absolute asset URLs. This prevents 404 errors for assets when refreshing the page on deep-nested routes.
+  - **Vite**: `base: '/'`
+  - **Webpack**: `output.publicPath: '/'`
+- **Renderer (Router)**: Use `createWebHistory()`.
+
+---
+
 ## ⚙️ API Reference
 
 ### `BuilderOptions` (CLI Config)
@@ -301,6 +333,8 @@ const installUpdate = () => {
 | `onDownloadComplete` | `function` | — | Completion hook: `(info, doInstall) => void` |
 | `onError` | `function` | — | Error handler: `(error: Error) => void` |
 | `onBeforeRestart` | `async function` | — | Called before `app.relaunch()`. Await-able for graceful shutdown |
+| `routerMode` | `'hash' \| 'history'` | — | Routing mode. Default: `'hash'` |
+| `protocol` | `string` | — | Custom protocol name for history mode. Default: `'app'` |
 
 ---
 

package/dist/bin/cli.cjs

@@ -39,8 +39,8 @@ var import_fs = __toESM(require("fs"), 1);
 var import_path = __toESM(require("path"), 1);
 var import_crypto = __toESM(require("crypto"), 1);
 async function createUpdatePackage(options) {
-  const asar = await import("asar").catch(() => {
-    throw new Error('Please install "asar" as a devDependency to use the builder.');
+  const asar = await import("@electron/asar").catch(() => {
+    throw new Error('Please install "@electron/asar" as a devDependency to use the builder.');
   });
   const {
     outDir,

package/dist/bin/cli.js

@@ -12,8 +12,8 @@ import fs from "fs";
 import path from "path";
 import crypto from "crypto";
 async function createUpdatePackage(options) {
-  const asar = await import("asar").catch(() => {
-    throw new Error('Please install "asar" as a devDependency to use the builder.');
+  const asar = await import("@electron/asar").catch(() => {
+    throw new Error('Please install "@electron/asar" as a devDependency to use the builder.');
   });
   const {
     outDir,

package/dist/builder/index.cjs

@@ -41,8 +41,8 @@ function defineConfig(config) {
   return config;
 }
 async function createUpdatePackage(options) {
-  const asar = await import("asar").catch(() => {
-    throw new Error('Please install "asar" as a devDependency to use the builder.');
+  const asar = await import("@electron/asar").catch(() => {
+    throw new Error('Please install "@electron/asar" as a devDependency to use the builder.');
   });
   const {
     outDir,

package/dist/builder/index.js

@@ -6,8 +6,8 @@ function defineConfig(config) {
   return config;
 }
 async function createUpdatePackage(options) {
-  const asar = await import("asar").catch(() => {
-    throw new Error('Please install "asar" as a devDependency to use the builder.');
+  const asar = await import("@electron/asar").catch(() => {
+    throw new Error('Please install "@electron/asar" as a devDependency to use the builder.');
   });
   const {
     outDir,

package/dist/main/index.cjs

@@ -33,12 +33,118 @@ __export(main_exports, {
   RenderUpdater: () => RenderUpdater
 });
 module.exports = __toCommonJS(main_exports);
-var import_path = __toESM(require("path"), 1);
-var import_original_fs = __toESM(require("original-fs"), 1);
+var import_path2 = __toESM(require("path"), 1);
+var import_original_fs2 = __toESM(require("original-fs"), 1);
 var import_crypto = __toESM(require("crypto"), 1);
-var import_electron = require("electron");
+var import_semver = __toESM(require("semver"), 1);
+var import_electron2 = require("electron");
 var import_promises = require("stream/promises");
 var import_stream = require("stream");
+
+// src/main/router-handler.ts
+var import_electron = require("electron");
+var import_url = require("url");
+var import_path = __toESM(require("path"), 1);
+var import_original_fs = __toESM(require("original-fs"), 1);
+var RouterHandler = class _RouterHandler {
+  static protocolName = "app";
+  static isSchemaRegistered = false;
+  static isHandlerInited = false;
+  versionsDir;
+  getActiveVersion;
+  constructor(options) {
+    this.versionsDir = options.versionsDir;
+    this.getActiveVersion = options.getActiveVersion;
+    this.init();
+  }
+  /**
+   * 零摩擦初始化入口
+   * 自动处理 Electron 生命周期：准备前注册特权，准备后挂载拦截器。
+   */
+  static setup(options) {
+    const { protocol: protocolName, versionsDir, getActiveVersion } = options;
+    if (!this.isSchemaRegistered) {
+      if (!import_electron.app.isReady()) {
+        this.protocolName = protocolName;
+        import_electron.protocol.registerSchemesAsPrivileged([
+          {
+            scheme: protocolName,
+            privileges: {
+              standard: true,
+              secure: true,
+              supportFetchAPI: true,
+              allowServiceWorkers: true,
+              corsEnabled: true
+            }
+          }
+        ]);
+        this.isSchemaRegistered = true;
+      } else {
+        console.warn(`[RouterHandler] App already ready. Cannot register scheme "${protocolName}".`);
+      }
+    }
+    if (!this.isHandlerInited) {
+      import_electron.app.whenReady().then(() => {
+        new _RouterHandler({ versionsDir, getActiveVersion });
+        this.isHandlerInited = true;
+      });
+    }
+  }
+  init() {
+    const protocolName = _RouterHandler.protocolName;
+    import_electron.protocol.handle(protocolName, async (request) => {
+      const url = new URL(request.url);
+      const { host, pathname } = url;
+      if (host === "renderer") {
+        const relativePath = pathname.startsWith("/") ? pathname.slice(1) : pathname;
+        const activeVersion = this.getActiveVersion();
+        const asarPath = import_path.default.join(this.versionsDir, activeVersion, "renderer.asar");
+        if (!import_original_fs.default.existsSync(asarPath)) {
+          return new Response("Not Found", { status: 404 });
+        }
+        const ext = import_path.default.extname(relativePath);
+        const isRequestingFile = ext !== "" && !relativePath.endsWith("/");
+        let targetFile = import_path.default.join(asarPath, relativePath);
+        if (!isRequestingFile || relativePath === "index.html" || relativePath === "") {
+          targetFile = import_path.default.join(asarPath, "index.html");
+        }
+        const response = await import_electron.net.fetch((0, import_url.pathToFileURL)(targetFile).toString());
+        const headers = new Headers(response.headers);
+        headers.set("Content-Type", this.getMimeType(targetFile));
+        headers.set("Access-Control-Allow-Origin", "*");
+        return new Response(response.body, {
+          status: response.status,
+          statusText: response.statusText,
+          headers
+        });
+      }
+      return new Response("Not Found", { status: 404 });
+    });
+  }
+  getMimeType(filePath) {
+    const ext = import_path.default.extname(filePath).toLowerCase();
+    const mimeMap = {
+      ".html": "text/html",
+      ".js": "application/javascript",
+      ".mjs": "application/javascript",
+      ".css": "text/css",
+      ".json": "application/json",
+      ".png": "image/png",
+      ".jpg": "image/jpeg",
+      ".jpeg": "image/jpeg",
+      ".gif": "image/gif",
+      ".svg": "image/svg+xml",
+      ".ico": "image/x-icon",
+      ".woff": "font/woff",
+      ".woff2": "font/woff2",
+      ".ttf": "font/ttf",
+      ".otf": "font/otf"
+    };
+    return mimeMap[ext] || "application/octet-stream";
+  }
+};
+
+// src/main/index.ts
 var RenderUpdater = class {
   versionsDir;
   currentVersionFile;
@@ -46,6 +152,8 @@ var RenderUpdater = class {
   activeVersion;
   publicKey;
   isDownloading = false;
+  routerMode;
+  protocolName;
   autoDownload;
   autoPrompt;
   maxVersionsToKeep;
@@ -56,7 +164,7 @@ var RenderUpdater = class {
   onBeforeRestart;
   constructor(options) {
     this.versionsDir = options.versionsDir;
-    this.currentVersionFile = import_path.default.join(this.versionsDir, "current.json");
+    this.currentVersionFile = import_path2.default.join(this.versionsDir, "current.json");
     this.baseUrl = options.updateUrl;
     this.publicKey = options.publicKey;
     this.autoDownload = options.autoDownload ?? false;
@@ -67,25 +175,34 @@ var RenderUpdater = class {
     this.onDownloadComplete = options.onDownloadComplete;
     this.onError = options.onError;
     this.onBeforeRestart = options.onBeforeRestart;
-    if (!import_original_fs.default.existsSync(this.versionsDir)) {
-      import_original_fs.default.mkdirSync(this.versionsDir, { recursive: true });
+    this.routerMode = options.routerMode ?? "hash";
+    this.protocolName = options.protocol ?? "app";
+    if (!import_original_fs2.default.existsSync(this.versionsDir)) {
+      import_original_fs2.default.mkdirSync(this.versionsDir, { recursive: true });
     }
     this.activeVersion = this.readCurrentVersionFromFile();
     this.cleanOldVersions();
+    if (this.routerMode === "history") {
+      RouterHandler.setup({
+        protocol: this.protocolName,
+        versionsDir: this.versionsDir,
+        getActiveVersion: () => this.activeVersion
+      });
+    }
   }
   cleanOldVersions() {
     try {
-      if (!import_original_fs.default.existsSync(this.versionsDir)) return;
-      const items = import_original_fs.default.readdirSync(this.versionsDir);
+      if (!import_original_fs2.default.existsSync(this.versionsDir)) return;
+      const items = import_original_fs2.default.readdirSync(this.versionsDir);
       const versionDirs = [];
       for (const item of items) {
         if (item === "current.json") continue;
-        const fullPath = import_path.default.join(this.versionsDir, item);
-        if (import_original_fs.default.statSync(fullPath).isDirectory()) {
+        const fullPath = import_path2.default.join(this.versionsDir, item);
+        if (import_original_fs2.default.statSync(fullPath).isDirectory()) {
           versionDirs.push(item);
         }
       }
-      versionDirs.sort((a, b) => this.compareVersions(b, a));
+      versionDirs.sort((a, b) => import_semver.default.compare(import_semver.default.coerce(b) ?? b, import_semver.default.coerce(a) ?? a));
       const activeIdx = versionDirs.indexOf(this.activeVersion);
       const safeVersions = /* @__PURE__ */ new Set();
       if (activeIdx !== -1) safeVersions.add(this.activeVersion);
@@ -100,7 +217,7 @@ var RenderUpdater = class {
       for (const v of versionDirs) {
         if (!safeVersions.has(v)) {
           console.info(`[RenderUpdater] Cleaning up old version: ${v}`);
-          import_original_fs.default.rmSync(import_path.default.join(this.versionsDir, v), { recursive: true, force: true });
+          import_original_fs2.default.rmSync(import_path2.default.join(this.versionsDir, v), { recursive: true, force: true });
         }
       }
     } catch (e) {
@@ -108,9 +225,9 @@ var RenderUpdater = class {
     }
   }
   readCurrentVersionFromFile() {
-    if (import_original_fs.default.existsSync(this.currentVersionFile)) {
+    if (import_original_fs2.default.existsSync(this.currentVersionFile)) {
       try {
-        const current = JSON.parse(import_original_fs.default.readFileSync(this.currentVersionFile, "utf-8"));
+        const current = JSON.parse(import_original_fs2.default.readFileSync(this.currentVersionFile, "utf-8"));
         return current.version;
       } catch {
         return "0.0.0";
@@ -119,19 +236,23 @@ var RenderUpdater = class {
     return "0.0.0";
   }
   hasAnyVersion() {
-    return import_original_fs.default.existsSync(this.currentVersionFile);
+    return import_original_fs2.default.existsSync(this.currentVersionFile);
   }
   /**
-   * Returns the file:// URL to the latest renderer.asar index.html,
-   * or empty string if no update is available.
+   * Returns the correct URL to load in the BrowserWindow.
+   * If history mode is enabled, it returns the custom protocol URL.
+   * Otherwise, it returns the local file URL with # hash.
    */
   getLoadUrl() {
     try {
-      if (import_original_fs.default.existsSync(this.currentVersionFile)) {
-        const current = JSON.parse(import_original_fs.default.readFileSync(this.currentVersionFile, "utf-8"));
+      if (import_original_fs2.default.existsSync(this.currentVersionFile)) {
+        const current = JSON.parse(import_original_fs2.default.readFileSync(this.currentVersionFile, "utf-8"));
         const version = current.version;
-        const asarPath = import_path.default.join(this.versionsDir, version, "renderer.asar");
-        if (import_original_fs.default.existsSync(asarPath)) {
+        const asarPath = import_path2.default.join(this.versionsDir, version, "renderer.asar");
+        if (import_original_fs2.default.existsSync(asarPath)) {
+          if (this.routerMode === "history") {
+            return `${this.protocolName}://renderer/`;
+          }
           return `file://${asarPath}/index.html`;
         }
       }
@@ -146,7 +267,7 @@ var RenderUpdater = class {
       if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
       const remoteInfo = await response.json();
       const currentVersion = this.activeVersion;
-      if (this.compareVersions(remoteInfo.version, currentVersion) > 0) {
+      if (import_semver.default.gt(remoteInfo.version, currentVersion)) {
         return { updateAvailable: true, version: remoteInfo.version, info: remoteInfo };
       }
       return { updateAvailable: false };
@@ -165,19 +286,19 @@ var RenderUpdater = class {
       const response = await fetch(`${this.baseUrl}/latest.json?t=${Date.now()}`);
       if (!response.ok) throw new Error("[RenderUpdater] Cannot fetch latest.json for download");
       const info = await response.json();
-      const versionDir = import_path.default.join(this.versionsDir, info.version);
-      const asarPath = import_path.default.join(versionDir, "renderer.asar");
-      if (import_original_fs.default.existsSync(asarPath) && this.verifyFile(asarPath, info)) {
+      const versionDir = import_path2.default.join(this.versionsDir, info.version);
+      const asarPath = import_path2.default.join(versionDir, "renderer.asar");
+      if (import_original_fs2.default.existsSync(asarPath) && this.verifyFile(asarPath, info)) {
         onProgress?.(100);
         this.useVersion(info.version);
         return;
       }
-      if (!import_original_fs.default.existsSync(versionDir)) {
-        import_original_fs.default.mkdirSync(versionDir, { recursive: true });
+      if (!import_original_fs2.default.existsSync(versionDir)) {
+        import_original_fs2.default.mkdirSync(versionDir, { recursive: true });
       }
       let downloadedBytes = 0;
-      if (import_original_fs.default.existsSync(asarPath)) {
-        downloadedBytes = import_original_fs.default.statSync(asarPath).size;
+      if (import_original_fs2.default.existsSync(asarPath)) {
+        downloadedBytes = import_original_fs2.default.statSync(asarPath).size;
       }
       const fetchOptions = {};
       if (downloadedBytes > 0) {
@@ -198,7 +319,7 @@ var RenderUpdater = class {
       const incomingTotal = contentLength ? parseInt(contentLength, 10) : 0;
       const total = downloadedBytes + incomingTotal;
       if (!downloadResponse.body) throw new Error("Response body is empty");
-      const fileStream = import_original_fs.default.createWriteStream(asarPath, { flags: downloadResponse.status === 206 ? "a" : "w" });
+      const fileStream = import_original_fs2.default.createWriteStream(asarPath, { flags: downloadResponse.status === 206 ? "a" : "w" });
       const progressTransform = new import_stream.Transform({
         transform(chunk, _encoding, callback) {
           downloadedBytes += chunk.length;
@@ -214,7 +335,7 @@ var RenderUpdater = class {
         fileStream
       );
       if (!this.verifyFile(asarPath, info)) {
-        import_original_fs.default.rmSync(versionDir, { recursive: true, force: true });
+        import_original_fs2.default.rmSync(versionDir, { recursive: true, force: true });
         throw new Error("[RenderUpdater] Verification failed after download (SHA256 or RSA Mismatch)");
       }
       this.useVersion(info.version);
@@ -224,7 +345,7 @@ var RenderUpdater = class {
     }
   }
   verifyFile(filePath, info) {
-    const fileBuffer = import_original_fs.default.readFileSync(filePath);
+    const fileBuffer = import_original_fs2.default.readFileSync(filePath);
     const hashSum = import_crypto.default.createHash("sha256");
     hashSum.update(fileBuffer);
     const sha256 = hashSum.digest("hex");
@@ -250,23 +371,13 @@ var RenderUpdater = class {
     return true;
   }
   useVersion(version) {
-    import_original_fs.default.writeFileSync(
+    import_original_fs2.default.writeFileSync(
       this.currentVersionFile,
       JSON.stringify({ version, date: (/* @__PURE__ */ new Date()).toISOString() })
     );
     this.activeVersion = version;
   }
-  compareVersions(v1, v2) {
-    const parts1 = v1.split(".").map(Number);
-    const parts2 = v2.split(".").map(Number);
-    for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
-      const n1 = parts1[i] || 0;
-      const n2 = parts2[i] || 0;
-      if (n1 > n2) return 1;
-      if (n1 < n2) return -1;
-    }
-    return 0;
-  }
+  // compareVersions 已由 semver 库替代，此方法已移除
   /**
    * One-stop method to check for updates, show dialogs (if autoPrompt=true),
    * download, and restart application.
@@ -285,8 +396,8 @@ var RenderUpdater = class {
             if (this.onBeforeRestart) {
               await this.onBeforeRestart();
             }
-            import_electron.app.relaunch();
-            import_electron.app.quit();
+            import_electron2.app.relaunch();
+            import_electron2.app.quit();
           };
           if (this.onDownloadComplete) {
             this.onDownloadComplete(info, () => {
@@ -295,7 +406,7 @@ var RenderUpdater = class {
           } else {
             if (info.forceUpdate) {
               if (info.forceUpdate === "prompt") {
-                import_electron.dialog.showMessageBoxSync({
+                import_electron2.dialog.showMessageBoxSync({
                   type: "warning",
                   title: "\u4E0B\u8F7D\u5B8C\u6210",
                   message: "\u6700\u65B0\u7248\u672C\u5DF2\u4E0B\u8F7D\u5B8C\u6BD5\u3002\u5373\u5C06\u91CD\u542F\u7A0B\u5E8F\u4EE5\u5E94\u7528\u66F4\u65B0\u3002",
@@ -304,7 +415,7 @@ var RenderUpdater = class {
               }
               doInstall().catch(console.error);
             } else if (this.autoPrompt) {
-              import_electron.dialog.showMessageBoxSync({
+              import_electron2.dialog.showMessageBoxSync({
                 type: "info",
                 title: "\u4E0B\u8F7D\u5B8C\u6210",
                 message: "\u6700\u65B0\u7248\u672C\u5DF2\u4E0B\u8F7D\u5B8C\u6BD5\u3002\u70B9\u51FB\u786E\u5B9A\u91CD\u542F\u7A0B\u5E8F\u4EE5\u5B89\u88C5\u66F4\u65B0\u3002",
@@ -327,7 +438,7 @@ var RenderUpdater = class {
       } else {
         if (info.forceUpdate) {
           if (info.forceUpdate === "prompt") {
-            import_electron.dialog.showMessageBoxSync({
+            import_electron2.dialog.showMessageBoxSync({
               type: "warning",
               title: "\u53D1\u73B0\u65B0\u7248\u672C",
               message: `\u53D1\u73B0\u65B0\u7248\u672C (v${info.version})\u3002
@@ -341,7 +452,7 @@ ${info.releaseNotes || "\u672C\u6B21\u66F4\u65B0\u4E3A\u5F3A\u5236\u66F4\u65B0\u
         } else if (this.autoDownload) {
           await doDownload();
         } else if (this.autoPrompt) {
-          const { response } = await import_electron.dialog.showMessageBox({
+          const { response } = await import_electron2.dialog.showMessageBox({
             type: "info",
             title: "\u53D1\u73B0\u65B0\u7248\u672C",
             message: `\u53D1\u73B0\u53EF\u7528\u66F4\u65B0 (v${info.version})\u3002\u662F\u5426\u7ACB\u5373\u4E0B\u8F7D\u66F4\u65B0\uFF1F

package/dist/main/index.d.ts

@@ -6,6 +6,8 @@ export declare class RenderUpdater {
     private activeVersion;
     private publicKey?;
     private isDownloading;
+    private routerMode;
+    private protocolName;
     private autoDownload;
     private autoPrompt;
     private maxVersionsToKeep;
@@ -19,8 +21,9 @@ export declare class RenderUpdater {
     private readCurrentVersionFromFile;
     hasAnyVersion(): boolean;
     /**
-     * Returns the file:// URL to the latest renderer.asar index.html,
-     * or empty string if no update is available.
+     * Returns the correct URL to load in the BrowserWindow.
+     * If history mode is enabled, it returns the custom protocol URL.
+     * Otherwise, it returns the local file URL with # hash.
      */
     getLoadUrl(): string;
     check(): Promise<{
@@ -34,7 +37,6 @@ export declare class RenderUpdater {
     download(onProgress?: (percent: number) => void): Promise<void>;
     private verifyFile;
     private useVersion;
-    private compareVersions;
     /**
      * One-stop method to check for updates, show dialogs (if autoPrompt=true),
      * download, and restart application.

package/dist/main/index.js

@@ -1,10 +1,116 @@
 // src/main/index.ts
-import path from "path";
-import fs from "original-fs";
+import path2 from "path";
+import fs2 from "original-fs";
 import crypto from "crypto";
-import { app, dialog } from "electron";
+import semver from "semver";
+import { app as app2, dialog } from "electron";
 import { pipeline } from "stream/promises";
 import { Readable, Transform } from "stream";
+
+// src/main/router-handler.ts
+import { protocol, net, app } from "electron";
+import { pathToFileURL } from "url";
+import path from "path";
+import fs from "original-fs";
+var RouterHandler = class _RouterHandler {
+  static protocolName = "app";
+  static isSchemaRegistered = false;
+  static isHandlerInited = false;
+  versionsDir;
+  getActiveVersion;
+  constructor(options) {
+    this.versionsDir = options.versionsDir;
+    this.getActiveVersion = options.getActiveVersion;
+    this.init();
+  }
+  /**
+   * 零摩擦初始化入口
+   * 自动处理 Electron 生命周期：准备前注册特权，准备后挂载拦截器。
+   */
+  static setup(options) {
+    const { protocol: protocolName, versionsDir, getActiveVersion } = options;
+    if (!this.isSchemaRegistered) {
+      if (!app.isReady()) {
+        this.protocolName = protocolName;
+        protocol.registerSchemesAsPrivileged([
+          {
+            scheme: protocolName,
+            privileges: {
+              standard: true,
+              secure: true,
+              supportFetchAPI: true,
+              allowServiceWorkers: true,
+              corsEnabled: true
+            }
+          }
+        ]);
+        this.isSchemaRegistered = true;
+      } else {
+        console.warn(`[RouterHandler] App already ready. Cannot register scheme "${protocolName}".`);
+      }
+    }
+    if (!this.isHandlerInited) {
+      app.whenReady().then(() => {
+        new _RouterHandler({ versionsDir, getActiveVersion });
+        this.isHandlerInited = true;
+      });
+    }
+  }
+  init() {
+    const protocolName = _RouterHandler.protocolName;
+    protocol.handle(protocolName, async (request) => {
+      const url = new URL(request.url);
+      const { host, pathname } = url;
+      if (host === "renderer") {
+        const relativePath = pathname.startsWith("/") ? pathname.slice(1) : pathname;
+        const activeVersion = this.getActiveVersion();
+        const asarPath = path.join(this.versionsDir, activeVersion, "renderer.asar");
+        if (!fs.existsSync(asarPath)) {
+          return new Response("Not Found", { status: 404 });
+        }
+        const ext = path.extname(relativePath);
+        const isRequestingFile = ext !== "" && !relativePath.endsWith("/");
+        let targetFile = path.join(asarPath, relativePath);
+        if (!isRequestingFile || relativePath === "index.html" || relativePath === "") {
+          targetFile = path.join(asarPath, "index.html");
+        }
+        const response = await net.fetch(pathToFileURL(targetFile).toString());
+        const headers = new Headers(response.headers);
+        headers.set("Content-Type", this.getMimeType(targetFile));
+        headers.set("Access-Control-Allow-Origin", "*");
+        return new Response(response.body, {
+          status: response.status,
+          statusText: response.statusText,
+          headers
+        });
+      }
+      return new Response("Not Found", { status: 404 });
+    });
+  }
+  getMimeType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const mimeMap = {
+      ".html": "text/html",
+      ".js": "application/javascript",
+      ".mjs": "application/javascript",
+      ".css": "text/css",
+      ".json": "application/json",
+      ".png": "image/png",
+      ".jpg": "image/jpeg",
+      ".jpeg": "image/jpeg",
+      ".gif": "image/gif",
+      ".svg": "image/svg+xml",
+      ".ico": "image/x-icon",
+      ".woff": "font/woff",
+      ".woff2": "font/woff2",
+      ".ttf": "font/ttf",
+      ".otf": "font/otf"
+    };
+    return mimeMap[ext] || "application/octet-stream";
+  }
+};
+
+// src/main/index.ts
 var RenderUpdater = class {
   versionsDir;
   currentVersionFile;
@@ -12,6 +118,8 @@ var RenderUpdater = class {
   activeVersion;
   publicKey;
   isDownloading = false;
+  routerMode;
+  protocolName;
   autoDownload;
   autoPrompt;
   maxVersionsToKeep;
@@ -22,7 +130,7 @@ var RenderUpdater = class {
   onBeforeRestart;
   constructor(options) {
     this.versionsDir = options.versionsDir;
-    this.currentVersionFile = path.join(this.versionsDir, "current.json");
+    this.currentVersionFile = path2.join(this.versionsDir, "current.json");
     this.baseUrl = options.updateUrl;
     this.publicKey = options.publicKey;
     this.autoDownload = options.autoDownload ?? false;
@@ -33,25 +141,34 @@ var RenderUpdater = class {
     this.onDownloadComplete = options.onDownloadComplete;
     this.onError = options.onError;
     this.onBeforeRestart = options.onBeforeRestart;
-    if (!fs.existsSync(this.versionsDir)) {
-      fs.mkdirSync(this.versionsDir, { recursive: true });
+    this.routerMode = options.routerMode ?? "hash";
+    this.protocolName = options.protocol ?? "app";
+    if (!fs2.existsSync(this.versionsDir)) {
+      fs2.mkdirSync(this.versionsDir, { recursive: true });
     }
     this.activeVersion = this.readCurrentVersionFromFile();
     this.cleanOldVersions();
+    if (this.routerMode === "history") {
+      RouterHandler.setup({
+        protocol: this.protocolName,
+        versionsDir: this.versionsDir,
+        getActiveVersion: () => this.activeVersion
+      });
+    }
   }
   cleanOldVersions() {
     try {
-      if (!fs.existsSync(this.versionsDir)) return;
-      const items = fs.readdirSync(this.versionsDir);
+      if (!fs2.existsSync(this.versionsDir)) return;
+      const items = fs2.readdirSync(this.versionsDir);
       const versionDirs = [];
       for (const item of items) {
         if (item === "current.json") continue;
-        const fullPath = path.join(this.versionsDir, item);
-        if (fs.statSync(fullPath).isDirectory()) {
+        const fullPath = path2.join(this.versionsDir, item);
+        if (fs2.statSync(fullPath).isDirectory()) {
           versionDirs.push(item);
         }
       }
-      versionDirs.sort((a, b) => this.compareVersions(b, a));
+      versionDirs.sort((a, b) => semver.compare(semver.coerce(b) ?? b, semver.coerce(a) ?? a));
       const activeIdx = versionDirs.indexOf(this.activeVersion);
       const safeVersions = /* @__PURE__ */ new Set();
       if (activeIdx !== -1) safeVersions.add(this.activeVersion);
@@ -66,7 +183,7 @@ var RenderUpdater = class {
       for (const v of versionDirs) {
         if (!safeVersions.has(v)) {
           console.info(`[RenderUpdater] Cleaning up old version: ${v}`);
-          fs.rmSync(path.join(this.versionsDir, v), { recursive: true, force: true });
+          fs2.rmSync(path2.join(this.versionsDir, v), { recursive: true, force: true });
         }
       }
     } catch (e) {
@@ -74,9 +191,9 @@ var RenderUpdater = class {
     }
   }
   readCurrentVersionFromFile() {
-    if (fs.existsSync(this.currentVersionFile)) {
+    if (fs2.existsSync(this.currentVersionFile)) {
       try {
-        const current = JSON.parse(fs.readFileSync(this.currentVersionFile, "utf-8"));
+        const current = JSON.parse(fs2.readFileSync(this.currentVersionFile, "utf-8"));
         return current.version;
       } catch {
         return "0.0.0";
@@ -85,19 +202,23 @@ var RenderUpdater = class {
     return "0.0.0";
   }
   hasAnyVersion() {
-    return fs.existsSync(this.currentVersionFile);
+    return fs2.existsSync(this.currentVersionFile);
   }
   /**
-   * Returns the file:// URL to the latest renderer.asar index.html,
-   * or empty string if no update is available.
+   * Returns the correct URL to load in the BrowserWindow.
+   * If history mode is enabled, it returns the custom protocol URL.
+   * Otherwise, it returns the local file URL with # hash.
    */
   getLoadUrl() {
     try {
-      if (fs.existsSync(this.currentVersionFile)) {
-        const current = JSON.parse(fs.readFileSync(this.currentVersionFile, "utf-8"));
+      if (fs2.existsSync(this.currentVersionFile)) {
+        const current = JSON.parse(fs2.readFileSync(this.currentVersionFile, "utf-8"));
         const version = current.version;
-        const asarPath = path.join(this.versionsDir, version, "renderer.asar");
-        if (fs.existsSync(asarPath)) {
+        const asarPath = path2.join(this.versionsDir, version, "renderer.asar");
+        if (fs2.existsSync(asarPath)) {
+          if (this.routerMode === "history") {
+            return `${this.protocolName}://renderer/`;
+          }
           return `file://${asarPath}/index.html`;
         }
       }
@@ -112,7 +233,7 @@ var RenderUpdater = class {
       if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
       const remoteInfo = await response.json();
       const currentVersion = this.activeVersion;
-      if (this.compareVersions(remoteInfo.version, currentVersion) > 0) {
+      if (semver.gt(remoteInfo.version, currentVersion)) {
         return { updateAvailable: true, version: remoteInfo.version, info: remoteInfo };
       }
       return { updateAvailable: false };
@@ -131,19 +252,19 @@ var RenderUpdater = class {
       const response = await fetch(`${this.baseUrl}/latest.json?t=${Date.now()}`);
       if (!response.ok) throw new Error("[RenderUpdater] Cannot fetch latest.json for download");
       const info = await response.json();
-      const versionDir = path.join(this.versionsDir, info.version);
-      const asarPath = path.join(versionDir, "renderer.asar");
-      if (fs.existsSync(asarPath) && this.verifyFile(asarPath, info)) {
+      const versionDir = path2.join(this.versionsDir, info.version);
+      const asarPath = path2.join(versionDir, "renderer.asar");
+      if (fs2.existsSync(asarPath) && this.verifyFile(asarPath, info)) {
         onProgress?.(100);
         this.useVersion(info.version);
         return;
       }
-      if (!fs.existsSync(versionDir)) {
-        fs.mkdirSync(versionDir, { recursive: true });
+      if (!fs2.existsSync(versionDir)) {
+        fs2.mkdirSync(versionDir, { recursive: true });
       }
       let downloadedBytes = 0;
-      if (fs.existsSync(asarPath)) {
-        downloadedBytes = fs.statSync(asarPath).size;
+      if (fs2.existsSync(asarPath)) {
+        downloadedBytes = fs2.statSync(asarPath).size;
       }
       const fetchOptions = {};
       if (downloadedBytes > 0) {
@@ -164,7 +285,7 @@ var RenderUpdater = class {
       const incomingTotal = contentLength ? parseInt(contentLength, 10) : 0;
       const total = downloadedBytes + incomingTotal;
       if (!downloadResponse.body) throw new Error("Response body is empty");
-      const fileStream = fs.createWriteStream(asarPath, { flags: downloadResponse.status === 206 ? "a" : "w" });
+      const fileStream = fs2.createWriteStream(asarPath, { flags: downloadResponse.status === 206 ? "a" : "w" });
       const progressTransform = new Transform({
         transform(chunk, _encoding, callback) {
           downloadedBytes += chunk.length;
@@ -180,7 +301,7 @@ var RenderUpdater = class {
         fileStream
       );
       if (!this.verifyFile(asarPath, info)) {
-        fs.rmSync(versionDir, { recursive: true, force: true });
+        fs2.rmSync(versionDir, { recursive: true, force: true });
         throw new Error("[RenderUpdater] Verification failed after download (SHA256 or RSA Mismatch)");
       }
       this.useVersion(info.version);
@@ -190,7 +311,7 @@ var RenderUpdater = class {
     }
   }
   verifyFile(filePath, info) {
-    const fileBuffer = fs.readFileSync(filePath);
+    const fileBuffer = fs2.readFileSync(filePath);
     const hashSum = crypto.createHash("sha256");
     hashSum.update(fileBuffer);
     const sha256 = hashSum.digest("hex");
@@ -216,23 +337,13 @@ var RenderUpdater = class {
     return true;
   }
   useVersion(version) {
-    fs.writeFileSync(
+    fs2.writeFileSync(
       this.currentVersionFile,
       JSON.stringify({ version, date: (/* @__PURE__ */ new Date()).toISOString() })
     );
     this.activeVersion = version;
   }
-  compareVersions(v1, v2) {
-    const parts1 = v1.split(".").map(Number);
-    const parts2 = v2.split(".").map(Number);
-    for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
-      const n1 = parts1[i] || 0;
-      const n2 = parts2[i] || 0;
-      if (n1 > n2) return 1;
-      if (n1 < n2) return -1;
-    }
-    return 0;
-  }
+  // compareVersions 已由 semver 库替代，此方法已移除
   /**
    * One-stop method to check for updates, show dialogs (if autoPrompt=true),
    * download, and restart application.
@@ -251,8 +362,8 @@ var RenderUpdater = class {
             if (this.onBeforeRestart) {
               await this.onBeforeRestart();
             }
-            app.relaunch();
-            app.quit();
+            app2.relaunch();
+            app2.quit();
           };
           if (this.onDownloadComplete) {
             this.onDownloadComplete(info, () => {

package/dist/main/router-handler.d.ts

@@ -0,0 +1,20 @@
+export interface RouterHandlerOptions {
+    protocol: string;
+    versionsDir: string;
+    getActiveVersion: () => string;
+}
+export declare class RouterHandler {
+    private static protocolName;
+    private static isSchemaRegistered;
+    private static isHandlerInited;
+    private versionsDir;
+    private getActiveVersion;
+    private constructor();
+    /**
+     * 零摩擦初始化入口
+     * 自动处理 Electron 生命周期：准备前注册特权，准备后挂载拦截器。
+     */
+    static setup(options: RouterHandlerOptions): void;
+    private init;
+    private getMimeType;
+}

package/dist/types.d.ts

@@ -64,6 +64,18 @@ export interface UpdaterOptions {
      * Useful for telling the Vue renderer to save state and cleanup.
      */
     onBeforeRestart?: () => void | Promise<void>;
+    /**
+     * Defines the routing mode of the renderer project.
+     * 'hash': Use default file:// loading (Zero performance overhead).
+     * 'history': Use custom app:// protocol with try-files redirection to support History mode.
+     * Defaults to 'hash'.
+     */
+    routerMode?: 'hash' | 'history';
+    /**
+     * Custom protocol name for history mode or asset serving.
+     * Defaults to 'app'.
+     */
+    protocol?: string;
 }
 export interface BuilderOptions {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "electron-updater-for-render",
-  "version": "1.1.2-beta.3",
+  "version": "1.1.2-beta.5",
   "description": "A lightweight incremental updater for Electron renderer processes",
   "type": "module",
   "bin": {
@@ -27,20 +27,22 @@
   },
   "dependencies": {
     "jiti": "^2.6.1",
-    "original-fs": "^1.2.0"
+    "original-fs": "^1.2.0",
+    "semver": "^7.7.4"
   },
   "peerDependencies": {
-    "asar": "^3.2.0",
+    "@electron/asar": "^3.3.0",
     "electron": ">=20.0.0"
   },
   "peerDependenciesMeta": {
-    "asar": {
+    "@electron/asar": {
       "optional": true
     }
   },
   "devDependencies": {
+    "@electron/asar": "^4.2.0",
     "@types/node": "^22.0.0",
-    "asar": "^3.2.0",
+    "@types/semver": "^7.7.1",
     "tsup": "^8.0.2",
     "typescript": "^5.0.0"
   },