一、基础知识
反向代理指的是 Nginx 站在前面替客户端去访问后端服务,客户端只和 Nginx 打交道,看不到真实后端。它和「正向代理」方向相反:正向代理替客户端出去访问外部资源,反向代理替服务器接住外部请求。它常用来做端口转发、负载均衡、隐藏后端地址、统一加 HTTPS,还能在代理层统一处理超时、缓存和请求头。理解这一点很重要——请求先到 Nginx,再由 Nginx 决定交给谁,所以排查时要养成「先看 Nginx 把请求转给了谁,再看后端怎么回应」的习惯,而不是笼统地说「网站挂了」。
配置的核心是 server 块里的 location,它决定「不同的 URL 交给谁处理」。location 的匹配规则必须记牢,否则 404 会查到怀疑人生。按优先级从高到低:
- 精确匹配
=:location = /api只匹配/api本身,命中后立即停止。 - 前缀匹配
^~:匹配普通前缀,一旦命中就不再检查正则。 - 正则匹配
~/~*:~区分大小写,~*不区分。按配置文件里出现的先后顺序,第一个命中的生效。 - 普通前缀匹配:不带符号的最长前缀匹配。
- 通用匹配
/:以上都不命中时的兜底。
这里有个反直觉的点:普通前缀只是「暂时记下最长的那个」,正则有机会推翻它;只有 ^~ 或 = 才能挡住正则。
另一个高频陷阱是 proxy_pass 结尾的斜杠,它决定转发时是否替换路径:
location /api/ { proxy_pass http://192.0.2.10:8080/; }:带斜杠,会把/api/这一段替换掉,/api/user变成/user发给后端。location /api/ { proxy_pass http://192.0.2.10:8080; }:不带斜杠,路径原样转发,/api/user仍是/api/user。
最后是 root 与 alias:root 把完整 URI 拼到指定目录后,而 alias 用 location 后面的那段路径替换掉。两者用混,静态文件必 404。
二、实操步骤
下面配置片段直接用 example.com 与文档地址 192.0.2.10,可复制到测试环境。
第 1 步:先确认语法并找到生效的配置。
nginx -t
nginx -T 2>/dev/null | grep -nE 'server_name|location|proxy_pass|root|alias'
nginx -T 会把所有 include 展开后打印完整配置,最适合排查「改了文件却没生效」。
第 2 步:写一个带调试标记的示例 server 块。
cat > /etc/nginx/conf.d/example.conf <<'EOF'
server {
listen 80;
server_name example.com;
location = /health {
add_header X-Match "exact";
return 200 "okn";
}
location ^~ /api/ {
add_header X-Match "api-prefix";
proxy_pass http://192.0.2.10:8080/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
location / {
add_header X-Match "default";
root /var/www/html;
try_files $uri $uri/ /index.html;
}
}
EOF
nginx -t && nginx -s reload
add_header X-Match 是调试利器:看响应头就知道命中了哪个 location。
第 3 步:用 curl 验证命中结果。
curl -sSI http://example.com/health | grep -i x-match
curl -sSI http://example.com/api/user | grep -i x-match
curl -sSI http://example.com/ | grep -i x-match
分别应看到 exact、api-prefix、default。
第 4 步:验证斜杠导致的路径差异。
# 带斜杠:/api/user 转发为 /user
curl -sS http://example.com/api/user
# 若改为不带斜杠,路径 /api/user 会原样到达后端,可在后端打印请求路径确认
第 5 步:验证 root 与 alias 的区别。
# root:/static/a.css 对应文件 /var/www/html/static/a.css
location /static/ { root /var/www/html; }
# alias:/static/a.css 对应文件 /data/assets/a.css
location /static/ { alias /data/assets/; }
用 curl -I 看返回码,配合 error.log 里「No such file or directory」的实际路径,能直接看出拼出来错在哪。
第 6 步:看日志确认 404 是谁返回的。
tail -n 50 /var/log/nginx/access.log
tail -n 50 /var/log/nginx/error.log
access.log 里若带上游状态码,说明 404 是后端返回的;error.log 里若有 connect() failed,说明根本没连上后端。
三、关键细节
-
正则按出现顺序命中:把更具体的正则写在前面,宽泛的写在后面,否则被前一个正则抢先匹配。
-
^~的真正作用是「阻止正则」:当某个前缀目录不希望被后面的正则覆盖时,给它加上^~。 -
proxy_pass的斜杠决定路径替换:这是 404 的头号元凶。改代理地址时,务必连同斜杠一起核对,并到后端打印一次真实收到的路径。 -
Host 头默认会被改写:不写
proxy_set_header Host $host;时,后端收到的是代理地址而非原域名。很多应用据此生成绝对链接,结果页面资源全部指向错误域名而 404。 -
SPA 前端必须配
try_files:try_files $uri $uri/ /index.html;能把不存在的路径回退到入口文件,否则刷新子路由必 404。 -
404 可能是后端给的:判断归属看日志与响应头,别一上来就改 Nginx 路径。
-
改后端地址时斜杠要一起检查:从
http://192.0.2.10:8080改成http://192.0.2.11:8080/这种看似无害的改动,会悄悄改变路径替换行为,务必复测一次真实请求路径。
四、常见错误
1. 访问 /api/xxx 返回 404,后端接口却明明存在
- 现象:直连后端接口正常,经 Nginx 就 404。
- 原因:proxy_pass 斜杠导致路径前缀被多删或少留。
- 修正:对照第 4 步,用后端打印请求路径,决定带不带斜杠。
2. 静态资源全部 404
- 现象:页面能开,CSS/JS 全挂。
- 原因:root 与 alias 混用,或路径写成相对路径导致拼错目录。
- 修正:用 alias 时用绝对路径且结尾带斜杠,查 error.log 里的实际文件路径。
3. 页面里的链接指向奇怪域名,资源 404
- 现象:HTML 里资源 URL 变成后端 IP。
- 原因:没设置 Host 头,应用按请求 Host 生成链接。
- 修正:补上 proxy_set_header Host $host; 并在必要时设置 X-Forwarded-Proto。
4. 本想匹配 /api,却落到默认 location
- 现象:接口请求返回了前端页面。
- 原因:某个正则抢先命中,覆盖了你以为会生效的前缀匹配。
- 修正:用 X-Match 标记确认命中项,给前缀加 ^~ 或调整正则顺序。
5. 改了配置没生效
- 现象:反复修改无变化。
- 原因:没有 reload,或存在多个 include 文件互相覆盖,测试的不是同一份配置。
- 修正:nginx -t && nginx -s reload,再用 nginx -T 看最终生效配置。
6. 前端刷新子路由 404
- 现象:首页正常,刷新 /user/profile 就 404。
- 原因:缺少 try_files 回退到 index.html。
- 修正:在前端 location 中加 try_files $uri $uri/ /index.html;。
五、排查方法
照这个顺序做:
# 1. 确认语法与最终生效配置
nginx -t
nginx -T 2>/dev/null | grep -nE 'server_name|location|proxy_pass|root|alias|try_files'
# 2. 加 X-Match 调试头,先看命中了哪个 location
curl -sSI http://example.com/api/user | grep -i x-match
# 3. 看状态码与响应头,判断是谁返回的 404
curl -sSI http://example.com/api/user
# 4. 看访问日志与错误日志
tail -n 50 /var/log/nginx/access.log
tail -n 50 /var/log/nginx/error.log | grep -iE 'no such file|connect|upstream'
# 5. 绕过代理直连后端,隔离问题
curl -sS -i http://192.0.2.10:8080/user
# 6. 重载并复测
nginx -t && nginx -s reload
判断逻辑:命中错 location → 查优先级与正则顺序;命中对但 404 → 查 proxy_pass 斜杠与 Host 头;静态文件 404 → 查 root/alias 拼接;刷新子路由 404 → 查 try_files。
六、注意事项
- 示例仅作演示:文中 IP 为文档地址、域名为示例域名,实际请替换为你的后端与域名。
- 参数以官方文档为准:
proxy_set_header、try_files等指令的细节和默认值随版本变化,修改前先看当前生效配置。 - reload 不是万能:
nginx -s reload会平滑重启工作进程,旧连接仍可能按旧配置完成,验证时用新连接测试。 - 注意 include 覆盖:多份配置文件并存时,加载顺序决定最终行为,
nginx -T是唯一可信的全貌。 - 安全提示:不要让
proxy_pass指向可控的用户输入,避免被利用成开放代理或 SSRF 入口;对外暴露的 location 应做必要的访问限制。
免责声明:本文为个人学习与实操经验总结,仅代表个人观点,不构成任何技术或商业决策建议。不同系统环境与版本可能存在差异,实际操作请以官方文档为准并自行验证。

评论
还没有评论,来说两句吧。