Nginx + Vue History 模式刷新 404 的完整排查与解决方案

一、问题背景

在部署前后端分离项目时，常见架构如下：

前端：Vue 3（使用 createWebHistory，History 模式路由）
后端：Spring Boot
网关：Nginx

部署完成后，发现一个非常诡异的问题：

👉 页面内部跳转一切正常，但只要在浏览器地址栏刷新，就直接 404。

例如访问：http://ip:port/finance-record

首次从首页点击跳转 → 正常显示
浏览器刷新 → 404 Not Found

二、问题复现

现象：

操作	结果
`/finance-record` 页面内跳转	正常
直接访问 `/finance-record`	404
刷新 `/finance-record`	404

三、问题根因分析

1️⃣ Vue History 模式的本质

History 模式下：

/finance-record 只是前端路由
服务器实际上并不存在 /finance-record 这个文件

👉 所以：服务器必须把所有非静态资源请求回退到 index.html，交给前端路由处理。

2️⃣ 刷新时发生了什么？

浏览器刷新 /finance-record 时：

请求直接发送给 Nginx
Nginx 尝试寻找文件：/path/frontend/dist/finance-record
文件不存在 → 返回 404

3️⃣ 原因总结

服务器未对根路径 / 设置 SPA fallback
仅对某个子路径配置了 try_files
实际访问路径并未命中 fallback 规则

四、最终解决方案

👉 给根路径 / 增加统一的 SPA 回退规则。

五、正确的 Nginx 配置

XML 复制代码

server {
    #你的端口
    listen  port;
    #你的ip或域名
    server_name ip;

    # API 反向代理
    location ^~ /api/ {
        proxy_pass http://127.0.0.1:backend_port;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 前端 SPA
    root /path/to/your/frontend/dist;
    index index.html;

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

    # 禁止访问隐藏文件
    location ~ /\.(git|env|htaccess) {
        deny all;
    }
}

原配置：

调整后的配置：

六、配置说明

配置	作用
`try_files $uri $uri/ /index.html`	所有非静态文件请求回退给前端
`root` + `index`	指定前端构建输出目录
`/api/` 代理

七、验证方式

1️⃣ 刷新 /finance-record → 不再 404

2️⃣ 访问 /assets/app.js → 正常返回

3️⃣ 调用 /api/calc → 正常代理

八、总结

Vue History 模式刷新 404 的根因不是 Vue，也不是浏览器，而是服务器不知道如何处理前端路由。

只要在 Nginx 层对根路径统一 fallback 到 index.html，问题即可彻底解决。

也可以这么说：

刷新 404 = 服务器找不到前端路由 → 用 try_files 回退给 index.html 即可