@name 是 Nginx 中专用于内部跳转的命名 location，不可被客户端访问，仅通过 error_page、try_files 或 rewrite break 等指令触发，用于封装复用代理、PHP 执行或 fallback 等逻辑，提升配置可维护性。
@name 是 Nginx 中专用于内部跳转的命名 location，它不对外提供服务，只在配置内部被 error_page、try_files 或 rewrite break 后触发，本质是一个不可访问的逻辑锚点。
命名 location 的核心用途
它不是用来响应用户请求的，而是把一组处理逻辑（比如代理、PHP 执行、静态文件 fallback）打包成一个可复用的“代码块”，避免重复写 proxy_pass 或 fastcgi_pass 等指令。
- 常见场景：统一处理 404、接管 try_files 失败后的逻辑、集中定义后端转发规则
- 不能直接通过浏览器访问
http://example.com/@api—— 这会返回 404，这是设计使然，不是配置错误 - 不需要显式写
internal;，Nginx 自动将其设为 internal
@name 的正确写法与常见误区
必须以 @ 开头，后面紧跟合法标识符（字母、数字、下划线），且不能带斜杠或空格。
- ✅ 正确：
location @php { fastcgi_pass unix:/var/run/php.sock; } - ❌ 错误：
location /@php { ... }—— 这变成普通 location，可能被外部访问 - ❌ 错误：
location @php/ { ... }—— @ 后不能跟斜杠 - ❌ 错误：
return 200 "ok";单独放在 @name 块里却期望直接访问 —— 它必须被其他指令调用才生效
典型调用方式
命名 location 只有被内部指令触发才有意义：
-
error_page 404 @notfound;→ 请求路径不存在时静默跳转到 @notfound -
try_files $uri $uri/ @proxy;→ 先找文件，找不到就交给 @proxy 处理 -
rewrite ^/old/(.*)$ /new/$1 break; proxy_pass http://backend;可优化为：rewrite ^/old/(.*)$ /new/$1 break; proxy_pass http://backend;→ 更清晰的做法是把 proxy_pass 封装进@backend，再用try_files … @backend或error_page … @backend复用
为什么推荐用 @name 而不是重复写配置
当多个 location 需要共用同一套后端逻辑（如相同超时、header 处理、健康检查策略），把它们提取到命名 location 中，能显著提升可维护性。
- 修改代理地址、超时时间、重试次数，只需改一处
- 避免因复制粘贴导致某处漏改，引发不一致行为
- 让主 location 块更聚焦于路由判断，而非执行细节
