index 指令不能路由到命名 location（@location），因其仅在 content phase 查找并返回指定文件，不触发内部重定向；需用 try_files、rewrite last 或 return 302 等显式方式跳转至 @location。
index 指令不能直接路由到命名 location（@location）。这是个常见误解——index 的作用仅限于在匹配到目录（URI 以 / 结尾）且未启用 autoindex 时，自动查找并返回指定的文件（如 index.json），它不参与 location 跳转逻辑，更不会触发 @ 命名 location 的内部重定向。
为什么 index 无法跳转到 @location
index 是一个“文件服务指令”，不是控制流指令。它的执行发生在 content phase（内容处理阶段），只做两件事：
① 确认请求 URI 对应的是一个目录路径；
② 在 root 或 alias 指向的物理路径下，按顺序尝试读取所列文件（如 index.html、index.json），成功则直接返回该文件内容。
它不生成内部重定向，也不调用 internal redirect 机制，因此完全绕过命名 location 的触发条件。
想实现“访问 /api/ 自动返回 /api/index.json 并走特定逻辑”怎么办
若需将请求导向命名 location（比如统一做鉴权、日志或动态响应），必须用显式重定向或内部重写，而非依赖 index：
- 用
try_files+named location组合：location /api/ { root /opt/data; try_files $uri $uri/ @api_handler; } location @api_handler { # 例如返回固定 JSON 或转发给后端 return 200 '{"status":"ok"}'; # 或 proxy_pass http://backend; } - 用
rewrite ... last触发 location 重匹配：location /api/ { rewrite ^/api/$ /api/index.json last; } location = /api/index.json { root /opt/data; # 此处可加 access_log、limit_req 等逻辑 } - 精确匹配 + 内部重定向（推荐用于简单场景）：
location = /api/ { return 302 /api/index.json; # 或使用 internal redirect（需确保路径可被其他 location 匹配） # rewrite ^ /api/index.json break; }
什么时候该用 index，什么时候该用 @location
选 index 当你只是静态返回某个默认文件，且路径和文件物理存在一一对应（如 /docs/ → /var/www/docs/index.md）；
选 @location 当你需要注入额外处理逻辑——比如统一添加响应头、校验 token、记录审计日志、或 fallback 到动态服务。
验证是否生效的关键点
别只看返回内容，重点检查：
• HTTP 状态码（index 返回 200，redirect 返回 301/302，internal redirect 仍是 200）；
• curl -I 查看 Location: 头是否存在；
• Nginx error log 中是否有 rewrite or internal redirection cycle 报错（说明重写配置有环）；
• 确保命名 location 前缀不与外部 URI 冲突（@api_handler 不会被直接访问，安全）。
