Electron-Vite + TS 中 Vue Router 路由模式如何配置才支持打包后正常跳转？

Question

在 Electron-Vite + TypeScript 项目中，使用 Vue Router 时若采用默认的 `history` 模式，打包后（尤其是 `electron:build` 后）主进程加载 `index.html` 时路径为 `file://.../dist/index.html`，而 `history` 模式依赖服务端路由回退逻辑，本地文件协议下无服务端支持，导致刷新或直接访问子路由（如 `/setting`）时白屏或 404。常见错误表现为：开发时跳转正常，但打包后仅首页可访问，二级路由无法加载对应组件。根本原因在于 `history` 模式要求所有路由均指向 `index.html`，而 Electron 的 `file://` 协议不支持此重写机制。需适配 Electron 环境的路由策略——既保持开发体验，又确保生产包内离线可用。解决方案需兼顾 `createWebHistory` 的基础配置、`__dirname`/`join` 路径处理，以及 Vite 构建输出路径与 `loadFile` 加载方式的协同。

Answer 1

```html

一、现象层：白屏与 404 的直观表现

• 开发时（vite dev）路由跳转正常，/setting、/dashboard 均可渲染；
• 执行 pnpm run electron:build 后，双击生成的 .exe 或 .app，首页（/）可加载；
• 点击菜单跳转至 /setting —— 正常；
• 但**刷新页面**或**直接在地址栏输入 file://.../dist/index.html#/setting** —— 白屏或控制台报错 Failed to load resource: net::ERR_FILE_NOT_FOUND；
• Network 面板可见浏览器尝试请求 file://.../dist/setting（而非回退到 index.html），暴露了 history 模式在 file:// 下的天然缺陷。

二、机制层：为什么 history 模式在 Electron 中“失能”？

Vue Router 的 createWebHistory() 本质依赖浏览器 history.pushState() + 服务端 fallback：当用户访问 /setting 时，服务端需将所有非静态资源请求统一返回 index.html，再由前端 Router 解析路径并匹配组件。但在 Electron 中：

环境	协议	是否具备服务端重写能力	能否拦截 /setting → index.html
开发（Vite Dev Server）	http://localhost:5173	✅ 支持 connect-history-api-fallback	✅
生产（Electron 打包后）	file://...	❌ 无服务端，无中间件	❌ 浏览器直接按路径查找文件

三、架构层：Electron-Vite 路由适配的核心协同点

成功方案必须同时满足以下三者协同：

1. Vite 构建输出路径：默认为 dist/，其中 index.html 是唯一入口；
2. 主进程 loadFile 加载方式：必须使用 win.loadFile(join(__dirname, '../dist/index.html'))（而非 loadURL('file://...') 手动拼接），确保路径跨平台安全；
3. Vue Router 历史模式配置：需在 createWebHistory() 中显式传入 base，且该 base 必须与 Vite 的 base 配置、Electron 实际加载路径严格一致。

四、解决方案层：生产就绪的路由配置范式

推荐采用「条件化 history base」策略，兼顾开发与生产：

// src/router/index.ts
import { createRouter, createWebHistory } from 'vue-router';
import { join, resolve } from 'path';
import { fileURLToPath } from 'url';

const isDev = import.meta.env.DEV;
const __dirname = dirname(fileURLToPath(import.meta.url));

// ✅ 动态计算 base：开发用 '/'，生产用 './'（相对路径）
const routerBase = isDev ? '/' : './';

const router = createRouter({
  history: createWebHistory(routerBase),
  routes: [
    { path: '/', component: () => import('@/views/Home.vue') },
    { path: '/setting', component: () => import('@/views/Setting.vue') },
  ],
});
export default router;

五、工程层：Vite 与 Electron 主进程关键配置对齐

Vite 配置需显式声明 base: './'（注意是字符串 './'，非 '/'），否则构建产物中资源引用路径仍为绝对路径（如 /assets/index.xxxx.js），导致生产环境加载失败：

// vite.config.ts
export default defineConfig({
  base: import.meta.env.PROD ? './' : '/',
  build: {
    rollupOptions: {
      output: {
        assetFileNames: 'assets/[name].[hash].[ext]',
        chunkFileNames: 'assets/[name].[hash].js',
        entryFileNames: 'assets/[name].[hash].js',
      }
    }
  }
});

六、验证层：全场景测试清单

• ✅ 开发环境：vite dev → 刷新任意子路由（/setting）正常；
• ✅ 生产环境：electron:build 后运行 App → 点击导航正常；
• ✅ 生产环境：刷新当前子路由页 → 仍显示对应组件（非白屏）；
• ✅ 生产环境：关闭 App，重新打开并直接访问 file://.../dist/index.html#/setting → 渲染正确；
• ✅ 多平台验证：Windows（.exe）、macOS（.app）、Linux（AppImage）均通过。

七、进阶思考：为何不直接换 hash 模式？

虽 createWebHashHistory() 可规避此问题，但存在硬伤：

• URL 中冗余 #，不符合桌面应用 UX 规范（如 macOS 菜单栏无法识别 # 后路径）；
• 深度链接（Deep Linking）集成困难，例如外部协议唤起 myapp://setting 需额外解析；
• SEO 无关（Electron 桌面应用本无需 SEO），但团队若未来拓展 Web 版，history 模式可复用路由逻辑。

八、部署层：自动化路径校验流程图

graph TD
  A[启动 Electron App] --> B{isDev?}
  B -- Yes --> C[使用 createWebHistory('/')]
  B -- No --> D[使用 createWebHistory('./')]
  C --> E[由 Vite Dev Server 提供 fallback]
  D --> F[由 ./base + 相对路径资源引用保障]
  F --> G[所有子路由请求均被 index.html 捕获]
  G --> H[Vue Router 解析 #/setting 并渲染]

```