一句话承诺：提供最小可用的反向代理配置与时序图，帮你快速定位 404 的真正来源。

对照表：404来源可能性

最小可用反向代理配置（示例）

http {
  upstream api {
    server 127.0.0.1:9000;
  }

  server {
    listen 80;
    server_name _;

    # 观测：在响应头注入上游状态
    proxy_set_header X-Real-IP $remote_addr;
    add_header X-Upstream-Status $upstream_status always;

    location /api/ {
      proxy_pass http://api;
      proxy_http_version 1.1;
      proxy_set_header Host $host;
      proxy_set_header Connection "";
    }

    # 静态文件最小配置
    location / {
      root /var/www/html;
      try_files $uri $uri/ /index.html;
    }
  }
}

核查动作

# 1) 直连上游确认是否为后端404
curl -i http://127.0.0.1:9000/api/v1/items

# 2) 查看命中的location
# 在nginx.conf中临时加入：
# add_header X-Location "$uri|$request_uri|$host" always;

# 3) 检查静态目录路径是否存在
ls -lah /var/www/html

少量解释

• 把 404 的来源分成“Nginx命中错误”与“上游返回404”两类，先直连上游排除后端问题。
• 使用 add_header X-Upstream-Status 在响应中暴露上游状态，便于区分代理/静态路径问题。
• try_files 能避免错误的文件路径匹配导致的404。

常见坑与替代法

• 坑：误用 alias 与 root 导致目录拼接错误。替代：使用 try_files 并明确目录结构。
• 坑：location /api 与 location / 覆盖冲突。替代：确保更精确的 /api/ 在前。
• 坑：上游返回 404 却以为是 Nginx 问题。替代：先 curl 直连上游端口。

下一篇预告

MySQL 查询慢又不想动业务：索引加法的三步微优化（案例表+执行计划）。