在使用Electron-vite搭建桌面应用开发环境时，不少开发者会遇到项目启动后预览页面显示空白的情况，这个问题很多时候和前端路由的模式选择有直接关系，其中切换到HashRouter是常用的解决方式。
空白屏问题的常见原因
Electron应用的页面加载逻辑和常规浏览器环境有差异，常规的前端路由如HistoryRouter依赖HTML5的history API，需要服务器端的路由重定向支持。但是在Electron环境中，默认加载的是本地文件，使用file协议打开页面，HistoryRouter的路由跳转逻辑无法被正确处理，就会导致页面找不到对应的资源，最终出现空白屏。
HashRouter的工作原理
HashRouter是前端路由的另一种模式，它的路由标识是URL中#后面的部分，例如http://localhost:3000/#/home。浏览器在处理带#的URL时，不会向服务器发送#后面的内容，只会加载#前面的页面资源，路由的切换完全由前端JavaScript控制。这种特性刚好适配Electron的本地文件加载场景，不需要服务器端做额外的路由配置。
具体解决步骤
1. 前端路由切换为HashRouter
如果你的项目使用的是React作为前端框架，首先需要将路由模式从HistoryRouter改为HashRouter，以下是React Router v6的配置示例：
// 原HistoryRouter配置
// import { BrowserRouter as Router } from 'react-router-dom'
// 修改为HashRouter
import { HashRouter as Router, Routes, Route } from 'react-router-dom'
import Home from './pages/Home'
import About from './pages/About'
function App() {
return (
<Router>
<Routes>
<Route path="/" element={<Home />} />
<Route path="/about" element={<About />} />
</Routes>
</Router>
)
}
export default App
2. 调整Electron主进程加载路径
Electron主进程加载页面时，需要确保路径正确匹配HashRouter的路由规则，以下是主进程的配置示例：
// main.js 主进程文件
import { app, BrowserWindow } from 'electron'
import { join } from 'path'
let mainWindow = null
function createWindow() {
mainWindow = new BrowserWindow({
width: 1200,
height: 800,
webPreferences: {
preload: join(__dirname, 'preload.js'),
nodeIntegration: false,
contextIsolation: true
}
})
// 开发环境加载vite启动的服务地址，生产环境加载本地打包文件
if (process.env.NODE_ENV === 'development') {
// 注意这里不需要额外处理路由，HashRouter会自动处理#后面的路径
mainWindow.loadURL('http://localhost:5173')
} else {
// 生产环境加载打包后的index.html，HashRouter会基于本地文件处理路由
mainWindow.loadFile(join(__dirname, '../dist/index.html'))
}
}
app.whenReady().then(() => {
createWindow()
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) {
createWindow()
}
})
})
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') {
app.quit()
}
})
3. 验证配置效果
完成上述配置后，重新启动Electron-vite项目，在地址栏输入http://localhost:5173/#/about，如果能正常显示About页面，说明配置生效，空白屏问题已经解决。
注意事项
- 如果项目中使用了第三方路由库，需要确认该库是否支持HashRouter模式，部分旧版本的路由库可能需要额外配置。
- 生产环境打包时，要确保静态资源的路径是相对路径，避免因为资源路径错误导致页面加载异常。
- 如果项目中同时使用了前端路由和Electron的导航事件，需要注意两者的逻辑冲突，比如避免用Electron的API直接修改页面URL导致路由失效。
如果切换HashRouter后仍然出现空白屏，可以打开Electron的开发者工具，查看控制台的错误信息，通常错误提示会直接指向资源加载失败或者路由匹配失败的原因，根据提示进一步调整配置即可。
ElectronElectron-viteHashRouter前端路由修改时间：2026-07-06 02:42:22