Nginx?代理路徑重寫問題解析：為什么前端攜帶了?/api?前綴后端卻無法訪問

更新時間：2026年07月23日 09:17:54 作者：貓貓不是喵喵.

在使用Nginx作為反向代理服務器時,經(jīng)常會遇到需要重寫請求路徑的情況,本文給大家介紹Nginx代理路徑重寫問題解析：為什么前端攜帶了?/api?前綴后端卻無法訪問,感興趣的朋友一起看看吧

問題現(xiàn)象

在前后端分離的 Web 項目中，我們經(jīng)常使用 Nginx 作為反向代理服務器。一個典型的配置場景是：前端頁面通過 /api 前綴將請求發(fā)送給 Nginx，期望 Nginx 將這些請求代理到后端服務（例如運行在 http://localhost:8080 的 Spring Boot 應用）。然而，開發(fā)者常常會遇到一個令人困惑的問題：

前端請求：http://your-domain.com/api/user/list
Nginx 配置：看起來正確地將/api 路徑代理到了后端。
后端日志：卻顯示收到了 /user/list 的請求，缺少了 /api 前綴。
結果：后端因為沒有/api 這個路由映射，返回 404 錯誤。

為什么前端明明攜帶了 /api 前綴，經(jīng)過 Nginx 代理后，后端收到的請求卻沒有這個前綴了呢？

核心原因：proxy_pass指令的路徑處理規(guī)則

問題的根源在于 Nginx proxy_pass 指令對 URI 的處理方式。其行為取決于 proxy_pass 后跟的代理目標地址是否包含路徑部分。

規(guī)則一：代理目標地址不帶路徑

當proxy_pass 后面的地址只有協(xié)議://主機:端口，沒有以 / 結尾的路徑時，Nginx 會將客戶端請求的原始 URI（包含 /api 前綴）完整地傳遞給后端。

location /api/ {
    # 代理目標不帶路徑
    proxy_pass http://localhost:8080;
}

請求轉換過程：

前端請求：GET /api/user/list
Nginx 轉發(fā)給后端的請求：GET /api/user/list (發(fā)送到 http://localhost:8080/api/user/list)

這種情況下，后端需要能處理/api/user/list 這個路徑。

規(guī)則二：代理目標地址帶路徑

當 proxy_pass 后面的地址包含以 / 結尾的路徑時，Nginx 會進行路徑替換：將location 匹配到的部分（即 /api/）從原始 URI 中刪除，然后將剩余部分拼接到代理目標的路徑后面。

location /api/ {
    # 代理目標帶路徑（以 / 結尾）
    proxy_pass http://localhost:8080/;
}

請求轉換過程：

前端請求：GET /api/user/list
location /api/ 匹配到 /api/
Nginx 將其刪除，剩余 /user/list
拼接到代理目標路徑 / 后面：/user/list
Nginx 轉發(fā)給后端的請求：GET /user/list (發(fā)送到 http://localhost:8080/user/list)

這正是大多數(shù)問題出現(xiàn)的原因！開發(fā)者本意是想把請求代理到后端根路徑，但無意中在 proxy_pass 地址末尾加了一個 /，導致了路徑被“吃掉”。

解決方案與配置示例

根據(jù)你的后端路由設計，選擇以下一種配置方式。

方案一：后端需要完整路徑（包含 /api 前綴）

如果你的后端控制器統(tǒng)一配置了 @RequestMapping("/api") 或類似前綴，你需要讓 Nginx 保留 /api 前綴。

server {
    listen 80;
    server_name your-domain.com;
    location /api/ {
        # 關鍵：proxy_pass 地址末尾不要加 /
        proxy_pass http://localhost: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;
    }
}

方案二：后端不需要 /api 前綴（更常見）

如果你的后端路由直接從根路徑開始（例如 @GetMapping("/user/list")），你希望 Nginx 去掉 /api 前綴。

server {
    listen 80;
    server_name your-domain.com;
    location /api/ {
        # 關鍵：proxy_pass 地址末尾加上 /
        proxy_pass http://localhost: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;
    }
}

方案三：使用rewrite指令進行更靈活的重寫

如果路徑轉換邏輯更復雜（例如將/api/v1/ 重寫為/v1/），可以使用 rewrite 指令配合 break 標記。

location /api/ {
    # 去掉 /api 前綴，保留其他部分
    rewrite ^/api/(.*)$ /$1 break;
    proxy_pass http://localhost:8080;
    proxy_set_header Host $host;
    # ... 其他頭
}

break 標記表示重寫后的 URI 在當前 location 內不再匹配其他 rewrite 規(guī)則，并直接用于 proxy_pass。

調試與驗證技巧

log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                '$status $body_bytes_sent "$http_referer" '
                '"$http_user_agent" "$http_x_forwarded_for"';
access_log /var/log/nginx/access.log main;