Nginx 自定义错误页通过 error_page 指令映射状态码到内部 location 或文件，支持静态页、重定向、JSON 响应及跨作用域分级配置，需配合 internal、return 和 add_header 等指令实现。
在 Nginx 中配置自定义响应状态码页，核心是用 error_page 指令将特定状态码映射到内部处理逻辑，并配合 location 块返回内容或重定向。它不改变业务逻辑，只接管错误响应的呈现方式。
指定状态码并指向自定义页面
最常用的方式是为常见错误码（如 404、502）绑定本地 HTML 文件：
-
error_page 404 /404.html;—— 请求路径不存在时，返回根目录下的404.html -
error_page 500 502 503 504 /50x.html;—— 多个后端错误共用一个兜底页 - 对应 location 需加
internal;，防止用户直接访问该路径：
location = /404.html {<br> root /usr/share/nginx/html;<br> internal;<br>}
修改原始状态码再响应
若希望浏览器收到的是另一个状态码（比如把 404 改成 302 跳转），可在 error_page 后加等号和目标状态码：
-
error_page 404 =302 /redirect.html;→ 返回 302 状态 + 页面内容（实际跳转由客户端决定） -
error_page 404 = @moved;→ 转交命名 location，再用return 301 https://new.example.com/; - 注意：等号右侧不能是外部 URL，必须是内部路径或命名 location
返回 JSON 或动态内容
API 场景下常需返回结构化错误体，例如限流触发时返回 429 + JSON：
- 先用
limit_req_status 429;触发自定义状态码 - 再配
error_page 429 = @rate_limited; - 在
location @rate_limited中写：
return 429 '{"code":429,"message":"Too many requests"}';<br>add_header Content-Type "application/json"; - 命名 location 是唯一支持
return带 body 的合法位置
跨作用域复用与分级处理
大型部署中可分层定义错误响应：
- 全局
http块设默认页：error_page 500 /global-500.html; - 特定
server块覆盖：error_page 404 /app-404.html; - API
location内进一步细化：error_page 400 = @api_badreq;，再用 Lua 或静态 JSON 响应 - 不同地区还可结合
$geoip_country_code动态指定 root 路径，实现本地化错误页
