Nginx中location @name是仅限内部跳转的命名location，不可被客户端直接访问；它通过try_files、error_page等指令触发，用于实现错误处理、SPA降级等逻辑。
Nginx 中的 location @name 是命名 location，它不响应外部请求，只供内部重定向（如 error_page、try_files 或 rewrite ... last）使用。要实现“内部命名跳转”，关键不是直接访问 @name，而是通过指令触发内部跳转到它。
理解 @name 的作用范围
@name 是内部标记，不能被客户端直接访问（例如访问 /@fallback 会 404）。它仅在服务端处理流程中被 last 或 internal 类指令调用：
-
try_files $uri @fallback;—— 当文件不存在时，内部跳转到@fallback -
error_page 404 @fallback;—— 发生 404 时，内部跳转到@fallback -
rewrite ^/old/(.*)$ /new/$1 last;中的last会重新匹配 location，但若写成rewrite ^/old/(.*)$ @rewrite_handler last;，则必须确保@rewrite_handler存在且逻辑合理（注意：rewrite 不支持直接跳转到 @name，该写法无效；应改用try_files或error_page配合）
正确配置命名 location 的基本结构
一个可用的命名 location 必须包含明确的处理逻辑，比如返回内容、代理转发或内部重写：
location @proxy_api {
proxy_pass http://backend;
proxy_set_header Host $host;
}
<p>location @serve_index {
internal; # 可选，强化“仅内部访问”语义（Nginx 1.19.2+ 默认所有 @location 均为 internal）
root /var/www/app;
try_files /index.html =404;
}</p>
⚠️ 注意：internal 指令不是必须的（现代 Nginx 对 @location 默认禁止外部访问），但显式声明更清晰。
常用组合：try_files + @name 实现优雅降级
这是最典型也最实用的场景，例如 SPA 应用的前端路由 fallback：
location / {
root /var/www/spa;
try_files $uri $uri/ @fallback;
}
<p>location @fallback {
root /var/www/spa;
try_files /index.html =404;
}</p>
说明：
- 请求
/about→ 文件不存在 → 触发@fallback -
@fallback尝试返回/var/www/spa/index.html，让前端路由接管
搭配 error_page 实现统一错误处理
将特定 HTTP 状态码映射到命名 location：
location /api/ {
proxy_pass http://api_backend;
proxy_intercept_errors on; # 允许拦截后端返回的错误码
error_page 500 502 503 504 @api_error;
}
<p>location @api_error {
internal;
root /usr/share/nginx/html;
try_files /5xx.html =500;
}</p>
要点：
-
proxy_intercept_errors on是启用error_page拦截代理错误的前提 -
@api_error返回自定义错误页，路径基于root指令拼接 - 避免在 @location 中再写
proxy_pass或复杂逻辑——保持轻量、明确、可维护
