Electron集成React Router遇阻：HashRouter构建后页面无法渲染

问题描述 #

开发了一个基于React的Electron应用，使用react-router-dom为不同窗口路由到不同组件，渲染代码如下：

ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
    <React.StrictMode>
        <HashRouter>
            <Routes>
                <Route path='/' element={<App />} />
                <Route path='add' element={<LinkDialog/>} />
                <Route path='modify' element={<LinkDialog/>} />
                <Route path='edit' element={<EditDialog />} />
            </Routes>
        </HashRouter>
    </React.StrictMode>
)

窗口路由加载代码：

const VITE_DEV_SERVER_URL = process.env['VITE_DEV_SERVER_URL']
process.env.DIST = path.join(__dirname, '../dist')
const loadRoute = (window, route) => {
    if (VITE_DEV_SERVER_URL) {
        const url = new URL(VITE_DEV_SERVER_URL)
        url.pathname = route
        window.loadURL(url.href)
    } else {
        window.loadFile(path.join(process.env.DIST, '../renderer/index.html'), { hash: route })
    }
}

调试时用BrowserRouter页面正常显示，但构建后切换为HashRouter页面无法渲染，同时需要实现开发/构建模式自动切换Router类型。

一、构建后HashRouter页面无法渲染的解决 #

问题根源 #

生产环境使用HashRouter时，路由依赖URL的hash部分，格式应为/#/[路由路径]。当前loadRoute代码中生产环境传入的hash参数是route（比如add），导致最终URL的hash为#add，与HashRouter默认的/#/xxx路由格式不匹配，无法命中路由表中的规则，因此页面无法渲染。

修正代码 #

修改loadRoute的生产环境逻辑，生成符合HashRouter要求的hash格式：

const VITE_DEV_SERVER_URL = process.env['VITE_DEV_SERVER_URL']
process.env.DIST = path.join(__dirname, '../dist')
const loadRoute = (window, route) => {
    if (VITE_DEV_SERVER_URL) {
        const url = new URL(VITE_DEV_SERVER_URL)
        url.pathname = `/${route}` // 确保开发环境路径格式正确
        window.loadURL(url.href)
    } else {
        // 为HashRouter生成正确的hash格式：/#/xxx
        window.loadFile(path.join(process.env.DIST, '../renderer/index.html'), { hash: `/${route}` })
    }
}

二、开发/构建模式自动切换Router类型 #

利用Vite内置的环境变量import.meta.env.DEV判断当前环境，动态选择对应的Router组件：

实现代码 #

import { BrowserRouter, HashRouter, Routes, Route } from 'react-router-dom';
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import LinkDialog from './LinkDialog';
import EditDialog from './EditDialog';

// 根据环境自动选择Router组件
const RouterComponent = import.meta.env.DEV ? BrowserRouter : HashRouter;

ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
    <React.StrictMode>
        <RouterComponent>
            <Routes>
                <Route path='/' element={<App />} />
                <Route path='add' element={<LinkDialog/>} />
                <Route path='modify' element={<LinkDialog/>} />
                <Route path='edit' element={<EditDialog />} />
            </Routes>
        </RouterComponent>
    </React.StrictMode>
)

原理说明 #

• import.meta.env.DEV在Vite开发模式下为true，生产构建时自动变为false，无需手动切换配置。
• 开发环境用BrowserRouter适配Vite dev server的路由机制，生产环境用HashRouter避免Electron加载本地静态文件时的路径解析问题。

内容的提问来源于stack exchange，提问作者LITzman