天接云涛1. 问题现象与背景分析
最近在将一个Vue项目部署到IIS服务器后，遇到了一个典型的前端路由问题：当在浏览器中直接访问首页时一切正常，但如果在非首页位置进行页面刷新，就会返回404错误。这个现象在Vue等单页应用(SPA)部署到IIS时非常常见，其本质原因是IIS服务器对前端路由的处理机制与SPA的工作方式存在冲突。
在开发环境下，我们使用Vue CLI或Vite等工具启动的开发服务器已经内置了对前端路由的支持。但当我们把打包后的静态文件部署到IIS这样的生产环境服务器时，默认情况下IIS会尝试根据浏览器地址栏的URL路径去寻找对应的物理文件或目录，而Vue的路由实际上是客户端路由，这些路径在服务器端并不存在真实文件对应。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 理解Vue路由与服务器配置的关系
2.1 Vue路由的两种模式
Vue Router支持两种路由模式：
- hash模式：使用URL的hash部分（即#号后面的内容）来实现路由，例如
http://example.com/#/about - history模式：利用HTML5 History API实现无#的URL，例如
http://example.com/about
在hash模式下，由于URL改变的是#后面的部分，浏览器不会向服务器发送请求，因此刷新页面不会导致404问题。而在history模式下，每次URL改变都会被视为一个新的服务器请求，如果服务器没有正确配置，就会导致404错误。
2.2 IIS对URL请求的处理流程
当请求到达IIS服务器时，它会按照以下顺序处理：
- 检查请求的URL是否匹配服务器上的物理文件
- 如果没有匹配的文件，检查是否配置了对应的处理程序映射
- 如果都没有匹配，则返回404错误
对于Vue的history模式路由，像/about这样的路径在服务器上并不存在对应的about.html文件，因此IIS默认会返回404。
3. 解决方案：配置IIS URL重写规则
3.1 安装URL Rewrite模块
首先确保IIS服务器已安装URL Rewrite模块。如果没有安装，可以：
- 从Microsoft官网下载URL Rewrite模块
- 运行安装程序
- 安装完成后重启IIS管理器
3.2 配置web.config文件
在Vue项目的public文件夹（或打包后的dist文件夹）中创建或修改web.config文件，添加以下内容：
xml复制<configuration>
<system.webServer>
<rewrite>
<rules>
<rule name="Handle History Mode and custom 404/500" 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>
这个配置的作用是：
- 当请求的不是实际存在的文件或目录时
- 将请求重写到index.html
- 由Vue Router处理实际的路由逻辑
3.3 部署注意事项
- 确保web.config文件随其他静态文件一起部署到服务器
- 检查IIS中对应站点的处理程序映射是否包含StaticFile模块
- 如果使用子目录部署，需要调整重写规则中的URL路径
4. 进阶配置与优化
4.1 静态文件缓存控制
为了提高性能，可以配置静态文件的缓存策略。在web.config中添加：
xml复制<staticContent>
<clientCache cacheControlMode="UseMaxAge" cacheControlMaxAge="30.00:00:00" />
</staticContent>
4.2 自定义错误页面
虽然我们解决了刷新404问题，但仍可以配置自定义错误页面提升用户体验：
xml复制<httpErrors>
<remove statusCode="404" subStatusCode="-1" />
<error statusCode="404" path="/index.html" responseMode="ExecuteURL" />
</httpErrors>
4.3 启用HTTP压缩
减少资源传输大小：
xml复制<urlCompression doStaticCompression="true" doDynamicCompression="true" />
5. 常见问题排查
5.1 配置未生效的可能原因
- URL Rewrite模块未正确安装：检查IIS管理器左侧是否有"URL重写"图标
- web.config位置错误：确保文件在网站根目录
- IIS缓存：修改配置后尝试重启IIS或应用池
- 权限问题：确保IIS_IUSRS有读取web.config的权限
5.2 混合内容问题
如果网站使用HTTPS，但部分资源通过HTTP加载，会导致混合内容警告。解决方案：
- 确保所有资源使用相对路径或HTTPS绝对路径
- 在web.config中添加HTTP严格传输安全头：
xml复制<httpProtocol>
<customHeaders>
<add name="Strict-Transport-Security" value="max-age=31536000" />
</customHeaders>
</httpProtocol>
5.3 子目录部署的特殊处理
如果Vue应用部署在子目录（如http://example.com/app/），需要：
- 在Vue Router配置中设置base选项：
javascript复制const router = createRouter({
history: createWebHistory('/app/'),
routes
})
- 修改web.config中的重写规则：
xml复制<action type="Rewrite" url="/app/index.html" />
6. 替代方案与比较
6.1 使用hash模式
如果不方便修改服务器配置，可以考虑使用hash模式路由：
javascript复制const router = createRouter({
history: createWebHashHistory(),
routes
})
优点：
- 无需服务器端配置
- 兼容性更好
缺点：
- URL中包含#号，不够美观
- 某些SEO场景可能受影响
6.2 使用Node.js服务器
如果环境允许，可以考虑使用Node.js服务器（如Express）代替IIS：
javascript复制const express = require('express')
const history = require('connect-history-api-fallback')
const app = express()
app.use(history())
app.use(express.static('dist'))
app.listen(3000)
优点：
- 配置更简单灵活
- 更适合现代前端开发生态
缺点：
- Windows环境下性能可能不如IIS
- 需要额外维护Node.js环境
7. 最佳实践建议
-
开发与生产环境一致性：尽量保持开发环境和生产环境的路由模式一致，避免因模式不同导致的问题
-
自动化部署：将web.config纳入版本控制，并确保部署流程自动包含此文件
-
监控与日志：配置IIS日志记录，监控404错误，确保重写规则正常工作
-
性能考量：对于大型应用，考虑使用懒加载路由减少初始加载时间
-
渐进式增强：对于关键页面，考虑服务端渲染(SSR)或预渲染(Prerendering)以改善SEO和首屏性能
在实际项目中，我曾遇到过因缓存导致配置不生效的情况。解决方案是：
- 修改web.config后重启应用池
- 在浏览器中使用无痕模式测试
- 使用F12开发者工具禁用缓存进行调试
另一个常见陷阱是路径大小写问题。Windows服务器默认不区分大小写，但Vue Router是区分大小写的。确保路由定义和链接使用一致的大小写，或者使用路由的caseSensitive选项进行控制。