托管在Azure的React应用页面刷新时URL失效求快速解决方案

架构老林

2026-10-2

React路由刷新404（GitHub Actions自动构建场景）解决方案

问题根源：单页应用采用客户端路由逻辑，本地开发的dev-server默认配置了所有请求回退到index.html，生产环境服务端没有对应配置的话，直接访问嵌套路由就会返回404。以下是不同优先级的可行方案：

最快无侵入方案（无需改CI/服务端配置）

直接将路由模式从BrowserRouter替换为HashRouter，修改代码后推送到仓库，GitHub Actions自动构建后即可生效：

打开项目入口文件（通常是src/index.js/src/main.jsx）
替换导入和组件声明：

// 替换前
import { BrowserRouter } from 'react-router-dom'
ReactDOM.createRoot(document.getElementById('root')).render(
  <BrowserRouter>
    <App />
  </BrowserRouter>
)

// 替换后
import { HashRouter } from 'react-router-dom'
ReactDOM.createRoot(document.getElementById('root')).render(
  <HashRouter>
    <App />
  </HashRouter>
)

缺点是URL会携带#前缀，例如你的域名.com/#/about，不影响功能使用

无hash干净URL方案（无需修改GitHub Actions核心脚本）

以下配置直接加到项目代码里，GitHub Actions正常执行npm run build就会自动把配置打包到构建产物中，无需调整原有构建流程：

部署到Netlify/Vercel
在public文件夹下新建名为_redirects的文件，写入以下内容即可：
```
/*  /index.html  200
```
部署到Nginx服务器
在项目根目录新增Nginx配置文件，在server区块中添加以下规则：
```
location / {
  try_files $uri $uri/ /index.html;
}
```
只需在GitHub Actions的部署步骤中增加一行将该配置复制到服务器对应配置目录的指令即可，原有构建逻辑完全不用改
部署到GitHub Pages
在public文件夹下新建404.html文件，复制public/index.html的全部内容到该文件即可，所有404请求会自动回退到这个页面走客户端路由