Nginx 用 error_page + intercept_errors 拦截并定制静态资源的 404/50x 页面，需配合 root/alias 定位文件，按 /api/ 路径区分 JSON/HTML 响应，并通过 headers、NJS、JS 上报和 Git 管理增强体验与可观测性。
直接在 Nginx 配置中用 error_page 指令接管错误响应，是为静态资源服务定制专属 404 与 50x 页面最轻量、最高效的方式。它不依赖后端，也不触发额外请求，所有错误在网关层就完成识别、拦截与渲染，既保障体验，又提升可观测性。
基础配置：让 error_page 生效的关键开关
仅写 error_page 404 /404.html; 不一定生效——Nginx 默认会透传上游错误（如 PHP-FPM 返回的 404），而非自己生成响应。必须配合拦截开关：
- fastcgi_intercept_errors on;：用于 FastCGI 场景（如 PHP），开启后 Nginx 才会拦截 400–599 状态码并执行 error_page 规则
- proxy_intercept_errors on;：用于反向代理场景（如后端是 Node/Java），让 Nginx 拦截代理返回的错误状态
- 这两项需放在
http或server块中，且必须在error_page指令之前
路径与定位：确保自定义页面能被正确找到
error_page 后面的路径是“URI 路径”，不是文件系统路径。它的实际位置由所在 location 块中的 root 或 alias 决定：
- 用
root /var/www/static;时，error_page 404 /404.html;对应文件是/var/www/static/404.html - 用
alias /var/www/errors/;时，error_page 404 /404.html;对应文件是/var/www/errors/404.html（注意 alias 末尾斜杠） - 推荐统一使用
alias指向专用错误页目录（如/var/www/errors），避免与主站 root 冲突
区分场景：API 返回 JSON，页面返回 HTML
静态资源服务常同时承载 Web 页面与 API 接口。可按请求路径智能分发错误格式：
- 对
/api/开头的请求，返回结构化 JSON：location ^~ /api/ {<br> error_page 404 =404 /api-404.json;<br> error_page 500 502 503 504 =500 /api-error.json;<br>} - 对普通页面请求，返回带品牌风格的 HTML：
location / {<br> error_page 404 /404.html;<br> error_page 500 502 503 504 /50x.html;<br>} - 关键点：
=404表示保持原始状态码；不加=会被转成 200，影响前端判断
增强体验：让静态错误页不“静态”
即使是纯 HTML 错误页，也能通过简单手段注入动态信息，提升专业感与排查效率：
- 添加
add_header Cache-Control "no-cache, no-store, must-revalidate";到错误页 location 中，防止浏览器缓存旧版页面 - 在 HTML 中预留占位符（如
），配合 NJS 脚本替换为真实请求地址，方便用户反馈或自助排查 - 嵌入轻量 JS：自动上报
$upstream_status、$host和$request_time到前端监控，无需后端参与 - Git 托管所有错误页，CI 构建后同步到各节点，确保多实例间内容一致
