React HashRouter+Nginx路由404问题及配置优化咨询

问题根源 #

当前Nginx配置中，location = /edit仅精确匹配不带斜杠的请求，而location ~* /edit/(.*)会尝试将/edit/后的路径当作静态文件查找，忽略了单页应用（SPA）需要统一返回index.html的核心需求。HashRouter的#后内容属于客户端路由，不会发送到服务器，但当请求路径为/edit/时，服务器因找不到对应静态文件返回404。

修正后的Nginx配置 #

server {
  listen        8081;
  server_name   _;

  location = / {
    root      /usr/share/nginx/html;
    try_files /index.html =404;
  }

  location / {
    root      /usr/share/nginx/html;
    index     index.html index.htm;
    try_files /portal$uri /static$uri =404;
  }

  # 统一处理所有/edit开头的请求
  location ^~ /edit {
    root      /usr/share/nginx/html/editor;
    index     index.html;
    try_files $uri $uri/ /index.html;
  }
}

配置说明 #

• ^~ /edit：设置更高优先级，确保所有以/edit开头的请求都匹配该规则，避免被其他通用或正则规则拦截
• try_files $uri $uri/ /index.html：先尝试访问请求的静态文件/目录，不存在则直接返回index.html，完美适配SPA的客户端路由逻辑
• index index.html：显式指定默认索引文件，确保访问/edit/时自动返回index.html

前端侧可选调整 #

如果不想修改Nginx配置，可以在React项目中设置HashRouter的basename，让路由跳转路径不带额外斜杠：

import { HashRouter, Routes, Route } from 'react-router-dom';

function App() {
  return (
    <HashRouter basename="/edit">
      <Routes>
        <Route path="/page1" element={<Page1 />} />
        {/* 其他路由 */}
      </Routes>
    </HashRouter>
  );
}

调整后跳转路径会变为/edit#/page1，可匹配原Nginx的location = /edit规则。

内容的提问来源于stack exchange，提问作者Alexei Delezhov