Nginx 命令速查表 - Nginx 配置与运维常用命令大全
面向要排查 502/504、改 location 路由、做反向代理的工程师。Nginx 的难点不在命令多，而在 location 匹配规则、proxy_pass 是否带尾部斜杠、upstream 超时参数这些细节——写错不报错，只在流量进来时表现为异常。读完能先 nginx -t 校验再 reload，能从 error log 的 upstream 报错反推后端问题，理解 502 Bad Gateway 与 504 Gateway Timeout 的定位差异。
典型使用场景
配置反向代理、负载均衡、静态资源服务与 TLS 终止；排查 502/504 网关错误、重定向循环、配置语法错误或权限被拒（13: Permission denied）。
命令与测试 5
nginx -tnginx -s reloadnginx -Tsystemctl restart nginxnginx -Vlocation 匹配优先级 5
location = /pathlocation ^~ /static/location ~ \.php$location ~* \.(jpg|png)$location /path反向代理片段 5
proxy_pass http://127.0.0.1:8080;proxy_set_header Host $host;proxy_set_header X-Real-IP $remote_addr;proxy_read_timeout 60s;client_max_body_size 50m;日志与排查 4
tail -f /var/log/nginx/error.logtail -f /var/log/nginx/access.loggrep " 502 " /var/log/nginx/access.logcurl -I http://localhost常见问题 FAQ 5
Q: 如何测试 Nginx 配置是否正确？Q: 如何配置 HTTPS？Q: 如何设置反向代理？Q: 如何限制访问 IP？Q: 如何配置负载均衡？高频补充命令（容量增强 · REQ-02） 34
nginx -tnginx -Tnginx -s reloadnginx -s stopnginx -s quitnginx -s reopennginx -c /path/nginx.confnginx -Vworker_processes auto;worker_connections 1024;listen 80;listen [::]:80;server_name example.com www.example.com;return 301 https://$host$request_uri;location = /exact {}location ^~ /static/ {}location ~ \.php$ {}try_files $uri $uri/ /index.php?$query_string;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_pass http://backend;upstream backend { server 10.0.0.1; server 10.0.0.2; }add_header X-Frame-Options SAMEORIGIN;ssl_certificate /path/fullchain.pem;ssl_certificate_key /path/privkey.pem;gzip on;gzip_types text/css application/json;client_max_body_size 20m;expires 30d;error_page 404 /404.html;access_log /var/log/nginx/access.log main;deny 192.168.1.1; allow all;rewrite ^/old$ /new permanent;进程控制与性能配置（REQ-02 补充） 22
nginx -g "daemon off;"nginx -p /usr/local/nginx -c conf/nginx.confkill -s QUIT $(cat /var/run/nginx.pid)ps -ax | grep nginxnginx -e /var/log/nginx/error.loginclude /etc/nginx/conf.d/*.conf;error_log /var/log/nginx/error.log warn;pid /var/run/nginx.pid;user nginx;sendfile on;tcp_nopush on;keepalive_timeout 65;server_tokens off;root /data/www;index index.html index.htm;location /images/ { root /data; }location ~ \.(gif|jpg|png)$ { root /data/images; }fastcgi_pass localhost:9000;fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;proxy_redirect off;proxy_connect_timeout 60s;stub_status;参数矩阵
| 参数 | 作用 | 示例 |
|---|---|---|
-t | 仅测试配置文件语法，不启动 | nginx -t |
-s reload | 平滑重载配置（不中断连接） | nginx -s reload |
-s stop | 快速停止 | nginx -s stop |
-c | 指定配置文件路径 | nginx -c /etc/nginx/nginx.conf |
-g | 启动时传入全局指令 | nginx -g 'daemon off;' |
worker_processes | 工作进程数，通常设为 auto | worker_processes auto; |
proxy_pass | 将请求转发到上游服务 | proxy_pass http://127.0.0.1:3000; |
upstream | 定义后端服务器池做负载均衡 | upstream app { server 10.0.0.1; } |
try_files | 按序尝试文件，最后回退 | try_files $uri $uri/ /index.html; |
return 301 | 返回重定向 | return 301 https://$host$request_uri; |
易错点与避坑指南
现象改完配置不生效或新旧配置混用。
原因改了文件却忘记 reload，或直接改了正在运行的 worker 内存。
处置每次改完先 nginx -t 校验语法，再 nginx -s reload 平滑生效；避免 kill 掉 worker 造成连接中断。
现象访问站点返回 502 Bad Gateway。
原因上游（proxy_pass 指向的后端）未启动、端口错或连接被防火墙拦截。
处置在 nginx 主机上 curl 直连上游验证可用性；检查 upstream 地址/端口与后端监听；看 error.log 的 connect() failed。
现象返回 504 Gateway Timeout。
原因上游响应超过 proxy_read_timeout（默认 60s）。
处置调大 proxy_read_timeout / proxy_send_timeout，或优化上游处理耗时；确认不是上游死锁。
现象静态文件返回 403 Forbidden，日志 13: Permission denied。
原因nginx 工作进程用户（如 www-data）无目录/文件读权限，或 SELinux 限制。
处置确认目录有 o+x、文件有 o+r；若启用 SELinux 用 setsebool -P httpd_read_user_content 1 放行。
现象HTTP 被强制跳转到 HTTPS 形成重定向循环。
原因SSL 终端在 CDN/负载均衡层已做 443 跳转，nginx 又再跳一次。
处置确认跳转只在一层发生；若 CDN 已终止 TLS，nginx 侧不要再 return 301 https。
现象配置测试报错 unknown directive。
原因使用了未编译进二进制的模块（如未装 stub_status、lua）。
处置nginx -V 看编译模块；缺失时换用带该模块的包或重新编译，不要在配置里引用不存在的指令。
排障路径
1先校验配置语法
nginx -t上线前必做，避免 reload 后整个服务起不来。
2平滑重载新配置
nginx -s reload不中断现有连接；若旧 worker 卡死可用 -s quit 优雅退出。
3实时跟踪错误日志定位网关错误
tail -f /var/log/nginx/error.log502/504/权限问题都会在 error.log 留下 connect()/permission 线索。
4从 nginx 主机直连上游验证可用性
curl -I http://127.0.0.1:3000/health排除是上游挂了还是 nginx 配置问题。
提示
- proxy_pass 结尾带不带斜杠语义完全不同：带 / 会替换 location 前缀，不带则原样拼接。
- 改完配置先 nginx -t 再 reload，语法错时 reload 不会生效但旧进程继续跑。
- 502 先看 error.log：connection refused 是后端没起，timeout 是后端太慢。
常见问题
nginx location 匹配顺序是怎么定的？
优先级从高到低：精确匹配 =、带 ^~ 的前缀匹配（命中后不再检查正则）、正则 ~/~*（按配置顺序，第一个命中生效）、普通前缀匹配（取最长前缀）。= 和 ^~ 会立即短路返回，正则则要等所有前缀匹配都试完后才参与。
返回 404 的时候怎么判断是 location 没匹配上还是后端真的 404？
看 error.log：请求根本没进后端时 log 里只有 access，或 proxy_pass 对应 server 未收到请求；若后端返回 404，log 会显示 request to 后端的 upstream 响应。也可以在配置里临时加 try_files 或直接 curl 后端端口做对照。
proxy_pass 带不带尾部斜杠有什么区别？
关键差别：proxy_pass 若带路径（如 http://upstream/api/），匹配 location 时 location 匹配到的剩余部分会拼接到该路径后；若不带路径（http://upstream 或 http://upstream/），则保留原始 URI 处理。带路径常用于把 /foo 重写到后端 /api/...。
502 Bad Gateway 和 504 Gateway Timeout 分别怎么排查？
502 是 Nginx 拿不到后端的有效响应：先确认后端进程是否存活、端口是否在听、防火墙和 proxy_pass 地址是否正确。504 是后端超时未在限期内返回，优先查后端处理耗时，再调 proxy_read_timeout/proxy_connect_timeout。两者都要结合 error.log 里的 upstream 段判断。
改了 nginx 配置用 restart 还是 reload？
优先 nginx -s reload 或 systemctl reload nginx：它平滑重载，不断开已有连接，且会先校验配置合法性。只有改动了 socket 监听、worker 数等无法热加载的参数，或 reload 一直报错时，才用 systemctl restart。改前先 nginx -t 校验。
由 巧匠 维护
公开更新于 2026年9月10日，内容持续校对官方文档。