nginx内部跳转通过location @name、try_files、rewrite ... break和error_page实现静默流转,不暴露客户端、不改地址栏、不发重定向;其中@name最规范安全,仅限内部调用,用于逻辑复用、静态fallback、错误处理及统一代理。

用命名位置 @name 实现内部锚点跳转
这是最规范、最安全的内部跳转方式。`location @xxx` 定义的是纯内部标签,不能被外部访问,Nginx 自动设为 internal,只能由其他指令触发:
-
必须通过内部指令调用:比如
try_files $uri @php;(文件不存在时跳)或error_page 404 @notfound;(出错时跳) -
不能直接访问:访问
/@php会返回 404,这是设计使然,不是配置错误 -
适合封装复用逻辑:例如把所有 PHP 请求代理逻辑集中写在
location @php { proxy_pass http://php_backend; },多个入口可复用,避免重复配置
用 try_files 实现“存在则服务,否则内部转发”
这是静态资源 + 动态兜底的经典模式,本质是按顺序检查文件/路径是否存在,最后落到命名位置:
-
try_files $uri $uri/ @api;→ 先找真实文件,再找目录索引,都不行就静默跳到@api - 注意:
try_files后最后一个参数必须是内部位置(如@xxx)或 URI;若写成/fallback则会发起一次新的外部请求(可能触发循环) - 常与
root或alias配合,确保文件路径解析正确
用 rewrite … break 实现路径重写后内部匹配
当需要根据规则改写请求路径,又不想让客户端感知时,用 break 标志:
-
rewrite ^/v1/(.*)$ /api/$1 break;→ 把/v1/xxx改成/api/xxx,然后停止当前 rewrite 流程,重新用新路径匹配 location - 区别于
last:break不会再次进入 rewrite 阶段,更安全,不会意外触发死循环 - 适合做 API 版本路由、路径标准化等,但逻辑较分散,不如命名位置清晰
用 error_page 统一接管异常响应
不只是 404,任何状态码(包括上游返回的 502、503)都可绑定到命名位置做内部处理:
-
error_page 502 503 504 @maintenance;→ 后端不可用时,自动跳到维护页逻辑 -
location @maintenance { return 503 "Service temporarily unavailable"; }或返回静态页 - 关键点:error_page 的跳转是内部的、无状态码透传的(除非显式用
return),客户端看到的是最终响应码











