Nginx 常见问题排查
本章收集 Nginx 运维最高频的问题，按"症状 → 原因 → 检查 → 解决"的清单式步骤展开。绝大多数问题都能靠 nginx -t、error.log、ss/curl 三个工具定位。
1. 配置报错：nginx: [emerg] ...
改完配置 reload 报错时先跑 nginx -t 看具体行号（每次改动都应先 -t 通过再 reload，尽量别用 restart）：
sudo nginx -t
# 输出：nginx: [emerg] "server" directive is not allowed here in /etc/nginx/nginx.conf:3
# 常见原因：分号缺失、括号不配对、指令放错层级（如 server 写在了 http 块外）
2. 启动失败：bind() ... (98: Address already in use)
端口被其他进程或残留的旧 nginx 占用：
sudo ss -lntp | grep :80 # 看谁占着 80 端口
# 输出：LISTEN 0 511 0.0.0.0:80 users:(("nginx",pid=1234,fd=6))
sudo nginx -s stop # 若是残留 nginx，先停掉再启动
3. 权限错误：open() ... failed (13: Permission denied)
nginx worker 用户读不到文件，或目录缺执行权限；SELinux 开启时还会额外拦截：
ls -ld /var/www/site # 检查属主与权限（目录需 755 可进入）
sudo chown -R nginx:nginx /var/www/site # 或改用 chmod
getenforce # 输出 Enforcing 说明 SELinux 生效
# 反代连不上后端时放行网络：sudo setsebool -P httpd_can_network_connect 1
4. 502 Bad Gateway
Nginx 连不上后端，先确认后端进程与端口，再看 error.log 分类处理：
curl -s http://127.0.0.1:8080/ # 后端自己通不通
tail -n 20 /var/log/nginx/error.log
| error.log 关键字 | 原因 | 处理 |
|---|---|---|
| connect() failed | 后端未启动/防火墙拦截 | 启动后端或放行端口 |
| upstream timed out | 后端处理太慢 | 调大 proxy_read_timeout |
| worker_connections are not enough | 连接数不足 | 参考性能调优章调参 |
5. 413 Request Entity Too Large
上传大文件被 client_max_body_size（默认 1m）拦截，按业务调大：
http { client_max_body_size 20m; } # 上传类接口按需调大
6. 504 Gateway Time-out
后端在超时时间内没返回，按接口耗时调整三个超时（慢任务应让接口异步化，别无限调大超时）：
location / {
proxy_connect_timeout 10s; # 与后端建立连接
proxy_read_timeout 60s; # 等待后端响应
proxy_send_timeout 60s; # 向后端发送请求体
}
7. 404：root 与 alias 用错
root 把 location 的 URI 拼在路径后面，alias 则是整段替换：
location /img/ {
root /var/www/site; # 实际找 /var/www/site/img/1.png
}
location /img/ {
alias /var/www/pics/; # 实际找 /var/www/pics/1.png
}
始终 404 时先核对 root/alias 规则，再检查文件是否存在与目录权限（见问题 3）。
8. reload 后像没生效
reload 是平滑重载，但以下情况会表现成"没生效"：
- 配置有错被忽略：确认 nginx -t 真的通过、reload 没报错；
- 改错了文件：站点多时用 nginx -T 确认实际加载的路径与内容；
- DNS/浏览器缓存或旧 worker：用 curl -H "Host: 站点域名" http://127.0.0.1/ 直连排除缓存，ps 查看残留 worker，必要时再次 nginx -s reload。
9. worker 进程崩溃
error.log 出现 worker process ... exited on signal 11（core dumped）多为段错误：官方软件包极少崩溃，优先怀疑第三方模块与业务，必要时开 core dump（worker_core_dump_size 与系统 core_pattern）抓现场。
排查总流程
按顺序过一遍：① nginx -t 排除语法 → ② 翻 error.log 找关键字 → ③ 用 ss/curl 验证端口与后端 → ④ 对照配置核对 listen/server_name/location 匹配 → ⑤ reload 后复测。
小结
排错记住三句话：配置先 nginx -t、问题看 error.log、连通靠 ss + curl。把这 9 个高频场景记熟，日常绝大多数 Nginx 故障都能在十分钟内定位。