命名 location(以 @ 开头)是仅限 nginx 内部跳转使用的逻辑标签,不参与 uri 匹配、不响应外部请求、跳转时不改变原始 uri;常用于单页应用兜底、自定义错误页和条件化内部重写。

命名 location(以 @ 开头)不是用来响应用户请求的,而是专供 Nginx 内部指令跳转使用的“逻辑标签”,它不参与常规 URI 匹配流程,也不改变浏览器看到的地址。
命名 location 的本质是内部跳转目标
它像一个只能被 Nginx 自己调用的子程序,外部无法通过 URL 访问(比如访问 /@app 会直接 404)。只有 try_files、error_page、rewrite ... last 这类指令才能触发跳转到它。跳转发生时,原始请求 URI 完全保留,只是处理逻辑切换了。
它和普通 location 的关键区别
- 不参与匹配排序:不会和
location /、location ~ \.js$等竞争,也不受优先级规则影响 - 不响应外部请求:客户端发来的任何以
@开头的路径,Nginx 都不会把它当作 location 处理 - 跳转不改 URI:比如用户请求
/user/profile,跳进location @router后,URI 仍是/user/profile,前端路由可据此渲染
典型使用场景
-
单页应用兜底:用
try_files $uri $uri/ @fallback,静态文件找不到就跳去返回index.html -
自定义错误页:用
error_page 404 @notfound,把 404 请求交由命名 location 统一处理(如返回美化页面或重定向) -
条件化内部重写:在
rewrite中配合last,跳进命名 location 做二次路径处理,避免外部重定向
配置时要注意的细节
- 命名 location 块里避免用
root或alias,容易导致路径解析错乱;推荐用proxy_pass或rewrite ... last配合主 location 的 root -
try_files后面写的@name必须真实存在,否则会返回 500 错误 - 命名 location 中一般只放流向控制指令(
rewrite、return、proxy_pass),不建议加日志、限流或鉴权逻辑











