如何自定义limit_req_status指令触发限流时的JSON错误响应内容结构？

本文共计796个文字，预计阅读时间需要4分钟。

{ error: { code: limit_req_status, message: 自定义 JSON 响应体 - 它只控制 HTTP 状态码，不负责响应内容。, description: 想返回结构化 JSON 错误信息，例如：

为什么 limit_req_status 无法设置 JSON 响应体

limit_req_status 是一个纯状态码开关：它只在限流触发时把原本的 503 改成你指定的值（如 429），但 Nginx 仍会用内置的默认错误页（纯文本 HTML）。它不接管响应体生成逻辑，也不支持模板或 JSON 字符串配置。

常见误解是以为设了 limit_req_status 429 就能自动输出 JSON，结果 curl 一测发现还是 text/html 的丑陋页面，甚至 Content-Type 都没变。

正确做法：用 error_page 拦截限流状态并重写响应

核心思路是：让限流触发后返回你指定的状态码 → 用 error_page 把该状态码映射到内部 location → 在该 location 中用 return 直接输出 JSON（或用 proxy_pass 转发给后端生成）。

• 必须先在 limit_req_zone 和 limit_req 中启用，并搭配 limit_req_status 429
• error_page 429 = @rate_limited; —— 注意等号，表示不跳转、直接内部重定向
• 在 location @rate_limited 中，用 return 429 '{"error":"rate_limited","code":429}\n';
• 务必手动设置 add_header Content-Type "application/json; charset=utf-8";，否则默认是 text/plain

示例片段：

limit_req_zone $binary_remote_addr zone=api:10m rate=5r/s; server { location /api/ { limit_req zone=api burst=10 nodelay; limit_req_status 429; <pre class='brush:php;toolbar:false;'> error_page 429 = @rate_limited; # ... 其他 proxy_pass 等 } location @rate_limited { add_header Content-Type "application/json; charset=utf-8"; return 429 '{"error":"rate_limited","code":429,"retry_after":60}\n'; }

}

注意 Content-Type 和字符编码的隐性坑

Nginx 的 return 指令默认不带 Content-Type，浏览器或客户端可能按 text/plain 解析 JSON，导致解析失败。更隐蔽的是：如果 JSON 中含中文（如 "msg":"请求过于频繁"），不加 charset=utf-8 会导致乱码，尤其在旧版 curl 或某些 SDK 中表现不一致。

• add_header 必须写在 location @rate_limited 内，写在 server 或外层 location 无效（因为 return 会终止处理流程）
• JSON 字符串里的换行符 \n 建议保留，部分 HTTP 工具（如 Postman）对无换行的单行 JSON 渲染异常
• 若需动态字段（如当前时间、剩余等待秒数），return 无变量支持，得改用 proxy_pass 转给一个轻量 endpoint

真正麻烦的不是怎么写这几行配置，而是排查时容易卡在 Content-Type 缺失或 charset 漏写 —— 表现就是 JSON 看起来“对”，但前端 JSON.parse() 报错，或者日志里显示乱码。动手前先用 curl -I 确认响应头是否符合预期。