React Router二级路径刷新/手动输入失效（Webpack构建）求助

问题描述 #

使用React Router v6开发单页应用，点击Link组件跳转页面功能正常，但部署到服务器后，刷新二级路径（如https://sample.cc/sport/soccer）会出现空白屏，一级路径（如https://sample.cc/sport）则无问题。本地运行一切正常，控制台无警告，所有网络请求均返回200。应用包含嵌套路由，推测问题出在Webpack构建环节，用Vite构建可解决，现需通过Webpack配置解决该问题。

问题根源 #

SPA使用createBrowserRouter时，二级路径属于前端路由逻辑，服务器收到/sport/soccer这类请求时，会尝试寻找对应物理文件，但实际项目中不存在该路径的文件，因此返回404，导致页面空白。Vite默认内置了前端路由的重定向处理，而Webpack需要手动配置配合服务器完成路由 fallback。

Webpack配置修改 #

1. 生产环境配置调整 #

在Webpack的output和HtmlWebpackPlugin中添加公共路径配置，确保资源加载路径正确，同时为后续服务器重定向做准备：

修改后的Webpack生产配置关键片段：

module.exports = {
    // ... 其他配置
    output: {
        path: path.resolve(__dirname, 'dist'),
        clean: true,
        publicPath: '/', // 核心：设置所有资源的根路径为站点根目录
        filename: 'static/js/[name].[contenthash].js', // 可选：优化缓存，避免资源缓存冲突
        chunkFilename: 'static/js/[name].[contenthash].chunk.js' // 可选：拆分代码块的命名
    },
    plugins: [
        new HtmlWebpackPlugin({
            template: path.join(__dirname, 'public', 'index.html'),
            publicPath: '/' // 确保与output.publicPath一致，避免资源加载路径错误
        }),
    ],
    // ... 其他配置
};

2. 开发环境测试配置（可选） #

如果需要在本地开发环境测试二级路径刷新功能，添加devServer的historyApiFallback配置，让开发服务器将所有请求重定向到index.html：

module.exports = {
    // ... 其他配置
    devServer: {
        historyApiFallback: true, // 开发环境下重定向所有请求到index.html
        open: true,
        hot: true
    },
    // ... 其他配置
};

服务器端必须配置 #

仅修改Webpack配置无法彻底解决问题，服务器需要将所有路由请求重定向到index.html，以下是常见服务器的配置示例：

• Nginx：在站点配置文件中添加

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

• Apache：在项目根目录创建.htaccess文件

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

• Express：在后端服务中添加路由 fallback

const express = require('express');
const path = require('path');
const app = express();

app.use(express.static(path.join(__dirname, 'dist')));

// 所有请求重定向到index.html
app.get('*', (req, res) => {
    res.sendFile(path.join(__dirname, 'dist', 'index.html'));
});

app.listen(3000, () => console.log('Server running on port 3000'));

验证步骤 #

1. 执行npm run build重新构建项目
2. 将dist目录部署到服务器
3. 测试刷新二级路径、手动输入二级路径，确认页面正常加载

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