React+Vite预览模式下非根页面刷新失败问题求助

问题本质 #

SPA采用history路由模式时，刷新非根路径（如/account-settings/account）会直接向服务器请求该路径的物理文件，但静态服务器中不存在对应文件，因此返回404错误。Vite开发服务器默认配置了historyApiFallback规则，自动将所有路由请求重定向到index.html，但vite preview默认未开启该配置，导致预览模式下出现问题。

解决方案 #

1. 配置Vite预览服务器启用History Fallback #

修改vite.config.ts，在配置中添加preview选项并开启historyApiFallback：

export default defineConfig(() => ({
    server: {
        port: 8080,
        open: true,
    },
    // 新增预览服务器配置
    preview: {
        port: 4173,
        historyApiFallback: true,
    },
    base: './',
    build: { outDir: './dist' },
    plugins: [react(), tsconfigPaths(), prismaPlugin()],
    resolve: { alias: { '@/styles': path.join(__dirname, 'src', 'styles') } },
}));

配置后，vite preview启动的服务器会将所有非根路径请求重定向到index.html，由SPA路由接管页面渲染。

2. 生产环境部署的服务器配置 #

为避免生产环境出现同类问题，部署时需给静态服务器配置对应的fallback规则：

• Nginx：在站点配置中添加

location / {
    try_files $uri $uri/ /index.html;
}

• Express：使用connect-history-api-fallback中间件

const express = require('express');
const history = require('connect-history-api-fallback');
const app = express();

app.use(history());
app.use(express.static('dist'));

app.listen(3000);

• Apache：在项目根目录的.htaccess文件中添加

RewriteEngine On
RewriteBase /
RewriteRule ^index\.html$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.html [L]

额外确认 #

确保你的React路由使用的是BrowserRouter（而非HashRouter），HashRouter通过URL哈希值处理路由不会出现刷新问题，但URL会带有#；若无需哈希路由，BrowserRouter配合服务器fallback是标准解决方案。

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