Nginx部署SPA项目刷新404问题解决方案

1. 问题现象与背景分析

最近在部署Vue/React等前端项目时，不少开发者都遇到过这样的场景：通过Nginx代理访问前端页面一切正常，但当刷新页面时却突然出现404错误。这个问题看似简单，却困扰着许多刚接触前后端分离部署的开发者。

实际上，这是单页应用（SPA）路由机制与Nginx处理逻辑冲突导致的典型问题。当我们在浏览器地址栏输入URL直接访问时，Nginx会正确返回index.html；而页面内跳转由前端路由处理。但刷新页面时，浏览器会向服务器请求当前URL对应的资源，Nginx就会去查找对应路径的文件——显然这个文件并不存在。

2. 核心原理深度解析

2.1 前端路由的工作机制

现代前端框架（如Vue Router、React Router）都采用两种路由模式：

• hash模式：URL带#符号（如example.com/#/about）
• history模式：URL无#（如example.com/about）

hash模式不会触发页面刷新，而history模式通过HTML5 History API实现无刷新跳转，但需要服务器配合——这正是我们遇到404问题的根源。

2.2 Nginx的请求处理流程

当Nginx收到请求时，其处理流程如下：

1. 匹配server块中的location规则
2. 查找对应路径的静态文件
3. 若找不到则返回404

对于前端history路由的URL（如/user/profile），Nginx会直接去/user/profile目录下查找文件，自然找不到任何资源。

3. 解决方案与配置实现

3.1 基础解决方案：try_files指令

最经典的解决方案是使用Nginx的try_files指令：

nginx复制location / {
    try_files $uri $uri/ /index.html;
}

这个配置的意思是：

1. 先尝试查找请求的URI对应文件（$uri）
2. 再尝试查找目录（$uri/）
3. 若都找不到则返回index.html

3.2 进阶配置方案

对于更复杂的场景，推荐以下配置：

nginx复制server {
    listen 80;
    server_name yourdomain.com;
    root /path/to/your/frontend;
    index index.html;

    location / {
        try_files $uri $uri/ @rewrites;
    }

    location @rewrites {
        rewrite ^.*$ /index.html last;
    }

    location ~* \.(js|css|png|jpg|