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

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

绑定静态 HTML 页面

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

• 在 server 块中添加：
  error_page 404 /404.html;
error_page 500 502 503 504 /50x.html;
• 对应 location 必须精确匹配、设好路径、加 internal 防止直接访问：
  

  location = /404.html {<br>  root /usr/share/nginx/html;<br>  internal;<br>}

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

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

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

Nginx Hosting

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

下载

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

返回 JSON 或纯文本响应

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

• 在限流触发时返回 429 JSON：
  

  limit_req_status 429;<br>error_page 429 = @rate_limited;

• 在命名 location 中写：
  

  location @rate_limited {<br>  default_type application/json;<br>  add_header Content-Type "application/json";<br>  return 429 '{"code":429,"message":"Too many requests"}';<br>}

• 任意 location 中也可用 return 直接发响应：
  location /maintenance { return 503 "Service temporarily unavailable"; }

跨层级分级配置与复用

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

• 全局 http 块设兜底：
  error_page 500 /global-500.html;
• 某 server 块覆盖：
  error_page 404 /app-404.html;
• API 的 location 进一步细化：
  location /api/ { error_page 400 = @api_badreq; }
• 结合变量实现本地化，如用 $geoip_country_code 动态切换 root 路径