Nginx 常见错误排查指南

Nginx 报错不要只看浏览器页面。真正有价值的信息通常在 error.log、access.log、后端服务状态和站点配置里。排查顺序应该是：先确认 Nginx 自身正常，再确认请求是否到达，最后确认后端、权限、路径和 HTTPS/CDN 配置。

🧪 先做 5 个基础检查

无论是 502、403 还是 404，都先跑下面这组命令。它能快速判断是 Nginx 没启动、配置语法错、端口没监听，还是请求已经到达但被规则处理错。

  # 检查 Nginx 状态
sudo systemctl status nginx

# 检查配置语法
sudo nginx -t

# 查看监听端口
sudo ss -lntp | grep nginx

# 本机请求测试
curl -I http://127.0.0.1
curl -I http://你的域名

# 最近错误日志
sudo tail -n 100 /var/log/nginx/error.log

📜 看日志：access.log 和 error.log

access.log 说明请求有没有进来、返回了什么状态码；error.log 说明 Nginx 内部为什么失败。两者要一起看。

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

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

# 找 502 请求
sudo awk '$9 == 502 {print}' /var/log/nginx/access.log | tail -n 20

# 找访问最多的 IP
sudo awk '{print $1}' /var/log/nginx/access.log | sort | uniq -c | sort -nr | head

# 按状态码统计
sudo awk '{print $9}' /var/log/nginx/access.log | sort | uniq -c | sort -nr

🚧 502 Bad Gateway：后端不可用

502 的本质是 Nginx 作为网关收到了请求，但它连不上后端，或后端返回异常。常见于 PHP-FPM、Node.js、Python、Docker 服务没启动。

  # 查看后端服务是否运行
sudo systemctl status php8.2-fpm
sudo systemctl status php-fpm
sudo systemctl status node-app

# 检查后端端口是否监听
sudo ss -lntp | grep -E ':(3000|8000|9000)\\b'

# 直接请求后端
curl -I http://127.0.0.1:3000
curl -I http://127.0.0.1:8000

• connect() failed: 端口或 Unix Socket 不存在，检查后端监听地址。
• upstream timed out: 后端响应太慢，检查应用日志、数据库和资源占用。
• permission denied: Nginx 用户无权访问 Socket，检查 Socket 权限和用户组。

🚫 403 Forbidden：权限或目录规则错误

403 通常不是“文件不存在”，而是 Nginx 找到了资源但不允许访问。重点查目录权限、站点 root、是否缺少 index 文件、是否有 deny 规则。

  # 查看站点目录权限
ls -ld /var/www /var/www/example.com
ls -la /var/www/example.com

# 确认 Nginx 运行用户
ps aux | grep nginx

# 常见修复示例，按实际目录调整
sudo chown -R www-data:www-data /var/www/example.com
sudo find /var/www/example.com -type d -exec chmod 755 {} \\;
sudo find /var/www/example.com -type f -exec chmod 644 {} \\;

🧩 404 Not Found：路径、root 或 try_files 错误

404 要先确认请求进了哪个 server block。多个站点共用一台 VPS 时，域名没匹配到正确配置，经常会落到默认站点。

• 检查 server_name 是否包含当前域名。
• 检查 root 是否指向真正的构建目录。
• 前端 SPA 需要 try_files $uri $uri/ /index.html。
• alias 和 root 语义不同，路径拼接很容易错。

🔁 重定向循环：HTTP/HTTPS 和 CDN 配置冲突

如果浏览器提示重定向次数过多，常见原因是 Nginx 强制 HTTPS，而 CDN 回源仍使用 HTTP；或者应用层也在重复强制跳转。

  # 查看重定向链
curl -I http://你的域名
curl -I https://你的域名
curl -L -I http://你的域名

# 如果使用 Cloudflare，优先确认 SSL/TLS 模式
# Flexible 容易和源站强制 HTTPS 形成循环，通常建议 Full 或 Full strict。

🔀 反向代理失败：端口、Host 和 WebSocket

反代服务要同时确认后端端口、请求头和协议升级。面板、实时应用、WebSocket 服务尤其容易漏掉 upgrade 头。

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

# WebSocket 额外需要
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

🛟 安全修改和回滚流程

生产站点不要直接改完就重启。先备份，语法检查通过后用 reload。reload 失败通常不会杀掉旧进程，比 restart 更稳。

  # 修改前备份站点配置
sudo cp /etc/nginx/sites-available/example.com /etc/nginx/sites-available/example.com.bak

# 检查语法，确认无误再 reload
sudo nginx -t
sudo systemctl reload nginx

# 如果 reload 后异常，回滚配置
sudo cp /etc/nginx/sites-available/example.com.bak /etc/nginx/sites-available/example.com
sudo nginx -t
sudo systemctl reload nginx

❓ 常见问题解答