适用环境：本文适用于 React 18 + React Router v6 + Nginx 1.20 / Apache 2.4 + Node.js 16+ 环境。若你的环境与上述不同，执行前请先确认版本兼容性。

一、问题/场景描述

在React单页应用开发中，路由配置是核心环节，但开发者常遇到各种棘手问题。例如：页面刷新后出现404错误、路由跳转后组件不渲染、嵌套路由无法正常加载、动态路由参数丢失、以及使用HashRouter或BrowserRouter时出现白屏。这些问题在项目部署到生产环境后尤为突出，严重影响用户体验和开发效率。

二、原因分析

React路由配置问题的根源主要来自三方面。第一，BrowserRouter依赖服务器端路由重写，当用户直接访问非根路径时，服务器返回404而非index.html。第二，路由嵌套时未正确使用Outlet组件或路径拼接错误，导致子路由无法匹配。第三，动态路由参数（如:id）在组件中未通过useParams钩子正确获取，或路由顺序排列不当导致优先匹配了静态路由。此外，打包后静态资源路径配置错误（如publicPath）也会引发白屏问题。

三、详细解决步骤

步骤1：解决BrowserRouter刷新404问题

在Nginx服务器中配置try_files指令，将所有非文件请求重定向到index.html。

location / {
    root /var/www/your-project/build;
    index index.html;
    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]

步骤2：正确配置嵌套路由

在React Router v6中，使用Outlet组件渲染子路由内容。父组件需定义路由布局，子路由路径不要加斜杠开头。

// App.js
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import Layout from './Layout';
import Home from './Home';
import About from './About';

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Layout />}>
          <Route index element={<Home />} />
          <Route path="about" element={<About />} />
        </Route>
      </Routes>
    </BrowserRouter>
  );
}

// Layout.js
import { Outlet } from 'react-router-dom';

function Layout() {
  return (
    <div>
      <h1>导航栏</h1>
      <Outlet /> {/* 子路由组件在此渲染 */}
    </div>
  );
}

步骤3：处理动态路由参数

使用useParams钩子获取URL参数，并确保路由定义顺序正确（静态路由在前，动态路由在后）。

// 路由定义：先静态后动态
<Route path="users" element={<UserList />} />
<Route path="users/:id" element={<UserDetail />} />

// UserDetail.js
import { useParams } from 'react-router-dom';

function UserDetail() {
  const { id } = useParams();
  return <p>用户ID: {id}</p>;
}

步骤4：修复打包后白屏问题

在package.json中设置homepage字段，或在Webpack配置中调整publicPath为相对路径。

// package.json
{
  "homepage": "."
}

对于Create React App项目，直接修改package.json即可。若使用自定义Webpack，则修改：

// webpack.config.js
output: {
  publicPath: './',
  // 其他配置...
}

四、注意事项

使用BrowserRouter时，务必确保服务器端已配置URL重写规则，否则部署后刷新会报404。嵌套路由的子路径不要以斜杠开头，否则会与根路径冲突。动态路由参数需在组件内通过useParams获取，且路由顺序应遵循“静态优先”原则。生产环境打包时，检查publicPath是否设置为相对路径，避免资源加载失败。

五、适用环境

本文适用于 React 18 + React Router v6 + Nginx 1.20 / Apache 2.4 + Node.js 16+ 环境。

React路由配置常见问题及解决方案详解