React Router v6.14.0 部署后刷新 404 问题终极解决方案

苏承栈

2026-10-26 • 👁 0人浏览过

React Router v6.14.0 使用 createBrowserRouter 时，生产环境手动输入 URL 或刷新页面返回 404，本质是服务端未将所有路由请求回退至 index.html，需通过服务器配置实现前端路由的正确兜底。 react router v6.14.0 使用 `createbrowserrouter` 时，生产环境手动输入 url 或刷新页面返回 404，本质是服务端未将所有路由请求回退至 `index.html`，需通过服务器配置实现前端路由的正确兜底。当使用 createBrowserRouter 构建基于浏览器历史的客户端路由（Client-Side Routing）时，React Router 完全依赖 JavaScript 在浏览器中接管导航逻辑——它不会向服务器发起真实页面请求，而是通过 history.pushState() 修改 URL 并动态渲染组件。但这一机制有个关键前提：所有非静态资源（如 /about-us、/dashboard/settings）的 HTTP 请求，必须由 Web 服务器统一返回 index.html，再交由 React Router 解析路径并匹配对应路由。否则，当你直接访问 https://yoursite.com/about-us 或刷新该页面时，服务器会尝试查找物理存在的 /about-us 目录或文件，找不到即返回标准 HTTP 404 —— 此时你的组件根本不会执行，因为 React 根本没启动。 ✅ 正确解决方案：服务端路由回退配置不同部署环境需不同配置，以下是主流场景的权威方案： ▪ Apache 服务器（如 cPanel、VPS 自建）在项目根目录（即 index.html 所在目录）创建 .htaccess 文件，内容如下：


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

✅ 原理说明： RewriteCond %{REQUEST_FILENAME} !-f：请求路径不是真实文件 RewriteCond %{REQUEST_FILENAME} !-d：请求路径不是真实目录 RewriteCond %{REQUEST_FILENAME} !-l：请求路径不是符号链接 → 满足以上全部条件时，强制将请求重写为 /index.html，交由 React 渲染。 ⚠️ 注意：确保服务器已启用 mod_rewrite 模块；若使用子目录部署（如 https://site.com/my-app/），需将 RewriteBase / 改为 RewriteBase /my-app/。 React Native For Android 源码编译中文WORD版本文档主要讲述的是React Native For Android 源码编译；希望对大家会有帮助；感兴趣的朋友可以过来看看下载 ▪ Nginx 服务器在 server 块中添加 try_files 指令：

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

▪ Vercel / Netlify / Cloudflare Pages（无配置文件）这些平台默认支持 SPA 路由，无需额外操作。只需确保： build 输出目录正确（如 dist 或 build）； 404.html 不是必需项（React Router 的 * 路由已处理逻辑 404）；若仍出现 404 页面，检查是否误将 404.html 作为真实响应（应删除或忽略，由 JS 控制）。 ▪ GitHub Pages（不推荐用于生产，但可应急） spa-github-pages 方案失效常因脚本未正确注入或缓存问题。更可靠方式是：确保 package.json 中 "homepage": "https://username.github.io/repo-name" 已设置；构建前运行 npm run build（自动适配路径）；删除 public/404.html ，避免 GitHub Pages 优先返回该静态页，覆盖 React 路由；确保 createBrowserRouter 中的 * 路由存在且生效（你代码中已正确配置）。 ? 验证是否生效部署后，打开浏览器开发者工具 → Network 标签页，刷新 /about-us： ✅ 正确行为：index.html 返回 200，后续 JS 加载并渲染； ❌ 错误行为：/about-us 请求返回 404（说明服务器未回退）。 ? 补充建议不要依赖 404.html 显示自定义 404 页面：React Router 的 * 路由（如你的）负责应用内逻辑 404 ；真正的 HTTP 404 应由服务器避免发生。开发阶段使用 vite preview 或 npx serve -s build 测试构建后行为，它们模拟了真实服务器的 SPA 回退逻辑。若使用自定义服务端（如 Express），需显式添加兜底路由：

app.get("*", (req, res) => {
  res.sendFile(path.join(__dirname, "build", "index.html"));
});

通过以上任一服务端配置，即可彻底解决 createBrowserRouter 在生产环境的刷新 404 问题，让组件按预期展示，同时保障所有嵌套路由、动态参数、搜索参数等功能完整可用。

相关文章