使用React Router切换页面时组件不渲染仅显白屏，刷新后才正常显示

核心排查方向 #

• 路由匹配顺序问题：通配符路由*必须放在所有路由配置的最后，React Router v6会按配置顺序优先匹配先定义的路由，通配符前置会拦截所有后续路由匹配，导致切换时命中通配符返回空白页，刷新时重新匹配会命中正确路由。
• 路由渲染写法错误：所有Route的element属性必须传入组件实例（如<Home />），不可直接传入组件构造函数（如Home）。
• 嵌套路由缺少<Outlet>占位：如果配置了嵌套子路由，父路由对应的组件内必须添加<Outlet />组件作为子路由的渲染容器，否则子路由切换时没有挂载位置，直接显示空白。
• 重复包裹BrowserRouter：BrowserRouter全局仅需在入口文件index.tsx中包裹一次，若在App.tsx或其他组件内二次包裹，会导致路由状态不同步，切换时组件无法响应路由变化。
• 懒加载组件缺少Suspense包裹：如果使用React.lazy懒加载路由组件，必须配合<Suspense>组件包裹懒加载组件，并提供fallback加载占位内容，否则组件加载过程中会渲染空白。
• 跳转路径写法错误：使用<Link>或useNavigate跳转时，若路径未加前缀/会被识别为相对路径，从当前路由后拼接路径，若没有对应路由配置就会返回空白。

正确配置参考 #

路由配置routes.tsx示例

import { RouteObject } from "react-router-dom";
import Layout from "./Layout";
import Home from "./pages/Home";
// 懒加载组件示例
const About = React.lazy(() => import("./pages/About"));
const NotFound = React.lazy(() => import("./pages/NotFound"));

export const routes: RouteObject[] = [
  {
    path: "/",
    element: <Layout />,
    children: [
      // 首页默认路由
      { index: true, element: <Home /> },
      {
        path: "about",
        // 懒加载组件必须包裹Suspense
        element: (
          <React.Suspense fallback={<div>加载中...</div>}>
            <About />
          </React.Suspense>
        )
      }
    ]
  },
  // 通配符路由必须放在最后
  {
    path: "*",
    element: (
      <React.Suspense fallback={<div>加载中...</div>}>
        <NotFound />
      </React.Suspense>
    )
  }
];

入口组件App.tsx示例

import { useRoutes } from "react-router-dom";
import { routes } from "./routes";

function App() {
  const routeElement = useRoutes(routes);
  return <>{routeElement}</>;
}

export default App;

项目入口index.tsx示例

import React from "react";
import ReactDOM from "react-dom/client";
import { BrowserRouter } from "react-router-dom";
import App from "./App";

const root = ReactDOM.createRoot(
  document.getElementById("root") as HTMLElement
);

// 全局仅包裹一次BrowserRouter
root.render(
  <BrowserRouter>
    <App />
  </BrowserRouter>
);

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