error_page是nginx自定义错误页的核心指令，通过将指定状态码重定向到内部uri实现错误响应处理；需配合root/alias或internal location确保uri可访问，并支持状态码保留、变量透传及map条件分发。
在 Nginx 中，error_page 指令是实现错误页面自定义的核心机制。它不改变真实响应状态码（除非配合 return 或 rewrite），而是将特定 HTTP 状态码的响应“重定向”到一个内部 URI，由该 URI 对应的 location 处理并返回内容——这正是实现美观、统一、带业务逻辑的错误页的关键。
基础语法与常见写法
error_page 必须写在作用域内（如 http、server 或 location 块中），基本格式为：
error_page 状态码... URI;
例如：
-
error_page 404 /404.html;→ 所有 404 响应都交由根路径下的/404.html返回 -
error_page 500 502 503 504 /5xx.html;→ 多个状态码共用一个页面 -
error_page 403 =403 /forbidden.html;→ 显式保留 403 状态码（等号后为新状态码） -
error_page 404 =200 /notfound.html;→ 把 404 改成 200 响应（慎用，SEO 不友好）
让错误页真正“生效”的关键配置
仅写 error_page 不够，还需确保目标 URI 能被正确服务。常见方式有两种：
-
静态文件方式：URI 指向磁盘上真实存在的 HTML 文件，需配合
root或alias定义路径映射
示例：root /var/www/html;error_page 404 /404.html;
→ 实际读取/var/www/html/404.html -
内部 location 处理方式（更灵活）：用
location = /404.html拦截，可加 header、日志、甚至代理到后端
示例：error_page 404 /404.html;location = /404.html {
internal;
add_header Content-Type text/html;}
传递原始请求信息（提升用户体验）
默认情况下，错误页无法获取原请求 URL、参数或方法。可通过 $request_uri、$host、$scheme 等变量，在 error_page 后接参数方式透传：
error_page 404 /error.html?uri=$request_uri&host=$host;- 然后在
/error.html中用 JS 读取 URL 参数，动态展示“您访问的页面 xxx 不存在” - 注意：若使用
internallocation，变量仍可用；但外部跳转时需确保参数安全（避免 XSS）
高级用法：按条件返回不同错误页
利用 map 指令 + 变量，可实现基于 User-Agent、来源域名或路径前缀的差异化错误页：
- 先定义映射：
map $http_user_agent $error_page_type {
~*curl|wget "cli";
default "web";} - 再使用：
error_page 404 /errors/404_$error_page_type.html; - 这样 API 调用（curl）看到的是纯文本 404，浏览器用户看到的是带样式的 HTML 页面
不复杂但容易忽略：务必检查文件权限、Nginx 用户能否读取错误页文件，以及是否启用 recursive_error_pages off;（默认关闭，无需开启，除非你真需要多层 error_page 嵌套）。
