nginx 管理状态码的核心是控制传递、拦截或改写后端响应码以匹配接口契约，通过 return 主动返回、error_page 映射兜底、proxy_intercept_errors 启用拦截、add_header 增强语义实现精准控制。
直接管理 Nginx 返回的状态码，核心不是“让 Nginx 生成新状态码”，而是控制它如何传递、拦截或改写后端响应的状态码，以匹配接口契约（比如前端约定只认 200，或要求错误必须返回 4xx 而非 5xx）。关键在于理解 Nginx 的角色——它本身不执行业务逻辑，但可做状态码的路由、转换和兜底。
用 return 指令主动返回指定状态码
适用于无需转发、纯静态响应或快速拒绝的场景。Nginx 可直接终止请求并返回预设状态码及可选响应体：
-
简单拦截：如禁止某路径访问，直接返回 403：
location /admin { return 403; } -
健康检查适配：K8s 或负载均衡器常要求 /healthz 返回 200，即使后端未就绪：
location = /healthz { return 200 'OK\n'; } -
重定向统一出口：所有旧域名请求强制跳转，用 301 避免 SEO 权重流失：
server_name old.example.com; return 301 https://new.example.com$request_uri;
用 error_page 实现状态码映射与兜底
当后端服务返回特定错误码（如 502/503），而你需要对客户端隐藏真实失败原因、统一返回友好错误或重试逻辑，error_page 是标准做法：
- 把上游超时（504）转为 408 客户端超时：
error_page 504 = 408 /timeout.html; - 将所有 4xx/5xx 统一交由自定义页面处理：
error_page 400 401 403 404 500 502 503 504 /error.html; - 注意：
=表示不改变状态码；= 400表示改写为指定码；省略=则默认用原状态码返回页面
用 proxy_intercept_errors 控制错误响应透传
默认情况下，Nginx 对 4xx/5xx 响应会直接透传给客户端。开启此指令后，Nginx 才会触发 error_page 规则 —— 这是实现“状态码转换”的前提：
- 在 location 或 upstream 上下文中添加：
proxy_intercept_errors on; - 搭配 error_page 使用才有效，否则 502 仍原样返回，不会被你定义的兜底页捕获
- 常见误操作：开了 error_page 却没开 intercept，导致配置形同虚设
用 add_header + if（谨慎）补充状态码语义
HTTP 状态码本身不携带业务含义，但可通过响应头增强可读性。例如要求所有成功响应带 X-Result: success，或失败时加 X-Error-Code: order_not_found：
- 利用 add_header 的状态码过滤机制：
add_header X-Result "success" always;（加always才能作用于 4xx/5xx） - 配合 if 判断状态码做差异化头注入（不推荐复杂逻辑，易出错）：
if ($status = 404) { add_header X-Error-Code "resource_missing"; } - 更稳妥的做法是：由后端生成这些业务头，Nginx 仅做透传或简单改写
