核心规则速览

proxy_pass指令后的代理地址（upstream）是否包含 URI 部分，直接决定了原始请求 URI 的处理方式。

定义说明：

• 不带 URI：指 upstream 地址仅包含协议、域名和端口（可省略），如 http://www.zhujishice.cn。
• 带 URI：指 upstream 地址包含协议、域名、端口及路径，如 http://www.zhujishice.cn/ 或 http://www.zhujishice.cn/api。

场景拆解：不带 URI（直接拼接）

当 proxy_pass 后不包含路径时，Nginx 会将完整的客户端请求 URI（包括 location 匹配的部分）直接拼接到 upstream 地址之后。

配置示例：

server {
    listen 8080;
    server_name example.com;
    # 案例 1: location 以目录形式结尾
    location /aaa/ {
        proxy_pass http://www.zhujishice.cn;  # 注意：末尾无斜杠
    }
    # 案例 2: location 以路径形式结尾
    location /aaa {
        proxy_pass http://www.zhujishice.cn;  # 注意：末尾无斜杠
    }
}

请求转发结果：

注意：如果客户端访问 /aaa 但 location 定义为 /aaa/（带斜杠），Nginx 通常会返回 301 重定向到 /aaa/。

场景拆解：带 URI（替换拼接）

当 proxy_pass 后包含路径（URI）时，Nginx 会执行“剪裁+拼接”操作：

• 剪裁：从客户端原始 URI 中去除 location 匹配成功的部分。
• 拼接：将剩余部分（剩余 URI）拼接到 proxy_pass 指定的 URI 之后。

规范用法（推荐）

配置示例：

location /aaa/ {
    proxy_pass http://www.zhujishice.cn/;  # upstream 带根路径
}

请求转发：
访问 http://www.zhujishice.cn:8080/aaa/xxx
剪裁：/aaa/xxx - /aaa/ = xxx
拼接：http://www.zhujishice.cn/ + xxx = http://www.zhujishice.cn/xxx

常见变形与避坑指南

最佳实践与总结

1. 一致性原则：为了路径清晰，建议 location 指令的结尾符与 proxy_pass 中 upstream 的 URI 结尾符保持一致。
   • 推荐：location /prefix/ 配 proxy_pass http://www.zhujishice.cn/。
   • 推荐：location /prefix 配 proxy_pass http://www.zhujishice.cn（不带 URI）。
2. 避免歧义：尽量不要混用“带斜杠”和“不带斜杠”的写法（如 location /aaa 配 proxy_pass http://www.zhujishice.cn/），以免产生双斜杠或路径截断错误。
3. 正则匹配：本文基于通用字符串匹配（location /path）。若使用正则表达式匹配（location ~ /path），路径剪裁规则可能有所不同，需单独测试。

一句话总结：

• 不带 URI（http://www.zhujishice.cn）：原样转发，路径不变。
• 带 URI（http://www.zhujishice.cn/）：剪裁 location 匹配部分，替换为 upstream URI。

主要功能

• 直接拼接转发：不带 URI 时，将客户端原始 URI 原样追加到 upstream 地址后，保持请求路径不变。输入为客户端 URI，输出为完整上游路径。
• 替换拼接转发：带 URI 时，剪裁 location 匹配部分，将剩余路径拼接到 upstream 的 URI 后。输入为客户端 URI，输出为经过重写的上游路径。
• 透明代理支持：适用于反向代理场景，后端服务无需感知路径变化。输入为 HTTP 请求，输出为转发到上游的请求。
• 路径重写能力：通过带 URI 的配置，实现统一前缀添加或路径映射。输入为原始请求路径，输出为带前缀的新路径。
• location 匹配机制：基于字符串前缀匹配，决定是否对请求 URI 进行剪裁。输入为 location 配置，输出为匹配结果和剩余路径。
• 双斜杠处理：某些配置组合（如 location /aaa 配 proxy_pass http://www.zhujishice.cn/）会产生双斜杠，虽然能工作但不规范。输入为配置写法，输出为可能带双斜杠的转发路径。

使用说明

• 配置 proxy_pass：在 location 块内设置 proxy_pass 指令，指定 upstream 地址。
• 控制 URI 部分：决定是否在 upstream 地址后添加 URI 路径（如 / 或 /api）。
• 匹配 location：使用 location /prefix/ 或 location /prefix 定义匹配规则。
• 测试转发结果：通过浏览器或 curl 访问测试路径，观察实际转发地址。
• 调整结尾符：保持 location 和 proxy_pass 的结尾符一致，避免双斜杠或路径粘连。

同类竞品对比

应用场景

• 透明代理：后端服务无需感知路径变化，直接转发原始请求。
• 统一前缀添加：为所有请求添加统一路径前缀，如 /api。
• 路径重写：将客户端请求路径映射到后端服务的不同目录。
• 反向代理：将请求转发到内部服务器，隐藏后端细节。
• API 网关：通过路径规则分发请求到不同微服务。