recursive_error_pages不支持循环重定向,仅允许error_page内部错误触发最多10层嵌套处理;超限返回500并记录日志,与http重定向无关。

recursive_error_pages 不是用来处理“重定向逻辑”的,它只负责在 error_page 内部触发错误时继续查找并执行下一级 error_page,属于服务端内部的错误兜底链路,和 301/302 等客户端重定向完全无关。想靠它实现多级跳转或循环重试,容易踩坑甚至触发 500 错误。
明确它的适用场景:静态资源多级 fallback
典型用途是为缺失资源提供逐级降级路径,比如:
- 用户请求
/img/logo.png→ 404 → 触发error_page 404 /fallback/logo.png -
/fallback/logo.pnglocation 内又 404 → 因开启recursive_error_pages on,再次查找匹配的error_page 404 /backup/logo.png -
/backup/logo.pnglocation 返回真实文件或兜底图,流程终止
整个过程不暴露给浏览器,全是内部 rewrite,响应始终是 200 或原始错误码(如最终也 404)。
必须配合的关键配置
仅开 recursive_error_pages on 不生效,还需满足三个条件:
-
每个 fallback location 必须能独立响应:推荐用
try_files或直接root/alias指向静态文件目录,避免该 location 自身再出错 -
显式启用错误捕获:静态文件 404 需在对应 location 块中加
recursive_error_pages on(http 块设为 on 是全局默认,但 location 可覆盖) -
代理返回的 404 要额外开启拦截:如果资源由后端服务返回 404,必须在 proxy location 中设置
proxy_intercept_errors on,否则 nginx 不会触发 error_page
避免超过 10 层嵌套的实用技巧
nginx 硬编码限制最多 10 层递归,超限直接返回 500 并记日志 rewrite or internal redirection cycle。安全做法:
- 每级 fallback location 末尾加
try_files $uri =404;,确保有明确终点 - 用不同 HTTP 状态码区分层级,例如第一级 fallback 返回 404,第二级返回 410(Gone),第三级返回 200 兜底图,避免无限匹配同一 error_page
- 在 error_log 中设
notice级别,实时观察是否出现循环警告
需要真正重定向时,请换用 rewrite + 条件判断
如果业务要求浏览器地址栏变化(如 /old-path → /new-path → /archive),应使用 rewrite 指令:
- 用
if或map提前判断路径是否存在或是否符合规则,避免无条件跳转 - 用
break终止后续匹配,防止重复 rewrite;用last重新进入 location 匹配(需谨慎设计退出条件) - 永远不要把
rewrite ... redirect和recursive_error_pages混用——它们运行在不同机制下,不会协同工作










