Nginx 中通过状态码控制请求分发策略-Nginx-PHP中文网

nginx不支持直接按上游状态码路由，但可通过proxy_next_upstream实现自动重试、error_page+named location实现降级跳转、openresty+lua实现精细状态码路由。

nginx 中通过状态码控制请求分发策略

Nginx 本身不直接支持根据上游返回的 HTTP 状态码（如 500、404、429）动态切换后端分发目标，它没有内置的“按状态码路由”指令。但可以通过组合使用 proxy_next_upstream、error_page、map 和 upstream 的状态控制机制，间接实现基于响应状态码的请求重试、降级或分流逻辑。

下面介绍几种实用、生产环境验证过的实现方式：

基于 proxy_next_upstream 的自动重试与故障转移

该指令决定在什么情况下将请求转发给下一个 upstream server，适用于容错重试场景（不是“分发”，而是“兜底重试”）：

Nginx Hosting

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

下载

upstream backend {
    server 10.0.0.10:8080;
    server 10.0.0.11:8080;
    server 10.0.0.12:8080 backup;
}

server {
    location /api/ {
        proxy_pass http://backend;
        proxy_next_upstream error timeout http_500 http_502 http_503 http_504;
        proxy_next_upstream_tries 3;
        proxy_next_upstream_timeout 10s;
    }
}

当后端返回 500、502 等指定状态码时，Nginx 会自动尝试下一个可用 server（含 backup）
注意：这不会改变原始分发逻辑（如轮询顺序），只是失败后重试；且仅对当前请求生效，不改变后续请求的路由

使用 error_page + named location 实现状态码驱动的降级跳转

可将特定错误状态码捕获，并重定向到备用 upstream 或静态响应：

upstream primary { server 10.0.0.10:8080; }
upstream fallback { server 10.0.0.20:8080; }
upstream static_fallback { server 127.0.0.1:8081; } # 返回兜底页面

server {
    location /service/ {
        proxy_pass http://primary;
        proxy_intercept_errors on; # 启用 error_page 拦截

        # 捕获 500/502/503 并跳转到 fallback
        error_page 500 502 503 = @fallback;
    }

    location @fallback {
        proxy_pass http://fallback;
    }

    # 可再设一层兜底：fallback 也失败时返回本地页面
    location /service/ {
        proxy_pass http://fallback;
        proxy_intercept_errors on;
        error_page 500 502 503 = @static_fallback;
    }

    location @static_fallback {
        proxy_pass http://static_fallback;
    }
}

proxy_intercept_errors on 是关键，否则 error_page 不生效
= @name 表示内部重定向（不改变 URL，不返回 302）
适合灰度发布、主备切换、API 降级等场景

利用 map + $upstreamhttp* 提取响应头做条件判断（需配合 Lua 或 OpenResty）

纯 Nginx 配置无法读取上游响应体或状态码变量用于 map，但可通过 ngx_http_lua_module 实现真正意义上的“状态码路由”：

# 需启用 lua-resty-core 和 lua-nginx-module
location /smart/ {
    access_by_lua_block {
        local res = ngx.location.capture("/upstream_proxy")
        if res.status == 503 then
            ngx.exec("@maintenance")
        elseif res.status == 429 then
            ngx.exec("@rate_limited")
        else
            ngx.status = res.status
            ngx.header.content_type = res.header["content-type"]
            ngx.print(res.body)
        end
    }
}

location @maintenance {
    return 503 '{"msg":"Service under maintenance"}';
}

location @rate_limited {
    return 429 '{"msg":"Too many requests"}';
}

location /upstream_proxy {
    internal;
    proxy_pass http://primary;
    proxy_hide_header X-Upstream;
}

这属于高级用法，依赖 OpenResty，适合需要精细化控制的业务网关层
不推荐在高并发简单场景滥用，有性能开销

小结：实际选型建议

只想自动避开坏节点？ → 用 proxy_next_upstream 配合健康检查（最轻量）
主服务异常时切到备用 API？ → error_page + proxy_intercept_errors（标准、稳定）
需要根据 401 跳登录页、404 渲染 SPA、429 返回限流头？ → OpenResty + Lua（灵活但复杂）
误以为 map $status 可用？ → ❌ $status 是 Nginx 自身响应状态，不是 upstream 返回值，不可用于 upstream 分发决策