NGINX（十四）404/502/504状态码常见错误排查

原创

于 2025-09-01 00:15:00 发布 · 3.7k 阅读

43 ·

CC 4.0 BY-SA版权

文章标签：

#nginx #运维 #404 #502 #504

在Nginx运维过程中，404（页面找不到）、502（网关错误）、504（网关超时）是最常遇到的三类状态码。对初学者而言，这些错误往往看似“无厘头”——配置明明没错，却始终无法访问。本文将从错误本质、常见场景、排查流程、解决方案四个维度，结合真实案例拆解问题，让你像“老运维”一样快速定位并解决问题。

一、先搞懂：HTTP状态码的核心含义

在排查前，我们需要先明确这三个状态码的本质，避免方向跑偏：

404 Not Found：客户端请求的资源（文件/接口）不存在，问题通常在“路径匹配”或“资源存在性”；
502 Bad Gateway：Nginx作为网关，无法从后端服务（如PHP-FPM、Tomcat、API服务）获取正常响应（可能是后端挂了、连接不上）；
504 Gateway Timeout：Nginx请求后端服务时，后端处理时间过长，超过了Nginx的超时限制，导致请求被中断。

简单总结：404是“找不着资源”，502是“后端挂了/连不上”，504是“后端太慢了”。

二、404 Not Found：从“路径”和“配置”找问题

404错误的核心是“请求的资源不存在”，但“不存在”的原因可能是路径写错、配置匹配错误、权限不足等。以下是3个真实案例及解决方案。

案例1：静态文件404——路径配置错误（最常见）

现象

在Nginx根目录/usr/share/nginx/html下创建了test.html，访问http://192.168.1.100/test.html时返回404，日志显示：

192.168.1.101 - - [20/Oct/2024:15:30:00 +0800] "GET /test.html HTTP/1.1" 404 153 "-" "Chrome/118.0.0.0"

排查步骤

确认资源是否存在：
先检查文件是否真的在配置的路径下：

# 查看Nginx配置的根目录（从nginx.conf或虚拟主机配置中找root指令）
grep "root" /etc/nginx/conf.d/default.conf
# 输出：root /usr/share/nginx/html;

# 检查文件是否存在
ls /usr/share/nginx/html/test.html  # 若输出无此文件，说明文件没放对位置

确认路径拼写是否正确：
- 大小写问题：Linux区分大小写，Test.html和test.html是两个文件；
- 路径层级：若文件在/usr/share/nginx/html/static/test.html，则访问路径应为http://IP/static/test.html，而非/test.html。

解决方案

若文件放错位置：将test.html移动到配置的root目录下：
```
mv /home/user/test.html /usr/share/nginx/html/
```
若路径层级错误：按实际路径访问，或修改root配置（不推荐，建议规范文件存放）。

案例2：location规则不匹配——配置优先级问题

现象

配置了一个虚拟主机，想让/api路径转发到后端服务，/路径返回静态页面，但访问http://IP/api/user时返回404，配置如下：

server {
    listen 80;
    server_name my-site.local;
    root /usr/share/nginx/html;
    index index.html;

    # 错误的location顺序
    location / {
        try_files $uri $uri/ /index.html;  # 静态页面匹配
    }

    location /api {
        proxy_pass http://127.0.0.1:8080;  # 后端API转发
    }
}

排查步骤

理解location匹配优先级：
Nginx的location匹配遵循“精确匹配（=）> 前缀匹配（^~）> 正则匹配（~）> 普通前缀匹配”，且普通前缀匹配会按“最长匹配”原则，但如果先配置了location /（匹配所有路径），后续的location /api会被忽略——因为/api也属于/的匹配范围，Nginx会优先匹配先定义的location /。
查看Nginx配置解析结果：
用nginx -T查看完整配置，并确认location的匹配顺序：
```
nginx -T | grep -A 10 "location"  # 
```