Nginx 中如何自定义请求状态码返回逻辑-Nginx-PHP中文网

nginx可通过return、error_page和map指令灵活控制响应状态码。return直接返回指定码（支持100–999）；map基于变量条件映射状态码；error_page捕获并重写状态码或跳转；需注意非标准码兼容性及响应体content-type设置。

nginx 中如何自定义请求状态码返回逻辑

在 Nginx 中，不能直接像后端语言那样“动态生成”任意状态码（比如 return 499 或 return 599），但可以通过 return、error_page 和 map 等指令灵活控制响应状态码的返回逻辑。关键在于理解 Nginx 的处理阶段和配置组合方式。

用 return 指令直接返回指定状态码

这是最简单直接的方式，适用于基于请求特征（如 URI、参数、头信息）做静态判断的场景。

return 只能出现在 server、location 或 if 块中（不推荐在 if 中滥用）
支持标准 HTTP 状态码（1xx–5xx），也支持自定义非标准码（如 499、521），只要数值在 100–999 范围内
可选附带响应体和 Content-Type，例如：return 403 "Access denied.\n";

示例：对特定路径返回 451（被法律禁止）

location /restricted/ {
    return 451 "This content is unavailable in your region.";
}

结合 map 实现条件化状态码映射

当需要根据变量（如请求头、参数、Cookie）动态决定状态码时，map 是更清晰、高效的选择。它在 rewrite 阶段前完成变量计算，避免 if 的陷阱。

定义一个映射变量（如 $custom_status），将请求特征映射为状态码数值
在 location 中用 return $custom_status 触发返回
支持正则、字符串匹配，也支持默认值（default）

示例：根据请求头 X-Env 返回不同状态码

Nginx Config Linter

对 Nginx 配置文件进行语法检查、验证和安全、性能审计。

下载

map $http_x_env $custom_status {
    default     200;
    "staging"   406;
    "blocked"   451;
}

server {
    location /api/ {
        return $custom_status;
    }
}

用 error_page + 自定义错误页实现状态码跳转逻辑

当需要返回某个状态码并同时渲染对应页面（或重定向到其他位置）时，error_page 是标准做法。它不改变原始响应码，而是捕获后重新响应。

error_page 404 =200 /fallback.html; 表示将 404 捕获后以 200 状态码返回 fallback 页面
= 后跟数字表示重写响应状态码；不加 = 则沿用原状态码并跳转到指定 URI
可配合 try_files 或内部重定向，实现“伪装”状态码的效果

示例：把所有未登录请求统一返回 401，并显示登录页

location /private/ {
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
    error_page 401 = @login;
}

location @login {
    return 401 "Please log in.";
    add_header Content-Type text/html;
}