Nginx 中实现动态状态码返回策略配置-Nginx-PHP中文网

nginx可通过map+return或lua实现动态状态码返回；map适合简单条件映射，需定义在http块顶层；lua支持复杂逻辑如限流，需编译lua模块；注意return终止请求、if使用限制及3xx重定向配置。

nginx 中实现动态状态码返回策略配置

在 Nginx 中无法直接“动态计算”状态码（如根据请求时间、参数值实时生成 403/429/503），但可通过内置变量、条件判断与模块组合，实现基于规则的动态状态码返回。核心依赖 map 指令、return 指令和可选的第三方模块（如 ngx_http_lua_module）。

用 map + return 实现轻量级动态状态码

map 是最常用且无需额外编译的方案，适合基于请求头、参数、IP 等简单条件返回不同状态码。

定义映射关系：将变量（如 $arg_status 或 $http_user_agent）映射为状态码数值
确保映射结果仅含合法状态码（如 200、401、403、429、500、503），非法值会触发 500 错误
在 server 或 location 块中用 return $status_code; 触发返回

示例：根据查询参数 debug 返回不同状态码

map $arg_debug $dynamic_status {
    ""      200;
    "fail"  500;
    "auth"  401;
    "rate"  429;
    default 200;
}

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

结合 geo 或 real_ip 实现 IP 级策略

对特定 IP 段或客户端地址返回定制状态码，常用于灰度拦截或地域限制。

Nginx Config Linter

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

下载

使用 geo 指令预定义 IP 映射变量（如 $blocked），值为 1 表示需拦截
配合 if 判断（注意：仅限 return 和 set 等有限指令）
更安全做法是用 map 将 $remote_addr 映射为状态码，避免 if 的坑

示例：对测试网段返回 403

map $remote_addr $ip_status {
    ~^192\.168\.10\. 403;
    default 200;
}

location /admin/ {
    return $ip_status;
}

用 Lua 脚本实现复杂逻辑（需编译 lua-module）

当需调用外部 API、读取 Redis、计算时间窗口限流时，Lua 是主流选择。

安装 nginx-module-lua（OpenResty 自带，或手动编译）
在 access_by_lua_block 中编写逻辑，设置 ngx.status 并调用 ngx.exit()
注意：Lua 中 ngx.exit(403) 会立即终止请求并返回对应状态码，不执行后续 handler

示例：每分钟限 5 次请求，超限返回 429

location /limited/ {
    access_by_lua_block {
        local limit = require "resty.limit.count"
        local lim, err = limit.new("my_limit", 5, 60)
        if not lim then
            ngx.log(ngx.ERR, "failed to create the limit object: ", err)
            return
        end

        local key = ngx.var.remote_addr
        local delay, err = lim:incoming(key, true)
        if not delay then
            if err == "rejected" then
                ngx.status = 429
                ngx.header["Retry-After"] = "60"
                ngx.exit(429)
            end
        end
    }
}