Vite应用部署IIS后刷新非首页出现404问题排查

问题场景 #

• 已执行npm run build构建单页应用，将dist目录内容部署至inetpub/wwwroot/sitename
• 首页可正常访问，通过前端路由的router.push(...)跳转页面功能正常
• 但刷新非首页页面、或直接通过导航链接访问子页面时，出现404错误
• 已添加web.config配置（先后尝试过<action type="Rewrite" url="/" />和<action type="Rewrite" url="/index.html" />），且已安装IIS的URL Rewrite扩展，问题仍未解决

常见排查方向 #

1. 确认URL Rewrite模块生效状态
   打开IIS管理器，查看对应站点的「模块」列表，确认RewriteModule已加载。若未找到，需重新安装URL Rewrite扩展并重启IIS。

2. 检查web.config位置与规则正确性

   • web.config必须放置在站点根目录（即inetpub/wwwroot/sitename下），不能放在子文件夹中
   • 单页应用的标准Rewrite规则应排除静态资源（文件/目录），将其余请求重定向到index.html，示例配置：

     <configuration>
       <system.webServer>
         <rewrite>
           <rules>
             <rule name="SPA Route Rewrite" stopProcessing="true">
               <match url=".*" />
               <conditions logicalGrouping="MatchAll">
                 <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
                 <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
               </conditions>
               <action type="Rewrite" url="/index.html" />
             </rule>
           </rules>
         </rewrite>
       </system.webServer>
     </configuration>
     

3. 验证站点权限
   确保站点对应的应用池账号对dist目录拥有读取权限，避免因权限问题导致规则无法生效。

4. 重启Web服务器/应用池
   IIS的配置修改（如URL Rewrite规则、web.config更新）常需重启才能生效，这也是本次问题的最终解决手段。

最终解决方法 #

通过重启Web服务器，使URL Rewrite模块与web.config的配置生效，解决了刷新非首页页面的404问题。

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