nginx 状态码映射通过 error_page、proxy_intercept_errors、map 与 return 等机制实现，而非直接重写状态码；需启用 intercept 才能拦截上游错误，支持内部重定向、状态码改写及条件响应，并应结合日志标记确保可追溯性。
在 Nginx 中，状态码映射与处理策略不是靠“重写状态码”本身实现的（Nginx 不允许直接篡改上游返回的状态码），而是通过 error_page、proxy_intercept_errors、自定义响应体和条件跳转等机制，将特定状态码导向统一处理逻辑，从而达成语义映射、用户体验优化或后端解耦的目的。
用 error_page 实现状态码拦截与重定向
这是最常用的方式：当 Nginx 接收到上游（如后端应用）返回的特定状态码时，可中断原始响应，转而执行内部 location 或返回自定义内容。
- 必须配合
proxy_intercept_errors on;（对 proxy 场景）或fastcgi_intercept_errors on;（对 PHP-FPM）才能生效，否则 Nginx 直接透传状态码 -
error_page 404 = /404.html;表示拦截 404 并内部重定向到 /404.html（不改变浏览器地址栏，状态码仍为 404） -
error_page 502 =302 /maintenance.html;表示将 502 映射为 302 重定向到维护页（状态码变为 302，浏览器跳转） - 支持多状态码映射：
error_page 401 403 404 = /error.html;
用 return + map 实现动态状态码转换
若需根据请求特征（如 User-Agent、路径、Header）决定返回哪个状态码，可用 map 指令预定义映射规则，再结合 return 主动响应。
- 在 http 块中定义映射：
map $arg_status $mapped_code {<br> "unauth" 401;<br> "forbidden" 403;<br> "gone" 410;<br> default 200;<br>} - 在 server 或 location 中使用：
if ($mapped_code != 200) { return $mapped_code; }（注意：return 会终止处理并立即响应） - 适用于灰度测试、API 版本兼容、A/B 测试等需要按条件返回不同状态码的场景
代理层统一错误页与日志标记
真实生产中，不仅要“映射”，还要“可追溯”。建议把状态码处理与日志、监控联动。
- 为每个 error_page location 添加唯一标识：
location = /50x.html { add_header X-Error-Handled "50x"; } - 在 log_format 中记录原始 upstream 状态码：
$upstream_http_x_original_status（需后端主动设置该 header）或$upstream_status（Nginx 自带变量） - 避免掩盖问题：不要无差别把 5xx 全部转成 200；应保留原始状态码到日志，并仅对用户侧做友好降级
限制与注意事项
状态码映射不是万能的，需避开常见陷阱：
- Nginx 无法修改已发送响应头后的状态码（即不能在输出缓冲后“后悔”）
-
error_page只对 Nginx 自己生成的错误（如文件不存在）或启用 intercept 后捕获的 upstream 错误有效；未开启 intercept 时，4xx/5xx 会直接透传 - 使用
=语法时，等号后跟数字表示保持原状态码；跟 URI 表示内部重定向；跟其他数字（如 =302）表示强制改写状态码 - 避免循环：确保 error_page 指向的 location 不再触发同级 error_page 规则
