React应用通过IIS发布后react-router刷新报404错误求助

问题原因 #

React属于单页应用（SPA），前端路由由JavaScript在浏览器端处理。刷新页面时，浏览器会直接向IIS请求对应路径的物理文件，但这些路由路径并不存在实际的服务器文件，因此返回404错误。

两种实用解决方法 #

方法一：配置IIS URL重写规则 #

1. 先确认IIS已安装URL重写模块：打开服务器管理器 -> 添加角色和功能 -> 找到「Web服务器（IIS）」-> 「Web服务器」-> 「应用程序开发」，勾选「URL重写」完成安装。
2. 在React应用的部署根目录（即index.html所在文件夹）中，创建或修改web.config文件，添加以下配置：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="React Routes" stopProcessing="true">
          <match url=".*" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
            <add input="{REQUEST_URI}" pattern="^/(api)" negate="true" /> <!-- 若有后端API路由，需排除，避免被重定向 -->
          </conditions>
          <action type="Rewrite" url="/" />
        </rule>
      </rules>
    </rewrite>
    <staticContent>
      <!-- 可选：配置静态资源缓存，提升加载速度 -->
      <clientCache cacheControlMode="UseMaxAge" cacheControlMaxAge="7.00:00:00" />
    </staticContent>
  </system.webServer>
</configuration>

3. 保存文件后重启IIS站点，刷新页面测试即可。

方法二：切换为Hash路由（无需修改IIS） #

如果不想配置IIS，可以直接修改React的路由模式：

1. 在项目的路由配置文件中，将BrowserRouter替换为HashRouter（以react-router-dom v6+为例）：

// 原代码
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';

// 修改后
import { HashRouter as Router, Routes, Route } from 'react-router-dom';

2. 重新执行npm run build生成生产包，将新的build目录文件重新部署到IIS，刷新页面即可正常访问。

注意事项 #

• 方法一中的web.config必须放在应用部署根目录，否则规则不生效。
• 若项目包含后端API接口，务必在重写规则中排除API路径，防止API请求被错误重定向到首页。
• 部署前确认使用的是npm run build生成的生产环境包，且所有build目录下的文件都已正确上传到IIS站点。

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