Nginx 中配置状态码以满足不同业务接口-Nginx-PHP中文网

nginx 不生成业务逻辑状态码，而是统一治理响应状态码：支持按路径/参数直接返回（如 return 200/503）、转换上游错误码（如 500→503）、限流返回标准 429、按状态码分流日志。

nginx 中配置状态码以满足不同业务接口

Nginx 本身不直接“生成”业务逻辑状态码，但它能精准控制响应状态码的输出时机、语义和行为，这对 API 接口的规范性、可观测性和客户端体验至关重要。关键不是让 Nginx 替代后端判断业务逻辑，而是用它做统一入口层的状态码治理：拦截、转换、兜底、限流反馈、重定向语义强化。

以下几种典型场景，覆盖绝大多数接口需求：

按请求路径或参数统一返回标准状态码

适合健康检查、开关类接口、静态兜底等无需后端参与的轻量级响应。

return 指令直接终止处理并返回指定状态码（含可选响应体）

示例：

location /healthz {
    return 200 '{"status":"ok","ts":' $msec '}';
}
location /maintenance {
    return 503 '{"code":"MAINTENANCE","msg":"系统升级中"}';
}

将上游错误状态码转换为更准确的语义状态码

后端可能返回笼统的 500，但客户端需要区分“服务不可用”还是“请求非法”。Nginx 可在反向代理层做语义修正。

Nginx Hosting

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

下载

使用 error_page 捕获上游状态码，再用 return 或 proxy_pass 转发到内部 location 统一处理

示例（把上游 500 转为 503，404 转为 410）：

location /api/ {
    proxy_pass http://backend;
    error_page 500 =503 @service_unavailable;
    error_page 404 =410 @gone;
}
location @service_unavailable {
    default_type application/json;
    return 503 '{"code":"SERVICE_UNAVAILABLE"}';
}
location @gone {
    return 410 '{"code":"GONE"}';
}

限流触发时返回符合 RFC 的标准状态码

默认限流返回 503 不够明确，429 是 RESTful 接口的标准选择。

limit_req_status 必须与 limit_req 同级配置，且仅作用于该规则

示例：

limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;
location /api/v1/ {
    limit_req zone=api_limit burst=20 nodelay;
    limit_req_status 429;
    proxy_pass http://backend;
}

根据状态码分流日志或监控告警（非响应，但强相关）

虽然不改变返回状态码，但能让不同错误类型快速定位。

用 map 提取 $status 分组变量，配合多 access_log 实现按 4xx/5xx 分离写入

示例（http 块内）：

map $status $log_4xx { ~^4\d\d "4xx"; default ""; }
map $status $log_5xx { ~^5\d\d "5xx"; default ""; }
log_format simple '$remote_addr [$time_local] "$request" $status';
access_log /var/log/nginx/access.log simple;
access_log /var/log/nginx/4xx.log simple if=$log_4xx;
access_log /var/log/nginx/5xx.log simple if=$log_5xx;

不复杂但容易忽略