Nginx 中如何使用 proxy_redirect 修改后端跳转-Nginx-PHP中文网

proxy_redirect用于重写后端返回的location和refresh响应头，支持字面量和正则匹配，需在location块中配置，仅对该location生效，可解决因路径不一致导致的跳转失败问题。

nginx 中如何使用 proxy_redirect 修改后端跳转

当后端服务返回 301/302 跳转响应（如 Location: /old-path）时，Nginx 默认会原样透传该跳转地址给客户端。若后端路径与前端暴露路径不一致（例如后端用 /api/，前端是 /），直接透传会导致跳转失败。这时需用 proxy_redirect 重写响应头中的 Location 和 Refresh 字段。

基本语法与匹配逻辑

proxy_redirect 按“旧地址 → 新地址”规则重写跳转头，支持字面量匹配和正则匹配。它只作用于后端返回的 Location 和 Refresh 响应头，不影响 Nginx 自身的跳转行为。

字面量形式：proxy_redirect /old/ /new/; —— 将响应头中以 /old/ 开头的路径替换为 /new/
正则形式：proxy_redirect ~^/api/(.*)$ /$1; —— 用捕获组实现灵活重写
关闭重写：proxy_redirect off; —— 禁用所有重写（慎用，可能引发跳转错误）

常见场景与配置示例

典型问题包括后端返回绝对路径、带域名的跳转，或路径前缀不一致。以下为高频用法：

CPA Update - Secure CLI Proxy API Maintenance

安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

下载

后端返回 Location: http://backend.example.com/login，需改为当前域名：
proxy_redirect http://backend.example.com/ /;
后端返回 Location: /admin/xxx，但 Nginx 反代路径是 /app/：
proxy_redirect /admin/ /app/;
后端返回相对路径 Location: /login，而前端访问域名为 https://example.com，需补全协议和域名：
proxy_redirect / https://example.com/;

作用域与生效位置

proxy_redirect 必须放在启用代理的上下文中（location 块内），且仅对该 location 生效。它不会继承父块配置，也不能在 http 或 server 级全局启用（除非明确指定作用域）。

若多个 location 对应不同后端，需分别配置对应规则
若使用 proxy_pass 时带 URI（如 proxy_pass http://upstream/api/;），Nginx 会自动剥离匹配的前缀并尝试智能重写，但显式配置更可靠
配合 proxy_set_header Host 使用，确保后端生成的跳转地址基于正确 Host