問題現(xiàn)象

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

• 前端請(qǐng)求：http://your-domain.com/api/user/list
• Nginx 配置：看起來正確地將/api 路徑代理到了后端。
• 后端日志：卻顯示收到了 /user/list 的請(qǐng)求，缺少了 /api 前綴。
• 結(jié)果：后端因?yàn)闆]有/api 這個(gè)路由映射，返回 404 錯(cuò)誤。

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

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

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

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

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

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

請(qǐng)求轉(zhuǎn)換過程：

• 前端請(qǐng)求：GET /api/user/list
• Nginx 轉(zhuǎn)發(fā)給后端的請(qǐng)求：GET /api/user/list (發(fā)送到 http://localhost:8080/api/user/list)

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

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

當(dāng) proxy_pass 后面的地址包含以 / 結(jié)尾的路徑時(shí)，Nginx 會(huì)進(jìn)行 路徑替換：將location 匹配到的部分（即 /api/）從原始 URI 中刪除，然后將剩余部分拼接到代理目標(biāo)的路徑后面。

location /api/ {
    # 代理目標(biāo)帶路徑（以 / 結(jié)尾）
    proxy_pass http://localhost:8080/;
}

請(qǐng)求轉(zhuǎn)換過程：

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

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

解決方案與配置示例

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

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

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

server {
    listen 80;
    server_name your-domain.com;
    location /api/ {
        # 關(guān)鍵：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/ {
        # 關(guān)鍵：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指令進(jìn)行更靈活的重寫

如果路徑轉(zhuǎn)換邏輯更復(fù)雜（例如將/api/v1/ 重寫為/v1/），可以使用 rewrite 指令配合 break 標(biāo)記。

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

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

調(diào)試與驗(yàn)證技巧

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;

1. 檢查 Nginx 配置語法：運(yùn)行 nginx -t 確保配置無誤。
2. 查看 Nginx 訪問日志：在配置中添加或檢查訪問日志格式，確認(rèn) Nginx 收到的原始請(qǐng)求。
3. 查看后端應(yīng)用日志：確認(rèn)后端實(shí)際接收到的請(qǐng)求路徑。
4. 使用 curl 或?yàn)g覽器開發(fā)者工具：直接測試 API 端點(diǎn)，觀察請(qǐng)求和響應(yīng)。

總結(jié)

“前端帶/api 前綴而后端收不到”這個(gè)經(jīng)典問題的核心在于理解 Nginx proxy_pass 指令的路徑處理規(guī)則：

• proxy_pass http://backend-host; (無尾隨 /)：傳遞完整 URI。
• proxy_pass http://backend-host/; (有尾隨 /)：進(jìn)行路徑替換，去掉location 匹配的部分。

到此這篇關(guān)于Nginx 代理路徑重寫問題解析：為什么前端攜帶了 /api 前綴后端卻無法訪問的文章就介紹到這了,更多相關(guān)nginx 代理路徑重寫內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論