解决electron+vue-router在history模式下打包后首页空白问题

解决electron+vue-router在history模式下打包后首页空白问题

在 Electron 中使用 Vue Router 的 history 模式时，打包后出现首页空白（默认不显示首页），核心原因是 history 模式依赖 HTML5 History API，而 Electron 打包后通过 file:// 协议加载本地文件，导致路由路径解析异常。以下是具体解决方案：

一、核心原因分析

1. history 模式的局限性：

   Vue Router 的 history 模式依赖服务器配置（如 Nginx 的 try_files），确保所有路径都指向 index.html。但 Electron 打包后使用 file:// 本地协议，没有服务器环境，导致路由无法正确匹配。

2. 路径解析差异：

   开发环境（http://localhost）中，history 模式可正常工作；但打包后，file:// 协议下，/ 可能被解析为系统根目录（如 file:///），而非应用内的 index.html 路径，导致路由匹配失败。

二、解决方案

方案 1：切换为 hash 模式（推荐，最简单）

hash 模式（路径带 #）不依赖服务器配置，适合本地文件加载，可直接解决空白问题。

// src/router/index.ts

import { createRouter, createWebHashHistory } from 'vue-router'; // 改用 hash 模式

const router = createRouter({

// 无论开发/生产环境，均使用 hash 模式

history: createWebHashHistory(import.meta.env.BASE\_URL), 

routes: \[

 {

	path: '/',
     name: 'home',
     component: () => import('@/views/Home.vue') // 首页组件
	 }
]

});

方案 2：坚持使用 history 模式（需额外配置）

若必须使用 history 模式，需通过以下配置确保路由正确解析：

1. 配置 Vue Router 的 base 路径

// src/router/index.ts

import { createRouter, createWebHistory } from 'vue-router';

// 生产环境设置 base 为相对路径（与打包后的 index.html 位置匹配）

const base = import.meta.env.DEV;
 // 关键：打包后相对路径

const router = createRouter({

history: createWebHistory(base),

routes: [

 {

   path: '/',

     name: 'home',

     component: () => import('@/views/Home.vue')

   },

// 关键：添加通配符路由，未匹配路径自动跳转首页

 {

    path: '/:pathMatch(.\*)\*',

    redirect: '/'

  }

]

});

2. 配置 Vite 打包路径

确保打包后的资源以相对路径加载，避免绝对路径导致的 file:// 协议解析错误：

// vite.config.ts

import { defineConfig } from 'vite';

export default defineConfig({

 base: import.meta.env.DEV ? '/' : './', // 生产环境使用相对路径

 build: {

  outDir: 'dist/renderer', // 输出到 Electron 可访问的目录

  assetsDir: 'assets'

}

});

3. 确保 Electron 主进程正确加载 index.html

主进程需加载打包后的 index.html，且路径必须准确：

// src/main/index.ts

import { app, BrowserWindow } from 'electron';

import path from 'path';

const createWindow = () => {
const mainWindow = new BrowserWindow({
  // ... 窗口配置
});

if (import.meta.env.DEV) {

  // 开发环境加载本地服务器

   mainWindow.loadURL('http://localhost:5173');
 } else {

 // 生产环境加载打包后的 index.html（路径必须正确）
  mainWindow.loadFile(path.join(\_\_dirname, '../renderer/index.html'));
}

};

三、关键注意事项

1. 避免绝对路径跳转：

   路由跳转时使用相对路径，如 <router-link to="/"> 而非绝对路径。

2. 清理路由缓存：

   打包前删除旧的 dist 目录，避免缓存文件干扰：

rm -rf dist && npm run build

1. 调试打包后的路由：

   临时开启生产环境 DevTools，查看路由匹配情况：

// 主进程中添加（测试用，发布前移除）

mainWindow.webContents.openDevTools();

若控制台显示 Failed to load resource: net::ERR_FILE_NOT_FOUND，说明路径配置仍有问题。

四、最佳实践总结

• 优先选择 hash 模式：在 Electron 等本地应用中，hash 模式（createWebHashHistory）兼容性更好，无需额外配置。

• history 模式必备配置：若使用 history 模式，必须同时设置 base: './'、通配符路由和 Vite 相对路径打包。

通过以上配置，可确保 Electron 打包后，Vue Router 能正确匹配首页路径，解决空白问题。