接口偶发 404 怎么办：从前端路径、Nginx rewrite 到后端路由逐层定位

接口偶发 404 很容易被误判成“后端没写这个接口”。但线上真实情况往往更复杂：有的用户能访问，有的用户 404；刷新后又好了；本地正常，发布到灰度环境才失败。此时直接盯控制器代码，很可能找错方向。

这篇文章按一次排查过程来写，从前端请求路径、Nginx rewrite、后端路由、灰度实例四层逐步定位。目标不是记住某个配置，而是建立一条可复用的 404 排查链路。

问题现场：同一个接口有时 200 有时 404

假设一个后台系统刚发布了订单备注功能。前端请求路径是：

POST /admin/api/orders/remark

测试环境正常，线上灰度后出现两个现象：

• 部分用户提交备注成功，接口返回 200。
• 部分用户提交备注失败，接口返回 404。
• 刷新页面后，有时请求路径变成 /api/orders/remark。
• 后端同学确认路由已经注册，不是接口没写。

这时不要急着重启服务。先把一条失败请求的链路信息收集齐：浏览器请求 URL、响应头、Nginx access log、后端应用日志、灰度实例编号。

初步判断：先确认 404 来自哪一层

404 可以来自多个位置，含义不同：

• 浏览器层：前端拼出的路径不对，请求还没到正确网关。
• Nginx 层：rewrite 或 location 没匹配，返回了静态 404。
• 应用层：请求到了后端，但路由表没有这个路径。
• 灰度层：部分实例路由配置旧，只有命中这些实例时失败。

一个快速判断方式是看响应头和响应体。Nginx 默认 404 页面通常很短，应用层 404 往往会带统一错误码、追踪 ID 或 JSON 响应。

curl -i 'https://example.com/admin/api/orders/remark'

如果响应类似下面这样，可能是 Nginx 返回的：

HTTP/2 404
server: nginx
content-type: text/html

如果响应是 JSON，并且带应用错误码，说明请求已经进入后端：

{
  "code": "ROUTE_NOT_FOUND",
  "trace_id": "req-20260630-001"
}

动手验证：对比浏览器路径和 Nginx 日志

接着把成功请求和失败请求放在一起看。浏览器 Network 面板里重点看三项：

• Request URL：路径是否带了 /admin 前缀。
• Status Code：404 是否来自同一个域名和同一个环境。
• Response Headers：是否有网关或应用标识。

Nginx access log 可以临时加上 upstream 信息，方便判断请求是否转发到后端：

log_format api_trace '$remote_addr $request $status '
                     'upstream=$upstream_addr '
                     'uri=$uri request_uri=$request_uri';

失败请求可能会看到：

POST /api/orders/remark 404 upstream=- uri=/api/orders/remark request_uri=/api/orders/remark

这说明请求没有进入 upstream，问题更可能在前端路径或 Nginx location，而不是后端控制器。

定位原因：rewrite 规则遗漏导致路径被截断

继续检查配置，发现系统有两套入口：

后台页面入口：/admin/
接口代理入口：/admin/api/
历史接口入口：/api/

前端在某个子页面使用了相对路径：

fetch('/api/orders/remark', {
  method: 'POST',
  body: formData
})

在本地开发代理里，/api/ 会被正常转到后端；但线上 Nginx 只代理 /admin/api/，于是 /api/orders/remark 落到静态站点 location，直接返回 404。

还有一种常见情况是 rewrite 少保留了一段路径：

location /admin/api/ {
    rewrite ^/admin/api/(.*)$ /$1 break;
    proxy_pass http://backend;
}

如果后端路由注册的是 /api/orders/remark，上面规则会把路径改成 /orders/remark，应用层自然找不到路由。

修复方案：统一前端 base path 和网关转发规则

修复分两步：先统一前端请求前缀，再确认 Nginx 转发后的路径和后端路由一致。

前端侧：集中管理接口前缀

const API_BASE = '/admin/api';

function apiPath(path) {
  return API_BASE + path;
}

fetch(apiPath('/orders/remark'), {
  method: 'POST',
  body: formData
});

不要在不同页面里手写 /api、/admin/api、相对路径三种写法。只要入口统一，灰度和线上环境的路径差异会少很多。

Nginx 侧：明确保留或去掉前缀

如果后端路由是 /api/orders/remark，可以转发时保留 /api：

location /admin/api/ {
    rewrite ^/admin/api/(.*)$ /api/$1 break;
    proxy_pass http://backend;
}

如果后端路由是 /orders/remark，那就去掉前缀，但要和后端约定清楚。关键是让“浏览器看到的路径”和“后端收到的路径”可预测。

验证结果：看 404 数、命中路由和灰度实例

修复后不要只测一次按钮。建议看三类结果：

• 浏览器 Network：所有入口都请求 /admin/api/orders/remark。
• Nginx 日志：upstream 不再是 -，请求确实进入后端。
• 后端日志：路由命中同一个 handler，灰度实例和正式实例一致。

可以用一组简单指标确认修复效果：

修复前：/api/orders/remark 404 占比 18%
修复后：404 占比 0%，upstream 命中率 100%
灰度实例：route_version 全部为 20260630-remark

如果修复后仍偶发 404，就继续看是否有旧静态资源缓存、灰度实例没更新、浏览器 Service Worker 缓存旧 JS 等问题。

总结：接口 404 要按链路分层查

接口偶发 404 不要只问“后端有没有这个接口”。更有效的顺序是：先看浏览器实际请求路径，再看 Nginx 是否转发到 upstream，再看后端收到的路径和路由表，最后确认灰度实例是否一致。

只要把前端 base path、Nginx rewrite、后端路由三者对齐，并用日志记录 request_uri、uri、upstream，这类 404 问题就能从猜测变成可验证的链路排查。