proxy_redirect用于重写后端3xx响应中的Location和Refresh头，使其适配前端域名路径；它在Nginx转发响应前生效，仅作用于location块内，支持正则匹配与捕获组实现动态替换，并需配合proxy_set_header Host使用。
当 Nginx 作为反向代理时，后端服务（如 Flask、Spring Boot 或 PHP 应用）返回的 301/302 响应中，Location 头往往包含原始内部地址（如 http://127.0.0.1:8080/login 或 https://backend.example.com/error），这会导致浏览器跳转失败或暴露内网信息。使用 proxy_redirect 可以动态重写这些地址，使其适配前端访问的域名和路径。
理解 proxy_redirect 的作用机制
proxy_redirect 不是重写请求，而是改写后端响应头中的 Location 和 Refresh 字段。它在 Nginx 接收到后端响应后、转发给客户端前生效。该指令只对 3xx 响应起作用，且必须出现在 location 块中（或 http/server 级，但 location 级最灵活）。
基本语法为：proxy_redirect [default | off | redirect replacement];
常用形式是两参数：指定要匹配的原始 Location 前缀，以及替换成的目标前缀。
用正则匹配实现动态修正（推荐）
当后端返回的重定向地址不固定（比如含动态端口、不同子路径、或协议混用），硬编码前缀容易失效。此时应启用正则支持：
- 在
proxy_redirect指令前加~（区分大小写）或~*（忽略大小写） - 使用
$1、$2等捕获组引用匹配内容，实现“原样保留路径，只换协议/域名/前缀” - 确保
proxy_set_header Host ...和proxy_redirect配合使用，避免 Host 丢失影响重写逻辑
示例：用户通过 https://app.example.com/api/v1/ 访问，后端返回 Location: http://localhost:3000/login?next=/api/v1/dashboard，希望改为 https://app.example.com/login?next=/api/v1/dashboard：
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
location /api/v1/ {
proxy_pass http://127.0.0.1:3000/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
<pre class="brush:php;toolbar:false;"># 将 http://localhost:3000/ → https://app.example.com/
proxy_redirect ~^http://localhost:3000(/|$) https://$host$1;
# 同时处理可能的相对重定向（如 Location: /login）
proxy_redirect / /api/v1/;}
处理相对路径与根路径重定向
后端有时返回相对 Location: /login 或绝对路径 Location: /api/v1/logout，此时需注意上下文路径映射：
- 若
proxy_pass末尾有/（如proxy_pass http://backend/;），Nginx 会剥离location匹配路径再转发，重定向也应按此逻辑修正 - 用
proxy_redirect / /api/v1/;可将后端返回的根路径重定向（/login）自动补上前缀 - 若后端返回的是完整路径但不含 host（如
Location: /v1/auth/callback），直接匹配路径前缀即可，无需正则
调试与验证关键点
配置生效前务必验证，常见问题包括：
- 浏览器开发者工具 Network 标签中检查 302 响应的
Location值是否已更新 - Nginx 错误日志（
error_log）开启info级别，可看到proxy_redirect是否匹配成功 - 确认没有多个
proxy_redirect冲突（后定义的会覆盖先定义的） - 如果用了
proxy_redirect default，它等价于proxy_redirect http://localhost:port/ /;，仅适用于简单场景，不推荐用于复杂路径映射
不复杂但容易忽略。
