Nginx 中如何通过 nginx.conf 配置自定义错误响应内容

核心是用error_page指令接管错误状态码，结合location返回静态页、重定向或JSON响应；需配root/alias定位文件、internal防直访、=覆盖状态码，并支持http/server/location多级配置与变量动态适配。

在 Nginx 中通过 nginx.conf 配置自定义错误响应内容，核心是用 error_page 指令接管特定状态码，并结合 location 块返回静态文件、重定向或动态响应体。它不修改业务逻辑，只控制错误发生后的呈现方式。

绑定静态 HTML 页面

最常用的方式：为 404、500 等状态码指定本地 HTML 文件。

1. 在 server 块中添加：

   error_page 404 /404.html;

   error_page 500 502 503 504 /50x.html;

2. 对应 location 必须精确匹配、设好路径、加 internal 防止直接访问：

   location = /404.html {

   root /usr/share/nginx/html;

   internal;

   }

3. 确保文件真实存在且 Nginx 有读取权限，例如 /usr/share/nginx/html/404.html

替换响应状态码并返回内容

用等号（=）可覆盖原始状态码，返回新状态 + 自定义内容。

1. error_page 404 =302 /redirect.html; → 返回 302 状态和 /redirect.html 内容（浏览器不自动跳转，需配合 JS 或 meta 标签）
2. error_page 404 = @moved; → 转交命名 location，再用 return 301 https://new.example.com/;
3. 注意：= 后不能写外部 URL，只能是内部路径或命名 location

返回 JSON 或纯文本响应

适合 API 场景，直接生成结构化错误体。

1. 在限流触发时返回 429 JSON：

   limit_req_status 429;

   error_page 429 = @rate_limited;

2. 在命名 location 中写：

   location @rate_limited {

   default_type application/json;

   add_header Content-Type "application/json";

   return 429 '{"code":429,"message":"Too many requests"}';

   }

3. 任意 location 中也可用 return 直接发响应：

   location /maintenance { return 503 "Service temporarily unavailable"; }

跨层级分级配置与复用

大型部署中支持按作用域分层定义，提高可维护性。

1. 全局 http 块设兜底：

   error_page 500 /global-500.html;

2. 某 server 块覆盖：

   error_page 404 /app-404.html;

3. API 的 location 进一步细化：

   location /api/ { error_page 400 = @api_badreq; }

4. 结合变量实现本地化，如用 $geoip_country_code 动态切换 root 路径