error_page可将502/503/504错误无感切换至静态备用页，提升服务韧性；需配置error_page指令、internal location、差异化降级页、健康检查及避坑要点。
当主站因后端服务宕机、网络中断或配置错误返回 502/503/504 等错误时，error_page 指令可立即接管响应，将用户无感切换至预置的静态备用站点（如维护页、降级首页、离线提示页），避免白屏或报错页面，提升用户体验与服务韧性。
核心配置：用 error_page 指向本地静态资源
在 server 或 location 块中添加：
- 指定错误码并重定向到内部 location：
error_page 502 503 504 /fallback.html; - 定义该路径指向本地文件：
location = /fallback.html { root /usr/share/nginx/html; internal; } -
internal是关键——它禁止外部直接访问/fallback.html，只允许 Nginx 内部跳转，防止备用页被恶意暴露或缓存污染
进阶实践：按错误类型提供差异化降级页
不同错误反映不同故障场景，可分层引导：
-
error_page 502 /502-maintenance.html;→ 后端不可达，显示“系统升级中” -
error_page 503 /503-overload.html;→ 服务过载，显示“稍后再试”+倒计时刷新 -
error_page 504 /504-timeout.html;→ 后端响应超时，提示“网络繁忙，请检查连接” - 所有 fallback 页面统一放在
/usr/share/nginx/html/fallback/下，便于集中管理与 CDN 预热
高可用增强：配合健康检查自动触发降级
仅靠 error_page 是被动响应。要真正实现“优雅引导”，需前置预防：
- 在
upstream块中启用健康检查：check interval=3 rise=2 fall=3 timeout=1;（需 nginx-plus 或第三方模块） - 当检测到所有后端均失败时，Nginx 自动将请求路由至 fallback location，此时
error_page已就绪，无缝生效 - 搭配
proxy_next_upstream error timeout http_502;可让单次失败请求自动重试其他节点，减少误触发 fallback 的概率
注意事项与避坑点
几个容易忽略但影响效果的关键细节：
-
error_page必须写在能捕获错误的上下文中——若 proxy_pass 在 location /api/ 下，而 502 出现在该 location，则 error_page 也需定义在同级 location 内，不能只放在 server 级 - 备用页本身必须是纯静态 HTML/CSS/JS，不依赖任何后端接口或动态渲染，否则会形成“降级页也挂了”的雪崩
- 建议对 fallback 页面开启 gzip 和 long cache（
expires 1h;），降低 CDN 回源压力，确保极端情况下仍能快速加载 - 可通过
add_header X-Fallback "true";在响应头中标记是否走降级路径，方便前端埋点或运维监控识别
