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 后加等号和目标状态码：

Nginx Hosting

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

下载

• 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 路径，实现本地化错误页