Nginx无法定义全新HTTP状态码（如999），但可通过error_page+return组合返回标准码（如451）、map动态映射后端标识、或用标准码+自定义header/body传递业务语义。
在 Nginx 中无法直接定义全新的 HTTP 状态码（如 999），但可以通过 error_page + return 或自定义响应头/体的方式，实现“逻辑上返回特定状态码”的效果，满足业务标识、调试或网关协议适配等需求。
利用 error_page 拦截并重定向到自定义 return
这是最常用且兼容性最好的方式：先用内部跳转触发一个未公开使用的标准状态码（如 499、451 或 444），再通过 error_page 捕获它，最终用 return 发送目标状态码和响应内容。
示例：返回自定义语义的 451（已被 RFC 定义为“因法律原因不可用”，但可按需复用）：
location /api/v1/test {
# 触发内部错误（不对外暴露）
return 451;
}
error_page 451 = @custom_451;
location @custom_451 {
internal;
add_header X-Custom-Status "BlockedByPolicy";
return 451 "{ \"code\": 451, \"msg\": \"Access denied by local regulation\" }";
}
- 必须使用
internal防止外部直接访问该命名 location -
return后的内容会作为响应体，需自行控制格式（JSON、纯文本等） - 状态码必须是标准 HTTP 码（100–599），Nginx 不允许返回非法值（如 600 或 999），否则报错
用 map 模块动态设置状态码（需配合 proxy_pass 或子请求）
当后端服务返回特定标识（如 header 或 body 字段），可用 map 提取并映射为状态码，再通过 proxy_intercept_errors on 和 error_page 联动处理。
示例：后端返回 X-App-Status: 498 表示“凭证过期”，Nginx 将其转为 401 并补充提示：
map $upstream_http_x_app_status $mapped_status {
"498" 401;
default 200;
}
server {
location /api/ {
proxy_pass http://backend;
proxy_intercept_errors on;
error_page 401 = @handle_401;
# 注意：此处 401 是由 map 触发的，不是后端真实返回
}
location @handle_401 {
internal;
add_header WWW-Authenticate "Bearer realm=\"api\"";
return 401 "{ \"error\": \"invalid_token\", \"status\": 401 }";
}
}
-
map只能作用于变量，不能直接生成非标状态码，但可辅助决策流程 - 需开启
proxy_intercept_errors才能拦截后端返回的错误状态并交由 error_page 处理 - 确保后端实际返回的状态码在 Nginx 可识别范围内（如 200 带特殊 header），避免被直接透传
伪造响应状态码（仅限调试，不推荐生产）
通过 Lua（OpenResty）或第三方模块（如 headers-more-nginx-module）可修改响应行，但这违反 HTTP 协议规范，多数客户端/代理会忽略或报错，仅适合本地验证逻辑。
- 使用
more_set_headers "Status: 499 Custom Reason"无效——该指令只设 header，不改状态行 - OpenResty 中可用
ngx.status = 499+ngx.say()实现，但需注意 response body 必须在 status 设置后输出 - CDN、负载均衡器或浏览器可能重写或拒绝非标准状态码，导致行为不可控
替代方案：用标准状态码 + 自定义 header/body 表达语义
更稳妥的做法是坚持使用标准状态码（如 400/401/403/422/429/503），并通过 header（X-App-Code）或 JSON body 显式携带业务含义。
- 例如：统一返回 400，但 body 中含
"code": "INVALID_SIGNATURE" - 前端或调用方解析
X-App-Code进行差异化处理，比依赖状态码更灵活可靠 - 符合 REST API 设计惯例，利于监控、日志分类和中间件兼容
