在 nginx 中,rewrite 与 return 配合使用的核心逻辑是:利用 rewrite 进行 url 模式匹配和变量提取(如正则捕获),一旦匹配成功且设置了 last 或 break 标志,nginx 会重新发起请求;随后在后续的 location 块或 server 块中,使用 return 指令直接返回指定的 http 状态码、重定向地址或自定义内容。这种组合通常用于实现复杂的 url 重写后跳转、基于特定条件的 api 路由分发,或者将动态请求转换为静态响应。

如何从旧 URL 中提取参数并重定向到新路径?
当需要将带有特定前缀的旧版 URL 映射到新版结构时,可以使用 rewrite 的正则表达式捕获组来提取关键参数,并通过 return 构建新的目标 URL。例如,将所有以 /api/v1/ 开头的请求重定向到 /api/v2/,同时保留原有的资源路径。具体做法是在 server 或 location 块中使用 rewrite ^/api/v1/(.*)$ /api/v2/$1 last;,然后在对应的 location /api/v2/ 中使用 return 301 $request_uri; 或直接返回固定响应。如果希望更灵活地控制返回值,可以在 rewrite 之后不设置 last,而是通过 set 指令设置变量,最后用 return 引用该变量。

server {
listen 80;
server_name example.com;
# 第一步:匹配旧格式并提取 ID
rewrite ^/old/resource/([0-9]+)$ /new/resource?id=$1 last;
location /new/resource {
# 第二步:根据提取的 ID 返回不同内容
if ($arg_id = "123") {
return 200 '{"status": "success", "id": "123"}';
}
return 404 '{"error": "ID not found"}';
}
}
上述配置中,访问 /old/resource/123 会被 rewrite 规则拦截,内部重写到 /new/resource?id=123。接着进入 location /new/resource,if 条件检查查询参数 $arg_id 是否为 123,如果是则通过 return 返回 JSON 成功信息;否则返回 404 错误。注意 rewrite ... last 会导致请求在服务器内部重新处理,而 return 会立即终止后续处理并发送响应。
如何根据用户代理或请求头动态决定返回状态?
在某些场景下,需要根据客户端的请求特征(如 User-Agent 或自定义 Header)来决定是否允许访问或返回特定状态码。此时可以先用 rewrite 进行初步的路由匹配,再通过 map 或 if 结合 return 实现动态响应。例如,对于所有非浏览器请求(如爬虫或 API 客户端),可以统一返回 403 禁止访问,而对于正常浏览器请求则继续处理。具体做法是定义一个 map 块来判断请求类型,然后在 location 中使用 return 返回相应状态码。

map $http_user_agent $is_bot {
default 0;
~*bot 1;
}
server {
listen 80;
server_name example.com;
location /api/data {
# 如果检测到 bot,直接返回 403
if ($is_bot) {
return 403 'Access denied for bots';
}
# 否则继续处理或返回正常数据
return 200 '{"data": "public info"}';
}
}
在这个例子中,map 指令根据 $http_user_agent 设置 $is_bot 变量。当请求进入 /api/data 时,if 判断 $is_bot 是否为 1,如果是,则通过 return 403 直接拒绝访问;否则返回 200 正常数据。这种方式避免了使用 rewrite 进行复杂的重写链,而是通过变量预处理和 return 快速决策,提高了配置的可读性和执行效率。
当 rewrite 匹配失败时 return 的行为是什么?
如果 rewrite 指令中的正则表达式未能匹配当前 URI,则该 rewrite 规则将被跳过,请求将继续按照 Nginx 的标准 location 匹配流程进行处理。此时,return 指令如果在同一个 location 块中且未被 if 或其他条件阻断,将会按原样执行。例如,在一个 location /test 中,如果 rewrite 规则不匹配,但下方有 return 200 'OK',那么请求仍会返回 200 OK。这意味着 rewrite 的失败不会自动触发 return 的异常处理,除非 return 被包裹在特定的条件判断中。因此,在设计配置时,应确保 return 的逻辑与 rewrite 的匹配结果一致,避免意外返回默认响应。


















