React Vite部署IIS后刷新内部页面出现404错误求助

问题根源 #

React单页应用（SPA）的路由属于前端路由，点击页面导航时是通过JS在前端切换组件，不会向服务器发起新请求。但刷新页面时，浏览器会直接向服务器请求/Prefrences这类路径，IIS会尝试寻找对应的物理文件或目录，找不到就返回404错误。

解决步骤 #

1. 安装IIS URL重写模块
   打开IIS管理器，检查是否已安装「URL重写」模块。如果未安装，需先安装该模块（可通过IIS管理器的模块管理入口添加）。

2. 添加web.config配置文件
   在部署后的项目根目录（即包含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="30.00:00:00" />
       </staticContent>
     </system.webServer>
   </configuration>
   

   该配置会将所有非物理文件、非目录、非API接口的请求，重写到根目录的index.html，交由React前端路由处理。

3. 优化Vite配置（可选）
   如果你的应用部署在根路径下，可在vite.config.js中显式设置base参数（子路径部署时需改为对应路径，比如/my-app/）：

   import { defineConfig } from 'vite'
   import react from '@vitejs/plugin-react'
   
   export default defineConfig({
     plugins: [react()],
     base: '/',
     build: {
       mode: "production", 
     },
   });
   

验证 #

配置完成后重启IIS站点，刷新/Prefrences这类内部页面，即可正常加载。

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