在 nginx 中，`rewrite` 指令执行后默认会立即发起内部重定向，导致当前请求上下文被重置，此时设置的 `add_header` 头信息会被丢弃。要解决这个问题，必须使用 `return` 指令替代 `rewrite ... last`，或者在 `if` 块中直接返回状态码并携带头部。核心做法是：利用 `return` 指令的第三个参数（或单独设置）来同时完成状态码跳转和响应头的注入，确保头信息随最终响应发出。
为什么 rewrite 配合 add_header 会失效
因为 `rewrite` 指令只是修改了 URI，Nginx 随后会根据新的 URI 重新进行 location 匹配和配置处理。这个“重新处理”的过程会清空之前在该请求上下文中通过 `add_header` 累积的所有自定义头部。只有当请求真正结束并准备发送响应时，`add_header` 才会生效，而 `rewrite` 并没有结束请求，它只是改变了路径。
server {
listen 80;
server_name example.com;
# 错误示范：rewrite 后 add_header 无效
location /old {
rewrite ^/old/(.*)$ /new/$1 last;
add_header X-Custom-Header "value"; # 这行不会出现在响应中
}
# 正确示范：使用 return 301 并添加头部
location /new {
# 这里可以正常添加头部，因为请求在此处结束
add_header X-Custom-Header "value";
try_files $uri $uri/ =404;
}
}
上述代码展示了两种写法的对比。在 `/old` 位置块中，`last` 标志触发了内部重定向，导致 `X-Custom-Header` 丢失。而在 `/new` 位置块中，请求正常处理并结束，因此头部能成功附加到响应中。如果必须在重写逻辑中添加头部，应直接使用 `return`。
如何使用 return 实现重写与添加头部
`return` 指令可以直接终止当前请求的处理并发送响应，因此它是添加头部最可靠的方式。语法为 `return code [text];` 或 `return code URL;`。当需要传递动态数据给新地址时，可以使用 `$1` 等捕获组变量构建 URL，并通过 `add_header` 在同一个 `location` 或 `if` 块中设置头部。
server {
listen 80;
server_name example.com;
location /api/v1 {
# 检查是否包含特定参数，若存在则重定向并加头
if ($arg_legacy = "true") {
return 301 /api/v2$request_uri?redirected=1;
add_header X-Rewrite-Reason "Legacy API Redirect";
}
# 正常处理逻辑
proxy_pass http://backend;
}
}
注意：在 `if` 块中使用 `return` 时，`return` 之后的指令（包括 `add_header`）不会被执行，因为 `return` 会立即终止处理。因此，正确的做法是将 `add_header` 放在 `return` 所在的同一作用域，但通常 `return` 本身不直接支持在返回值中嵌入头部。更稳妥的做法是在目标 location 中添加头部，或者使用 `map` 结合 `return` 的复杂逻辑。但在简单的场景下，如上述代码所示，如果希望重定向后的页面带有头部，应在目标 location (`/api/v2`) 中定义 `add_header`。如果必须在重定向瞬间添加头部（例如用于调试），可以使用 `add_header` 配合 `return` 在同一 `location` 块中，但需确保 `return` 不是 `if` 块内的最后一条语句且后面无其他逻辑冲突，实际上 Nginx 官方推荐在目标 location 中管理头部。
基于 $request_uri 的重写结果验证
在使用 `return 301 /new/$1$request_uri` 时，`$request_uri` 包含了原始查询字符串。这意味着重定向后的 URL 会保留原有的 GET 参数。例如，访问 `/old/page?id=1`，若规则匹配，将重定向至 `/new/page?id=1`。这种机制确保了客户端状态在重定向过程中不被丢失，同时可以在目标 location 中根据这些参数动态决定是否添加特定的安全头或缓存控制头。
