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

nginx 无法直接用 return 指令返回非标准状态码（如 499、599），必须通过 error_page + 内部 location 或 lua 模块实现；前者利用内部跳转绕过校验，后者通过 ngx.status 精确设置。

nginx 中实现自定义状态码返回配置

在 Nginx 中直接返回自定义状态码（如 499、599 或其他非标准码）不能仅靠 return 指令实现，因为 Nginx 默认只允许返回 RFC 定义的常见状态码（如 200、404、503 等）。若需返回任意整数状态码（例如 499、521、599），必须结合 error_page 和自定义错误页面机制来绕过校验限制。

使用 error_page + return 实现任意状态码

Nginx 的 return 指令本身会校验状态码合法性，但 error_page 可将内部重定向到一个 location，并在该 location 中用 return 发送不受限的状态码（Nginx 8.0+ 允许在内部跳转后的 location 中返回任意数值状态码）。

定义一个内部 location（以 @ 开头），里面用 return 返回目标状态码
用 error_page 将某个触发条件（如变量值、URL 路径、请求头）映射到该 location
通过 add_header 可选地添加响应头，如 Content-Type

示例：返回 599 自定义状态码

location /health {
    # 触发自定义状态码的条件（例如检查某个 header）
    if ($http_x_custom_flag = "abort") {
        return 444; # 先返回 444 断连，或改用 error_page
    }
    # 更推荐方式：用变量控制 error_page 触发
    set $custom_code "";
    if ($arg_code = "599") {
        set $custom_code "599";
    }
    if ($custom_code) {
        return 444; # 占位，实际由 error_page 处理
    }
}
<p>error_page 444 @custom_status;
location @custom_status {
return $custom_code "Custom Response\n";
add_header Content-Type "text/plain";
}</p>

通过 Lua 模块（OpenResty）精确控制状态码

若已部署 OpenResty 或编译了 ngx_http_lua_module，可直接在 Lua 中调用 ngx.status = xxx 设置任意状态码，无需绕过限制。

Nginx Hosting

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

下载

在对应 location 中嵌入 content_by_lua_block
用 ngx.status 赋值，再调用 ngx.say() 或 ngx.exit()
注意：设置 status 后必须显式输出内容或调用 exit，否则可能返回 200

示例：

location /api/v1/status {
    content_by_lua_block {
        local code = tonumber(ngx.var.arg_code) or 200
        ngx.status = code
        ngx.header["Content-Type"] = "text/plain"
        ngx.say("Status: ", code)
        ngx.exit(code)
    }
}

注意事项与常见问题

直接写 return 599; 会导致 Nginx 启动失败，报错 “invalid return code”。这是设计限制，不是配置错误。

499 状态码特殊性：Nginx 原生用 499 表示“客户端关闭连接”，不可主动返回；若需模拟，建议改用 499 以外的自定义码（如 498 或 599）
代理场景下状态码透传：后端返回非标状态码时，Nginx 默认会改为 502；需加 proxy_intercept_errors off; 并配合 error_page 捕获
日志记录：自定义状态码会正常记入 $status 变量，可用于 access_log 或监控