nginx反向代理需四步闭环实现友好错误页：一开proxy_intercept_errors on；二配error_page 502 504 /offline.html；三设internal location服务错误页；四确保html文件存在且nginx有读权限。
Nginx 做 HTTP 反向代理时，后端出错（比如挂了、超时、返回 502/504）默认会把原始错误直接甩给用户，页面难看还暴露细节。要实现「自动拦截 → 换成友好错误页」，核心不是只放个 HTML，而是四个动作必须闭环：开拦截开关、配跳转规则、防外部直访、确保文件可读。
必须开启 proxy_intercept_errors
Nginx 默认把后端返回的 502、504 当作“正常响应”原样透传，根本不会走 error_page。得在代理 location 里显式打开：
-
proxy_intercept_errors on;
⚠️ 注意：它只对状态码 ≥ 400、且响应体非空、含合法 HTTP 头部的响应生效；后端返回 200 + 错误内容，它不管——那是业务该处理的。
明确声明 error_page 跳转路径
光开开关没用，必须在同一作用域写清楚哪些错误码跳哪：
-
error_page 502 504 /offline.html; -
error_page 404 /not-found.html; - 或统一兜底：
error_page 400 401 403 404 500 502 503 504 /error.html;
路径/offline.html是 URI，不是文件路径，后面得有对应 location 去服务它。
单独定义 internal location 服务错误页
错误页不能被用户直接访问（否则绕过业务逻辑），也不能靠 root 全局指定：
location = /offline.html {
internal;
root /usr/share/nginx/html;
}
-
internal;是关键，禁止 curl https://www.php.cn/link/43ae9925db5ddfb25bf7f772d8069788 直接命中； -
root写在这里，表示实际文件是/usr/share/nginx/html/offline.html； - 确保这个 HTML 文件真实存在，且 Nginx 进程有读权限，否则会触发新错误（比如 500）。
静态资源和动态接口分开对待
-
动态接口（如
/api/）：应开启proxy_intercept_errors，保障错误体验一致； -
静态资源（如
/static/）：通常不该开这个指令，否则后端返回 404 时 Nginx 拦截后可能丢掉 Content-Type；更稳妥的是让 Nginx 自己 serve 静态文件，失败再 fallback 到 error_page。
不复杂但容易忽略
