一、基础知识

反向代理指的是 Nginx 站在前面替客户端去访问后端服务,客户端只和 Nginx 打交道,看不到真实后端。它和「正向代理」方向相反:正向代理替客户端出去访问外部资源,反向代理替服务器接住外部请求。它常用来做端口转发、负载均衡、隐藏后端地址、统一加 HTTPS,还能在代理层统一处理超时、缓存和请求头。理解这一点很重要——请求先到 Nginx,再由 Nginx 决定交给谁,所以排查时要养成「先看 Nginx 把请求转给了谁,再看后端怎么回应」的习惯,而不是笼统地说「网站挂了」。

配置的核心是 server 块里的 location,它决定「不同的 URL 交给谁处理」。location 的匹配规则必须记牢,否则 404 会查到怀疑人生。按优先级从高到低:

  1. 精确匹配 =:location = /api 只匹配 /api 本身,命中后立即停止。
  2. 前缀匹配 ^~:匹配普通前缀,一旦命中就不再检查正则。
  3. 正则匹配 ~ / ~*:~ 区分大小写,~* 不区分。按配置文件里出现的先后顺序,第一个命中的生效。
  4. 普通前缀匹配:不带符号的最长前缀匹配。
  5. 通用匹配 /:以上都不命中时的兜底。

这里有个反直觉的点:普通前缀只是「暂时记下最长的那个」,正则有机会推翻它;只有 ^~ 或 = 才能挡住正则。

另一个高频陷阱是 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,说明根本没连上后端。

三、关键细节

  1. 正则按出现顺序命中:把更具体的正则写在前面,宽泛的写在后面,否则被前一个正则抢先匹配。

  2. ^~ 的真正作用是「阻止正则」:当某个前缀目录不希望被后面的正则覆盖时,给它加上 ^~。

  3. proxy_pass 的斜杠决定路径替换:这是 404 的头号元凶。改代理地址时,务必连同斜杠一起核对,并到后端打印一次真实收到的路径。

  4. Host 头默认会被改写:不写 proxy_set_header Host $host; 时,后端收到的是代理地址而非原域名。很多应用据此生成绝对链接,结果页面资源全部指向错误域名而 404。

  5. SPA 前端必须配 try_files:try_files $uri $uri/ /index.html; 能把不存在的路径回退到入口文件,否则刷新子路由必 404。

  6. 404 可能是后端给的:判断归属看日志与响应头,别一上来就改 Nginx 路径。

  7. 改后端地址时斜杠要一起检查:从 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 应做必要的访问限制。

免责声明:本文为个人学习与实操经验总结,仅代表个人观点,不构成任何技术或商业决策建议。不同系统环境与版本可能存在差异,实际操作请以官方文档为准并自行验证。