React Router 页面空白的本质通常是路由匹配失败或者组件树没有被正确挂载。和普通渲染错误不同，这类问题不一定会触发红色报错，因为 React Router 对未匹配的路径会静默返回空结果，最终页面上只有一个空白的根节点。排查时需要从容器、路由表、嵌套关系、通配符和部署路径几个层面依次确认，下面按照实际项目中出现频率从高到低展开说明。

一、根组件没有包在 Router 容器中

最常见的空白原因是应用根组件没有被 BrowserRouter 或 HashRouter 包裹。React Router 的所有路由匹配都依赖 Router 容器提供的上下文，如果 Route 或 useRoutes 出现在容器外部，轻则页面空白，重则控制台提示当前组件不在 Router 上下文中。尤其是把路由表拆成独立文件后，很容易忘记在入口处包裹容器。

正确做法是在 ReactDOM.createRoot 渲染入口处就包好 BrowserRouter，子组件内部不再重复包裹。下面是一个标准入口配置：

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'));
root.render(
  <BrowserRouter>
    <App />
  </BrowserRouter>
);

如果项目部署在静态服务器上，或者路由需要兼容老式服务器，也可以改用 HashRouter。两者都能提供路由上下文，区别只在 URL 格式。关键是外层容器不能省略，也不能放在某个条件分支里导致部分页面渲染时容器不存在。

二、v5 和 v6 语法混用导致路由表失效

从 React Router v5 升级到 v6 后，一些核心组件名和属性变化很大。如果在 v6 项目中继续使用 Switch、component 或 exact，路由不会按预期工作。v6 已经移除了 Switch，统一使用 <Routes>；子路由通过 element 传入 JSX 元素，而不是组件引用；exact 也不再需要，因为 v6 的匹配逻辑默认更精确。

很多空白问题正是把 v5 写法直接搬进了 v6 环境。比如下面的错误写法：

// 这段代码在 v6 中无法正确渲染
import { Switch, Route } from 'react-router-dom';
function App() {
  return (
    <Switch>
      <Route exact path="/" component={Home} />
      <Route path="/about" component={About} />
    </Switch>
  );
}

在 v6 中应该改成：

import { Routes, Route } from 'react-router-dom';
function App() {
  return (
    <Routes>
      <Route path="/" element={<Home />} />
      <Route path="/about" element={<About />} />
    </Routes>
  );
}

如果项目是从 v5 迁移而来，建议全局搜索 Switch 和 component= 关键字，逐项替换为 Routes 和 element=。迁移后还要删除多余的 exact 属性，避免理解上的混淆。

三、嵌套路由没有配置 Outlet 或 index 路由

嵌套路由是另一个容易造成空白的地方。v6 中父路由对应的组件必须渲染一个 <Outlet> 占位符，子路由匹配到的组件才会显示在指定位置。如果父组件只写了标题、侧边栏等内容，却没有放置 <Outlet>，那么访问子路径时页面看似父布局在，但核心区域一片空白。

正确的嵌套结构如下：

import { Routes, Route, Outlet } from 'react-router-dom';
function Dashboard() {
  return (
    <div>
      <h2>Dashboard</h2>
      <Outlet />
    </div>
  );
}
function App() {
  return (
    <Routes>
      <Route path="/dashboard" element={<Dashboard />}>
        <Route index element={<Overview />} />
        <Route path="settings" element={<Settings />} />
      </Route>
    </Routes>
  );
}

这里的 index 子路由很关键。访问 /dashboard 时，只有配置了 index 路由才会渲染默认内容。如果给父路径配置了多个子路径，却漏掉 index 路由，访问父路径本身时内容区会空白。补上 <Route index element={...} /> 即可解决。

四、通配符路由位置错误或大小写问题

通配符路由 path="*" 常用于 404 页面，但如果放置顺序不对，会导致其他路由全部被吞掉。React Router 的匹配顺序是按 <Routes> 内的声明顺序执行，因此 * 必须放在所有具体路由之后。假设把 <Route path="*" element={<NotFound />} /> 写在最前面，那么访问任何路径都会渲染 NotFound，主页面看起来就是空白或错误页。

另一个容易被忽略的点是 React Router 默认对路径大小写敏感。项目里访问 /About 时，如果只配置了 /about，两者不会匹配。遇到空白但路径看起来正常时，可以检查 URL 的大小写是否和路由表完全一致。必要时可以在路由配置中统一转小写，或者使用 caseSensitive 参数明确匹配规则。

五、部署子路径未设置 basename

当 React 应用部署到服务器的子目录，例如 https://ipipp.com/admin，而本地开发一直用根路径访问，上线后很容易出现页面空白。此时 BrowserRouter 默认认为应用根路径是域名的根目录，所有路由都会从 / 开始匹配。如果实际访问路径带有 /admin 前缀，路由表里的 /about 永远匹配不到，最终渲染出空白或站点 404 页面。

解决办法是给 BrowserRouter 增加 basename 属性：

<BrowserRouter basename="/admin">
  <App />
</BrowserRouter>

同时要确认构建工具的输出路径和服务器配置。如果前端资源本身加载失败，页面会直接白屏，这种情况要先在浏览器开发者工具的 Network 面板里确认 JS 和 CSS 是否返回 200。资源路径正常后，再检查 basename 是否和部署目录一致。

六、快速排查清单

实际处理 React Router 页面空白时，可以按照下面顺序快速过一遍：先看入口文件是否包裹了 Router；再看使用的是 v5 还是 v6 语法，组件名是否写错；接着检查嵌套路由的 Outlet 和 index 配置；然后确认通配符是否放在最后；最后核对部署子路径的 basename。这个顺序基本能覆盖绝大多数空白场景，避免反复在组件内部加日志却找不到原因。

如果以上步骤都检查过仍无法解决，可以在路由组件中临时加一个简单的文本节点，确认是路由没匹配到还是组件本身渲染异常。定位到具体环节后，再根据对应小节的代码示例修正即可。