Nginx 刷新后 404 的原因与解决方案

---

Nginx 刷新后 404 的原因与解决方案

最近，我负责上线一个新的前端平台，部署在 Nginx 上。最初访问时一切正常，但当我 刷新页面 时，却突然出现了 404 Not Found。这让我意识到，可能是 Nginx 的静态资源路径 出了问题。于是，我深入排查了这个 404 问题，并整理成这篇博文，希望能帮助遇到类似情况的朋友。

静态资源路径问题（单页应用 SPA）

如果 Nginx 用于托管 Vue、React、Angular 等前端单页面应用（SPA），刷新后 404 可能是因为 Nginx 直接查找 URL 对应的物理路径，而前端路由交由 JavaScript 处理。

解决方案：使用 try_files

修改 nginx.conf，确保 location / 配置如下：

location / {
    root /var/www/html;
    index index.html;
    try_files $uri /index.html;
}

解释：

• try_files $uri /index.html;：如果找不到请求的文件，则返回 index.html，前端路由框架再解析路径。
• 适用于 Vue Router、React Router 这类 前端路由模式为 history 的情况。

---

Nginx 资源路径 (root 或 alias) 配置错误

如果 root 或 alias 路径错误，Nginx 找不到资源文件，导致刷新时返回 404。

示例：正确的 root配置

server {
    listen 80;
    server_name example.com;

    root /var/www/html;
    index index.html;
    
    location / {
        try_files $uri $uri/ /index.html;
    }
}

错误示例（容易导致 404）：

location / {
    alias /var/www/html/;
    index index.html;
}

alias 不能直接用于目录，应使用 root。

---

浏览器缓存或 Nginx 缓存影响

如果修改了 Nginx 配置，但仍然 404，可能是缓存问题。

清除浏览器缓存

按 Ctrl + Shift + R 或在开发者工具（F12）中 禁用缓存 后尝试刷新。

给静态资源加版本号

在 index.html 中修改引用的 JS/CSS：

<script src="/js/app.js?v=1.0.1"></script>

这样可避免缓存问题。

Nginx 关闭缓存

如果静态资源仍然被缓存，可在 nginx.conf 添加：

location / {
    add_header Cache-Control "no-cache, no-store, must-revalidate";
}

然后重启 Nginx：

systemctl restart nginx

---

反向代理 (proxy_pass) 配置错误

如果 Nginx 代理了后端 API（如 Node.js、Python Flask），刷新后 404 可能是因为请求路径未正确转发。

示例：正确的反向代理

location /api/ {
    proxy_pass http://backend_server:8080/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

检查点：

• 确保 backend_server:8080 服务可用。
• proxy_pass 后必须带 /，否则会拼接路径导致 404。

错误示例（容易导致 404）：

location /api {
    proxy_pass http://backend_server:8080;
}

这里 /api 缺少 /，会导致 http://backend_server:8080api/... 这样的错误路径。

---

Nginx 日志分析

如果以上方法仍未解决问题，可以查看 Nginx 访问日志 和 错误日志 进行分析：

# 查看访问日志
tail -f /var/log/nginx/access.log

# 查看错误日志
tail -f /var/log/nginx/error.log

如果错误日志中出现类似：

[error] 404 No such file or directory

说明请求的资源路径错误，可能需要检查 root 或 try_files 配置。

---

Nginx 配置变更后未重启

如果修改了 nginx.conf 但未生效，可能是 Nginx 未重新加载配置。

解决方案

nginx -t   # 先测试配置是否正确
systemctl restart nginx  # 重启 Nginx

---

总结

问题	解决方案
前端 SPA 应用（Vue/React）刷新 404	try_files $uri /index.html;
Nginx root 或 alias 路径错误	确保 root 指向正确的静态文件目录
浏览器缓存问题	清除缓存、添加版本号、禁用 Nginx 缓存
反向代理 proxy_pass 404	确保 proxy_pass 语法正确，后端服务可用
Nginx 配置修改未生效	nginx -t 检查语法，systemctl restart nginx 重启

按照本文方法排查，相信可以快速找到 Nginx 刷新后 404 的真正原因，并顺利解决问题！