Nginx 404 Not Found错误排查与解决

Nginx 作为高性能 Web 服务器和反向代理服务器，被广泛应用于网站部署、接口服务以及负载均衡场景。在实际使用过程中，404 Not Found 是最常见的问题之一。很多开发者在访问网站、调用接口或部署项目时，会遇到浏览器返回 “404 Not Found” 页面，但服务器并没有明显报错。

Nginx 返回 404 并不一定代表服务完全不可用，它通常意味着请求已经到达 Nginx，但 Nginx 没有找到对应的资源或无法将请求转发到正确的位置。造成这一问题的原因很多，包括配置错误、文件路径异常、location 匹配问题、反向代理配置错误以及权限设置等。

本文将系统分析 Nginx 404 Not Found 错误的常见原因，并提供详细排查方法和解决方案。

一、理解 Nginx 404 Not Found错误产生机制

当用户访问一个 URL 时，请求会经过以下流程：

1. 客户端发送 HTTP 请求；

2. Nginx 接收请求；

3. 根据 server 配置匹配对应站点；

4. 根据 location 规则匹配请求路径；

5. 查找静态文件或者转发请求到后端服务；

6. 返回响应结果。

如果在其中某一步无法找到对应资源，Nginx 就可能返回 404。

例如：

访问：

https://example.com/index.html

Nginx 根据配置：

server {
    listen 80;
    server_name example.com;

    root /usr/share/nginx/html;
}

会尝试查找：

/usr/share/nginx/html/index.html

如果文件不存在，就会返回：

404 Not Found

因此，解决 Nginx 404 问题的关键是确认：

• 请求是否进入正确的 server；

• location 是否匹配正确；

• 文件路径是否存在；

• 后端服务是否正常响应。

二、检查 Nginx 配置文件是否正确

Nginx 配置错误是导致 404 的主要原因之一。

首先检查当前生效配置：

nginx -t

正常情况下会显示：

syntax is ok
test is successful

如果配置存在问题，需要先修复配置错误。

查看完整配置：

nginx -T

通过该命令可以确认 Nginx 当前加载的是哪个配置文件，以及实际生效的 server 和 location。

常见错误包括：

1. root路径配置错误

例如：

server {
    listen 80;
    server_name test.com;

    root /var/www/html/project;
}

但实际项目文件位于：

/var/www/project

访问：

http://test.com/index.html

Nginx 会查找：

/var/www/html/project/index.html

自然返回404。

解决方法：

修改 root：

root /var/www/project;

然后重新加载：

nginx -s reload

2. index配置缺失

如果访问：

http://example.com/

Nginx 会根据 index 指令寻找默认首页。

例如：

index index.html index.htm;

如果目录中不存在这些文件，也可能出现404。

检查目录：

ls -al /usr/share/nginx/html

确认首页文件是否存在。

三、排查location匹配问题

Nginx 的 location 匹配规则非常容易导致404。

例如：

location /app/ {
    root /data/www;
}

访问：

http://example.com/app/index.html

Nginx 实际查找：

/data/www/app/index.html

如果真实目录结构是：

/data/www/index.html

就会失败。

这种情况下应该使用：

location /app/ {
    alias /data/www/;
}

区别：

root：

请求路径会拼接到root后面

alias：

直接替换location匹配路径

在静态资源映射场景中，alias 更容易符合预期。

四、检查反向代理配置导致的404

很多项目使用 Nginx 作为反向代理，例如：

用户
 |
Nginx
 |
Spring Boot / Node.js / Python服务

配置：

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

如果访问：

/api/user

但后端实际接口是：

/user

可能导致后端返回404。

需要注意 proxy_pass 尾部 / 的区别。

例如：

配置：

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

请求：

/api/user

转发：

http://127.0.0.1:8080/user

而：

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

请求：

/api/user

转发：

http://127.0.0.1:8080/api/user

路径变化可能导致后端接口不存在，从而返回404。

五、查看Nginx访问日志和错误日志

日志是排查404最快的方法。

默认访问日志：

/var/log/nginx/access.log

错误日志：

/var/log/nginx/error.log

查看最近请求：

tail -f /var/log/nginx/access.log

可能看到：

GET /test.html HTTP/1.1
404

错误日志：

tail -f /var/log/nginx/error.log

例如：

open() "/usr/share/nginx/html/test.html" failed

说明 Nginx 正在寻找文件：

/usr/share/nginx/html/test.html

但文件不存在。

根据日志中的真实路径检查即可快速定位问题。

六、检查静态文件是否存在

如果 Nginx 用于部署 Vue、React 等前端项目，404问题非常常见。

例如：

server {
    listen 80;

    root /opt/web/dist;
}

检查：

ls /opt/web/dist

确认是否包含：

index.html
assets/
js/
css/

如果目录为空或者部署路径错误，需要重新上传前端文件。

七、解决Vue、React单页面应用刷新404问题

SPA应用使用前端路由时，经常出现：

首页正常：

example.com

但是刷新：

example.com/user/profile

出现404。

原因：

Nginx 默认认为：

/user/profile

对应一个真实文件。

但实际上这是前端路由。

解决方式：

增加：

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

含义：

1. 如果文件存在，直接返回；

2. 如果目录存在，访问目录；

3. 否则返回 index.html。

然后由前端路由处理页面。

八、检查server_name匹配错误

多个站点共用一个 Nginx 时，server_name 配置错误也会导致404。

例如：

server {
    listen 80;
    server_name aaa.com;