如何解决前端History模式下页面刷新404故障教程-Nginx-PHP中文网

本质是服务器找不到对应路径的文件，因history模式下/user/profile为前端路由而非真实资源；解决关键是配置服务器对所有非资源请求兜底返回index.html，由前端js再次解析路由。

如何解决前端history模式下页面刷新404故障教程

刷新就 404，本质是服务器找不到对应路径的文件——因为 History 模式下的 /user/profile 是前端路由，不是真实存在的后端接口或静态资源。解决的关键，是让服务器对所有非资源请求“兜底”返回 index.html，交由前端 JS 再次解析路由。

确认前端已启用 History 模式

这是前提，否则后续配置无效：

Vue Router 3：检查 mode: 'history'；Vue Router 4+（Vue 3）：确认使用 createWebHistory()
React Router v6：createBrowserRouter 默认即为 History 模式，无需额外设置
构建产物中必须存在 index.html，且 JS/CSS 资源引用路径正确（如 /assets/index.xxxx.js，不是相对路径 ./assets/...）

Nginx 配置核心：try_files 兜底规则

在站点 server 块的 location / 区域添加这一行：

nginx-0.5.38

Nginx是一款高性能的开源软件，由俄罗斯开发者Igor Sysoev于2004年创建。它最初设计为高效的HTTP Web服务器，现已成为最受欢迎的Web服务器之一。Nginx以事件驱动、非阻塞I/O架构著称，能以极低内存占用处理数万并发连接，特别适合高流量场景。它同时担任反向代理、负载均衡器、HTTP缓存、TCP/UDP代理等多重角色，常用于静态文件服务、SSL终止、请求转发、API网关和微服务

下载

try_files $uri $uri/ /index.html;

$uri：优先匹配真实文件（.js、.css、图片等），命中则直接返回
$uri/：再尝试匹配目录（如请求 /api/ 时避免误 fallback）
/index.html：以上都不匹配时，统一返回根目录下的 index.html（注意开头斜杠，表示绝对路径）
确保 root 指向你实际的构建输出目录（如 /www/wwwroot/myapp/dist）

API 接口需单独配置，避免被兜底干扰

如果你的前端也调用后端 API（如 /api/login），必须在 location / 之前，用独立的 location ^~ /api/ 块做反向代理：

写法示例：location ^~ /api/ { proxy_pass http://127.0.0.1:8080/; }
^~ 表示前缀匹配且优先级高于正则，防止被后面的 location / 的 try_files 拦截
不要把 API 和前端混在同一个 location 下，否则 /api/xxx 会被当成不存在的文件而 fallback 到 index.html

验证与上线前必做三步

运行 nginx -t：语法检查，提示 success 才算通过
执行 nginx -s reload：平滑重载配置，不中断服务
手动测试三种典型场景：
✅ 输入 / 并刷新 → 应正常显示首页
✅ 输入 /user/profile 并刷新 → 应加载前端路由页，而非 404
✅ 输入 /api/user（或任意真实 API）→ 应返回后端数据，而非 HTML

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索前端的入门与实战技巧！