Nginx 常见报错速查

502 Bad Gateway

出现场景：访问反向代理的站点时

原因：Nginx 无法连接到后端服务（服务未启动、端口错误、超时）

解决方案：

1. 检查后端服务是否运行：systemctl status app 或 curl localhost:3000
2. 确认 proxy_pass 地址和端口正确
3. 检查后端服务日志查看是否有错误
4. 如果是 PHP-FPM：检查 socket 文件是否存在和权限
5. 增加 proxy_connect_timeout 和 proxy_read_timeout

预防：配置健康检查，使用 systemd 确保后端服务自动重启

403 Forbidden

出现场景：访问静态文件或目录时

原因：Nginx 进程没有读取文件/目录的权限

解决方案：

1. 检查文件权限：ls -la /var/www/html/
2. 确保 Nginx 用户（通常是 www-data 或 nginx）有读取权限
3. 修复权限：chmod 644 files, chmod 755 directories
4. 修改所有者：chown -R www-data:www-data /var/www/html/
5. 检查 SELinux：getenforce，如果是 Enforcing 可能需要设置上下文

预防：部署时统一设置文件权限，用部署脚本自动处理

nginx: [emerg] unknown directive / unexpected "}"

出现场景：nginx -t 测试配置或 nginx -s reload 时

原因：配置文件语法错误（拼写、缺少分号、括号不匹配）

解决方案：

1. 仔细检查报错行号附近的配置
2. 确认每条指令末尾有分号
3. 确认花括号 {} 配对正确
4. 检查 include 的文件是否存在
5. 用 nginx -T 查看完整合并后的配置

预防：修改配置后立即 nginx -t 测试，使用编辑器的 Nginx 语法高亮

nginx: [emerg] bind() to 0.0.0.0:80 failed (98: Address already in use)

出现场景：启动 Nginx 时

原因：80 端口已被其他进程（Apache、另一个 Nginx 实例）占用

解决方案：

1. 查找占用进程：sudo lsof -i :80 或 sudo ss -tlnp | grep :80
2. 停止占用的服务：sudo systemctl stop apache2
3. 如果是旧的 Nginx 进程：sudo killall nginx
4. 或者改用其他端口：listen 8080;

预防：服务器上只运行一个 Web 服务器，卸载不需要的 Apache

504 Gateway Timeout / upstream timed out

出现场景：请求需要较长处理时间的 API 时

原因：后端处理时间超过 Nginx 的 proxy_read_timeout（默认 60s）

解决方案：

1. 增加超时时间：proxy_read_timeout 300s;
2. 同时增加：proxy_connect_timeout 60s; proxy_send_timeout 300s;
3. 优化后端接口响应速度
4. 对于长时间任务改用异步处理（返回任务 ID，轮询结果）

预防：后端 API 应该在合理时间内响应，长任务用异步队列处理