在 nginx 中配置二级目录反向代理,核心做法是在 server 块内使用 location /path/ 匹配前缀,并通过 proxy_pass http://backend/; 将请求转发至后端服务。当 proxy_pass 的 url 末尾包含斜杠时,nginx 会自动剥离 location 匹配到的路径部分并追加到后端请求中;若省略斜杠,则会将完整 uri 原样传递给后端。这种差异决定了后端应用接收到的实际路径结构,需根据后端框架的路由规则选择正确的写法。

如何正确编写 location 和 proxy_pass 指令
要完成二级目录的反向代理,需要在 nginx.conf 或站点配置文件中定义一个 location 块,指定匹配的前缀路径,并在其中设置 proxy_pass 指向目标服务器的地址。关键在于 proxy_pass 值的末尾是否带有斜杠,这直接影响了请求 URI 的传递方式。如果希望访问 /api/v1/users 时后端收到的是 /users,则 proxy_pass 必须带斜杠;如果希望后端收到完整的 /api/v1/users,则不能带斜杠。通常对于微服务或 API 网关场景,带斜杠的写法更为常见,因为它能实现路径的重定向映射。

server {
listen 80;
server_name example.com;
# 配置二级目录 /api 的反向代理
location /api/ {
# 注意末尾的斜杠,它表示去掉 /api/ 后剩余部分传给后端
proxy_pass http://127.0.0.1:8080/;
# 必要的代理头设置
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
上述配置中,location /api/ 匹配以 /api/ 开头的任何请求。例如,请求 /api/v1/data 会被转发到 http://127.0.0.1:8080/v1/data。如果 proxy_pass 写为 http://127.0.0.1:8080(无斜杠),则请求 /api/v1/data 会被转发到 http://127.0.0.1:8080/api/v1/data。开发者应根据后端应用期望的路径前缀来决定是否保留斜杠。此外,proxy_set_header 指令用于传递客户端真实 IP 和原始主机名,确保后端能正确识别请求来源。
如何处理静态资源与动态请求的混合代理
在实际部署中,二级目录可能同时包含静态资源和动态 API 请求。此时需要区分处理,避免将静态文件错误地转发给后端应用服务器。可以通过在 location 块中使用 try_files 或直接针对特定后缀设置不同的 location 来实现。例如,对于 /static/ 目录下的图片、CSS 和 JS 文件,应直接从磁盘读取;而对于 /api/ 目录下的请求,则进行反向代理。这种分离不仅提高了性能,也避免了后端服务器处理不必要的静态请求。

server {
listen 80;
server_name example.com;
# 静态资源直接由 Nginx 提供
location /static/ {
alias /var/www/html/static/;
expires 30d;
}
# 动态 API 请求反向代理
location /api/ {
proxy_pass http://127.0.0.1:8080/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
# 默认根目录
location / {
root /var/www/html;
index index.html;
}
}
在上述配置中,location /static/ 使用 alias 指令将 URL 路径映射到服务器上的物理目录。例如,请求 /static/image.png 会返回 /var/www/html/static/image.png 文件。而 location /api/ 继续执行反向代理逻辑。这种结构清晰地分离了静态内容和动态内容,是 Web 服务器配置的常见模式。需要注意的是,alias 和 root 指令在使用时有细微差别:root 是将 location 路径附加到根目录后,而 alias 是用指定的路径完全替换 location 路径。在二级目录场景中,alias 通常更直观。
当后端服务返回重定向时,二级目录路径会发生什么变化
当后端应用在处理请求后返回 HTTP 重定向响应(如 301 或 302)时,Nginx 作为反向代理会直接将后端返回的 Location 头透传给客户端。如果后端应用 unaware 它处于二级目录下,它可能会返回绝对路径如 Location: http://backend/new-path 或相对路径 Location: /new-path。这会导致客户端跳转到非预期的地址,因为浏览器会基于当前 URL(即 example.com/api/...)解析相对路径,或者直接使用后端提供的绝对路径。为解决此问题,后端应用应配置其基础 URL 前缀,或使用 Nginx 的 proxy_redirect 指令来修正重定向地址。
server {
listen 80;
server_name example.com;
location /api/ {
proxy_pass http://127.0.0.1:8080/;
# 修正后端返回的重定向地址
# 将后端返回的 /new-path 转换为 /api/new-path
proxy_redirect http://127.0.0.1:8080/ /api/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
proxy_redirect 指令允许 Nginx 修改后端响应中的 Location 和 Refresh 头。在上述示例中,如果后端返回 Location: http://127.0.0.1:8080/new-path,Nginx 会将其替换为 Location: /api/new-path,从而确保客户端被正确重定向到二级目录下的新路径。这是处理二级目录反向代理时容易忽略但至关重要的步骤,尤其在后端应用未正确配置上下文路径时。通过这种方式,可以保持 URL 结构的一致性,避免用户遇到 broken links 或循环重定向问题。











