Nginx 中配置状态码以增强接口控制

return指令是最轻量高效的状态码控制方式，支持直接返回200、403、404、301/302等状态码，结合if可条件化响应，try_files可隐式触发404/503等，应避免用rewrite redirect替代return或在if中使用proxy_pass。

直接用 return 指令就能精准控制状态码，这是最轻量、最高效的方式。它不走文件查找、不转发、不执行后续逻辑，一击命中，适合做快速拦截或协议响应。

return 指令：最常用也最推荐的写法

语法简单明确：return 状态码 [响应体];

1. 200 OK：用于健康检查接口或空响应场景，例如：return 200 "OK";
2. 403 Forbidden：拒绝未授权访问，比如校验 header 失败后：if ($http_x_api_key = "") { return 403 "Missing API key"; }
3. 404 Not Found：隐藏真实路径或屏蔽非法入口，如禁用 .git 目录：location ~ /.git { return 404; }
4. 301/302 重定向：配合正则可做路径规范化，例如强制末尾带斜杠：location ~ ^/api/v1[^/]$ { return 301 $uri/; }

结合 if + return 实现条件化状态码

注意：if 在 location 内可用，但不能嵌套，且仅支持有限变量（如 $http_*、$arg_*、$request_uri）。

1. 校验请求头是否合规：if ($http_user_agent !~* "(curl|wget|python-requests)") { return 403; }
2. 限制请求方法：if ($request_method !~ ^(GET|HEAD|POST)$) { return 405; }
3. 拦截特定参数值：if ($args ~* "debug=1") { return 400 "Debug mode disabled in production"; }

用 try_files 隐式触发状态码

当文件不存在时，try_files 会自动返回 404；若指定 fallback URI，则可能触发 302 或内部重定向。

1. 静态资源兜底：try_files $uri /index.html =404; —— 找不到就返回 404
2. 单页应用路由适配：try_files $uri $uri/ /index.html; —— 前端路由 fallback 到 index.html，Nginx 不报错
3. 主动降级响应：try_files /maintenance.html =503; —— 存在维护页则返回，否则直接返回 503

避免常见误区

有些做法看似合理，实则低效或不可靠：

1. 不用 rewrite ... redirect 替代 return 302：前者多一次重写+重匹配，性能差且易循环
2. 不在 if 中调用 proxy_pass：Nginx 明确不支持，会导致配置加载失败
3. 不依赖 error_page 做主动拦截：它是被动捕获错误，无法替代前置判断逻辑
4. 慎用 break 和 last 混合 return：return 本身已终止流程，加 break 多余