在使用Nginx做反向代理的架构中，有一个指令经常被忽略，但一旦忽略就会出现莫名其妙的跳转问题，它就是proxy_redirect。典型场景是这样的：后端Tomcat监听在8080端口，用户通过Nginx的80端口访问，当后端返回一个302重定向，响应头里的Location值是http://192.168.1.10:8080/login，浏览器拿到这个地址后直接跳向了内网IP，页面自然打不开。proxy_redirect的作用就是在Nginx把响应返回给客户端之前，按照配置的规则把Location（以及Refresh）响应头中的地址重写一遍，让它变回用户可以正常访问的外部地址。
一、先理解问题：Location响应头是怎么暴露内网地址的
反向代理的工作流程中，Nginx作为中间人，把客户端请求转发给上游服务器，再把上游响应原样（除了显式配置修改的头）返回给客户端。问题在于，上游服务器并不知道自己在被代理，它构建重定向地址时，会基于自己收到的请求信息来拼URL。如果Nginx转发时没有正确传递Host头，上游会以为访问者是http://127.0.0.1:8080，于是生成的Location就是这个内部地址。
很多后端框架还提供了转发头识别机制，比如Java生态中的X-Forwarded-Host、X-Forwarded-Proto，Spring Boot配合ForwardedHeaderFilter可以自动构建正确的外部地址。但并非所有应用都开了这个能力，有些老系统、第三方闭源服务根本没有办法修改后端行为，这时候就只能靠Nginx在响应阶段做兜底重写，这正是proxy_redirect的用武之地。
区分一下容易混淆的两个方向：proxy_set_header处理的是请求方向的头，影响的是上游如何看到客户端；而proxy_redirect处理的是响应方向的头，影响的是客户端如何看到上游。前者是预防手段，后者是补救手段，两者经常需要配合使用。
二、proxy_redirect的语法与四种取值方式
proxy_redirect的完整语法形式是proxy_redirect redirect replacement;，意思是把Location中以redirect开头的部分替换成replacement。除此之外它还支持default、off以及正则表达式三种特殊形式。下面通过一个基础配置来看它的实际用法：
server {
listen 80;
server_name www.example-domain.com;
location /app/ {
proxy_pass http://127.0.0.1:8080/;
# 当上游返回 Location: http://127.0.0.1:8080/index
# 会重写为 Location: http://www.example-domain.com/app/index
proxy_redirect http://127.0.0.1:8080/ http://www.example-domain.com/app/;
}
}这个配置里，第一参数是要被匹配的前缀，第二个参数是替换后的前缀。Nginx做的是前缀匹配加整体替换，不是简单的字符串搜索。也就是说http://127.0.0.1:8080/xxx会被完整重写为http://www.example-domain.com/app/xxx，路径部分原样保留。
再看default这个特殊值。写成proxy_redirect default;时，Nginx会根据location和proxy_pass的配置自动推导替换规则：假设location /app/对应proxy_pass http://backend/;，那么默认重写规则就等价于proxy_redirect http://backend/ /app/;。它的好处是零维护成本，proxy_pass改了以后规则自动跟着变；缺点是推导能力有限，遇到复杂的路径映射就不够用了。
off则表示完全关闭重写，Location头原样透传给客户端。这在某些场景下是必要的，比如上游本身就能感知外部地址，或者你需要保留原始重定向语义做调试。需要注意的是，proxy_redirect默认值其实就是default，很多人以为不配置就是不重写，这是不对的，默认行为一直在悄悄工作。
三、正则匹配与变量替换：应对复杂场景
当被代理的是一组服务器而不是固定地址时，前缀写死就不行了。这时可以在redirect位置使用正则表达式，配合变量捕获来动态替换：
upstream backend {
server 10.0.0.11:8080;
server 10.0.0.12:8080;
}
server {
listen 80;
server_name www.example-domain.com;
location / {
proxy_pass http://backend;
# redirect参数以 ~ 开头表示大小写敏感正则，~* 表示忽略大小写
proxy_redirect ~^(http://10\.0\.0\.(?:11|12):8080)/(.*)$ http://www.example-domain.com/$2;
}
}这段配置里，正则捕获了两台后端机器的地址，统一替换为对外域名，路径通过$2保留。使用正则时有个细节要记住：redirect部分必须以波浪号开头声明为正则，而replacement部分永远是普通字符串加变量，不参与正则语义。
replacement中还可以使用Nginx内置变量实现更灵活的拼接，比如$host、$scheme、$server_port。典型用法如proxy_redirect http://$proxy_host/ $scheme://$host/;，其中$proxy_host变量会自动展开为proxy_pass中指定的上游主机名，这样一条规则就能覆盖所有上游地址，无需逐个罗列。
四、实战中的常见坑与排查方法
第一个坑是相对路径重写失效。proxy_redirect只处理绝对地址形式的Location，如果上游返回的是Location: /login这种相对路径，重写规则根本不会触发。好消息是相对路径本身没有内网地址问题，浏览器会基于当前域名解析它；但如果你的代理路径有前缀（比如/app/），上游返回的相对路径缺少这个前缀，就会跳错位置。这种情况要用sub_filter或者干脆在应用侧配置上下文路径来解决。
第二个坑是HTTPS卸载场景下的协议错误。Nginx监听443终结TLS，与上游之间走HTTP，上游返回的Location往往是http://开头，重写后如果仍保留http协议，浏览器会报混合内容或者HTTPS降级警告。解决办法是在replacement中使用$scheme或者直接写死https://：
server {
listen 443 ssl;
server_name www.example-domain.com;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
# 强制把http形式的Location重写为https对外地址
proxy_redirect http://127.0.0.1:8080/ https://www.example-domain.com/;
}
}第三个坑是重定向循环。如果重写规则写反了，或者replacement又恰好匹配了redirect规则，Location会被反复改写甚至形成死循环跳转。排查这类问题的通用方法是直接用curl观察原始响应头：curl -I http://127.0.0.1:8080/some/path先看上游返回什么，再看经过Nginx后的curl -I https://域名/some/path输出，两相对比就能确认重写是否按预期生效。
最后提一点工程实践建议：优先通过proxy_set_header Host $host加上后端的转发头识别让上游自己生成正确地址，proxy_redirect只作为无法修改后端时的兜底手段。同时可以在location块中配置多条proxy_redirect规则，Nginx会按顺序匹配，命中即停止，利用这个特性可以针对不同上游路径写差异化的重写策略。掌握这些细节后，反向代理下的跳转问题基本都能快速定位并解决。
Nginx proxy_redirect响应地址重写反向代理配置修改时间：2026-09-07 11:24:54