Ant Design Pro 项目部署后页面刷新404问题的解决方案

问题现象分析

在使用Ant Design Pro框架开发的项目部署到服务器后，用户遇到了一个典型的前端路由问题：当从首页进入应用后，页面跳转和导航都能正常工作，但如果在非首页位置刷新页面，服务器会返回404错误。这种问题在单页应用(SPA)部署时十分常见。

问题根源探究

这种现象的根本原因在于Ant Design Pro默认使用的是基于HTML5的history路由模式。在这种模式下：

1. 前端路由通过JavaScript动态管理页面内容
2. 浏览器地址栏的URL变化不会真正向服务器发起请求
3. 当用户直接访问某个路径或刷新页面时，浏览器会向服务器请求该路径的资源
4. 服务器如果没有特殊配置，会尝试查找对应路径的文件，导致404错误

解决方案

方案一：配置正确的服务器路由

对于使用Nginx作为Web服务器的项目，需要在配置文件中添加以下规则：

location / {
  try_files $uri $uri/ /index.html;
}

这条规则告诉Nginx，当请求的文件不存在时，返回index.html文件，由前端路由接管后续处理。

方案二：修改Ant Design Pro配置

在Ant Design Pro项目中，可以通过修改配置文件来调整路由行为：

1. 在config/config.ts文件中设置hash路由模式
2. 将hash参数设置为true

export default defineConfig({
  hash: true,
  // 其他配置...
});

使用hash路由模式后，URL中会包含#符号，浏览器不会将#后面的路径发送到服务器，从而避免刷新404问题。

最佳实践建议

1. 对于生产环境部署，建议同时采用两种方案：

   • 配置服务器支持history路由
   • 保留hash路由作为备选方案

2. 如果项目需要SEO支持，history路由模式更为友好

3. 在开发环境中，Umi.js开发服务器已经内置了对history路由的支持，因此开发时不会遇到此问题

总结

Ant Design Pro项目部署后的刷新404问题是一个常见的前端路由配置问题。通过合理配置服务器或修改前端路由模式，可以轻松解决这一问题。理解单页应用的路由原理对于现代前端开发至关重要，这不仅能帮助我们解决部署问题，也能为后续的性能优化和用户体验提升打下基础。