如何解决React Router Dom在CI/CD部署中导航失效的问题

React Router Dom是React生态中常用的路由管理工具，很多项目在本地开发时路由跳转一切正常，但是经过CI/CD流水线部署到生产环境后，就会出现点击导航链接返回404、页面无法加载的问题，这会影响用户的正常使用体验。

问题产生的常见原因

1. 使用了BrowserRouter模式但未配置服务器回退规则

React Router Dom的BrowserRouter模式依赖HTML5的history API，路由路径是真实的URL路径，比如/user/list。本地开发时webpack-dev-server默认配置了回退到index.html的规则，所以刷新或者直接访问路由路径不会报错。但是很多静态服务器默认没有这个配置，当直接访问或者刷新路由路径时，服务器会去寻找对应路径的静态文件，找不到就会返回404。

2. CI/CD部署流程中静态资源路径配置错误

如果项目打包后的静态资源基础路径配置错误，比如设置了错误的homepage或者basename，会导致路由匹配时路径拼接错误，进而出现导航失效的情况。

3. 路由配置存在大小写或者路径拼写问题

部分服务器对路径的大小写敏感，本地开发时系统可能不区分大小写，但是部署到Linux环境的服务器后，路径大小写不匹配就会导致路由无法匹配。

对应的解决方案

方案一：配置服务器回退规则

如果是用Nginx作为静态服务器，需要在Nginx配置文件中添加如下规则，让所有不存在的静态资源请求都回退到index.html，由React Router来处理路由匹配：

server {
    listen 80;
    server_name your_domain.com;
    root /usr/share/nginx/html;
    index index.html;

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

如果是用Apache服务器，需要在项目根目录的.htaccess文件中添加如下配置：

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

方案二：检查并修正静态资源路径配置

如果项目部署在子路径下，比如https://ipipp.com/admin/，需要在BrowserRouter中设置basename属性，同时在package.json中设置正确的homepage：

// 路由配置文件中
import { BrowserRouter } from 'react-router-dom';

function App() {
  return (
    <BrowserRouter basename="/admin">
      {/* 路由组件内容 */}
    </BrowserRouter>
  );
}

export default App;

package.json中的配置：

{
  "name": "your-project",
  "homepage": "/admin",
  "dependencies": {
    "react-router-dom": "^6.0.0"
  }
}

方案三：统一路由路径的大小写规范

在路由配置时统一使用小写路径，并且可以在路由跳转时做路径格式化处理，避免大小写不一致的问题：

import { useNavigate } from 'react-router-dom';

function NavComponent() {
  const navigate = useNavigate();

  const handleNavigate = (path) => {
    // 统一转为小写路径再跳转
    const formattedPath = path.toLowerCase();
    navigate(formattedPath);
  };

  return (
    <button onClick={() => handleNavigate('/User/List')}>
      跳转用户列表
    </button>
  );
}

方案四：改用HashRouter模式（临时方案）

如果暂时无法修改服务器配置，可以临时改用HashRouter模式，它的路由路径会带#前缀，比如/#/user/list，服务器只会处理#之前的部分，不会把路由路径当作静态资源路径请求，但是这种方式会改变URL的表现形式，适合作为临时解决方案：

import { HashRouter } from 'react-router-dom';

function App() {
  return (
    <HashRouter>
      {/* 路由组件内容 */}
    </HashRouter>
  );
}

export default App;

CI/CD流程中的注意事项

在CI/CD流水线中，需要确保部署脚本正确复制了所有的路由配置文件，比如Nginx的配置文件、.htaccess文件等，避免这些配置文件在打包或者部署过程中被遗漏。同时可以在部署完成后添加自动化测试步骤，模拟直接访问路由路径，验证路由功能是否正常。

如果使用的是云服务的静态托管功能，比如阿里云OSS静态托管、腾讯云静态网站托管，需要在托管配置中设置默认404页面为index.html，这样也能实现和服务器回退规则相同的效果。

React_Router_DomCI/CD前端部署路由配置修改时间：2026-07-15 16:06:28