Nginx 中实现自定义状态码返回机制-Nginx-PHP中文网

nginx无法定义全新http状态码（如999），但可通过error_page+return组合返回标准码（如451）、map动态映射后端标识、或用标准码+自定义header/body传递业务语义。

nginx 中实现自定义状态码返回机制

在 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 联动处理。

Nginx Hosting

通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

示例：后端返回 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、负载均衡器或浏览器可能重写或拒绝非标准状态码，导致行为不可控