1. 從本地開發(fā)到“偽上線”為什么我們需要Nginx代理做前端或者全棧開發(fā)的朋友肯定都經(jīng)歷過(guò)這個(gè)階段本地項(xiàng)目跑得好好的前后端聯(lián)調(diào)也通了但一到部署或者需要模擬線上環(huán)境測(cè)試時(shí)就各種幺蛾子。最常見的就是跨域問(wèn)題瀏覽器那個(gè)紅色的CORS錯(cuò)誤簡(jiǎn)直是開發(fā)者的“老朋友”。另一個(gè)頭疼的問(wèn)題是本地開發(fā)服務(wù)器比如Vite、Webpack Dev Server的端口和線上服務(wù)的端口、路徑往往不一致導(dǎo)致代碼里一堆環(huán)境判斷既難看又容易出錯(cuò)。這時(shí)候一個(gè)在本地運(yùn)行的Nginx就能成為你的“環(huán)境魔術(shù)師”。它不是什么高深莫測(cè)的運(yùn)維專屬工具對(duì)于開發(fā)者而言把它理解成一個(gè)非常智能的“請(qǐng)求轉(zhuǎn)發(fā)員”和“靜態(tài)文件服務(wù)員”就足夠了。通過(guò)在本地配置Nginx你可以輕松實(shí)現(xiàn)解決跨域問(wèn)題讓Nginx作為中間層將前端頁(yè)面對(duì)后端API的請(qǐng)求“偽裝”成同源請(qǐng)求瀏覽器自然就放行了。統(tǒng)一訪問(wèn)入口無(wú)論你本地跑了多少個(gè)服務(wù)前端、后端API、Mock服務(wù)、文檔站點(diǎn)都可以通過(guò)同一個(gè)域名和端口如localhost:80來(lái)訪問(wèn)路徑通過(guò)Nginx規(guī)則來(lái)分發(fā)極大簡(jiǎn)化了訪問(wèn)和配置。模擬生產(chǎn)環(huán)境生產(chǎn)環(huán)境通常也是Nginx或類似網(wǎng)關(guān)在后端服務(wù)前做代理。本地使用相同的代理配置可以提前發(fā)現(xiàn)路由、靜態(tài)資源路徑等配置問(wèn)題避免上了生產(chǎn)再踩坑。負(fù)載均衡與健康檢查本地進(jìn)階如果你在本地同時(shí)啟動(dòng)多個(gè)后端實(shí)例用于測(cè)試Nginx甚至可以配置簡(jiǎn)單的負(fù)載均衡幫你驗(yàn)證相關(guān)邏輯。簡(jiǎn)單說(shuō)在本地配Nginx不是為了炫技而是為了創(chuàng)造一個(gè)更接近真實(shí)、更少麻煩的開發(fā)調(diào)試環(huán)境。接下來(lái)我就以一個(gè)典型的Vue/React前端項(xiàng)目對(duì)接Spring Boot后端API的場(chǎng)景為例手把手帶你走通從安裝、配置到調(diào)試的完整流程并分享幾個(gè)我踩過(guò)坑才總結(jié)出來(lái)的關(guān)鍵技巧。2. 環(huán)境準(zhǔn)備不是簡(jiǎn)單安裝就完事很多人覺得安裝Nginx就是去官網(wǎng)下載、解壓、運(yùn)行但對(duì)于本地開發(fā)配置有一些細(xì)節(jié)決定了你后續(xù)是順風(fēng)順?biāo)€是焦頭爛額。2.1 獲取NginxWindows/macOS/Linux的差異選擇首先忘掉那些復(fù)雜的源碼編譯。對(duì)于本地開發(fā)我們追求的是快速可用。Windows直接去 Nginx官網(wǎng) 下載Stable version的Windows zip包比如nginx-1.24.0.zip。解壓到任意目錄例如D:\nginx-1.24.0。這就是你的Nginx根目錄了。重要提示路徑中最好不要有中文或空格避免一些不必要的權(quán)限或識(shí)別問(wèn)題。macOS強(qiáng)烈推薦使用Homebrew安裝一行命令搞定后續(xù)管理也方便。brew install nginx安裝后配置文件通常位于/usr/local/etc/nginx/nginx.conf靜態(tài)文件默認(rèn)目錄是/usr/local/var/www。Linux (Ubuntu/Debian)使用apt包管理器安裝。sudo apt update sudo apt install nginx安裝后配置文件通常在/etc/nginx/nginx.conf站點(diǎn)配置在/etc/nginx/sites-available/和/etc/nginx/sites-enabled/。我的經(jīng)驗(yàn)之談在Windows上我更喜歡把它放在非系統(tǒng)盤如D盤的根目錄或一個(gè)清晰的DevTools文件夾下。因?yàn)槟阈枰?jīng)常修改配置、查看日志一個(gè)干凈的路徑會(huì)讓你在命令行里操作起來(lái)更順手。另外把Nginx的根目錄比如D:\nginx-1.24.0添加到系統(tǒng)的PATH環(huán)境變量里這樣你就可以在任意命令行窗口直接用nginx命令了非常方便。2.2 驗(yàn)證安裝與基本操作命令安裝或解壓后打開命令行Windows用CMD或PowerShellmacOS/Linux用Terminal進(jìn)入Nginx的根目錄Windows下是包含nginx.exe的目錄macOS/Linux因?yàn)橐言赑ATH中任意目錄即可。啟動(dòng)Nginx:# Windows (在nginx.exe所在目錄) start nginx # 或直接雙擊nginx.exe不推薦看不到日志輸出 # macOS/Linux sudo nginx # 如果brew安裝且不想用sudo需要調(diào)整權(quán)限或使用brew services brew services start nginx驗(yàn)證是否啟動(dòng)成功 打開瀏覽器訪問(wèn)http://localhost。如果看到“Welcome to nginx!”的頁(yè)面恭喜你第一步成功了。常用命令# 重新加載配置修改配置文件后必用無(wú)需重啟進(jìn)程 nginx -s reload # 優(yōu)雅停止處理完已連接請(qǐng)求后再停止 nginx -s quit # 快速停止 nginx -s stop # 測(cè)試配置文件語(yǔ)法是否正確修改配置前先測(cè)試好習(xí)慣 nginx -t注意在Windows上如果你用start nginx啟動(dòng)后續(xù)的-s信號(hào)命令需要在同一個(gè)命令行窗口或另一個(gè)命令行中進(jìn)入Nginx目錄執(zhí)行。nginx -s reload是你開發(fā)過(guò)程中最常用的命令沒有之一。2.3 理解核心目錄結(jié)構(gòu)以Windows解壓版為例了解這幾個(gè)關(guān)鍵目錄和文件后面配置才不會(huì)迷路nginx-1.24.0/ ├── conf/ # 配置目錄 │ ├── nginx.conf # **主配置文件我們的主戰(zhàn)場(chǎng)** │ └── ... (其他配置模板) ├── html/ # 默認(rèn)的靜態(tài)資源目錄 │ ├── 50x.html # 錯(cuò)誤頁(yè)面 │ └── index.html # 你剛才看到的歡迎頁(yè) ├── logs/ # **日志目錄查錯(cuò)救命稻草** │ ├── access.log # 訪問(wèn)日志誰(shuí)什么時(shí)候訪問(wèn)了什么 │ └── error.log # **錯(cuò)誤日志出問(wèn)題了第一時(shí)間看這里** └── nginx.exe # 主程序核心心法nginx.conf是大腦logs/error.log是體檢報(bào)告。任何配置不生效、服務(wù)報(bào)錯(cuò)請(qǐng)第一時(shí)間打開error.log文件查看線索。在Windows下你可以用文本編輯器打開它或者在命令行用tail -f logs/error.log如果安裝了相關(guān)工具實(shí)時(shí)查看。3. 核心配置解剖手寫一個(gè)本地代理規(guī)則默認(rèn)的nginx.conf文件內(nèi)容較多我們不需要全部搞懂。聚焦于http塊內(nèi)的server塊這是我們定義單個(gè)“網(wǎng)站”或“服務(wù)”的地方。我會(huì)先給出一個(gè)最簡(jiǎn)化的、針對(duì)本地開發(fā)場(chǎng)景的配置然后逐行拆解。假設(shè)你的項(xiàng)目結(jié)構(gòu)如下前端項(xiàng)目運(yùn)行在http://localhost:5173(Vite默認(rèn)端口)后端API項(xiàng)目運(yùn)行在http://localhost:8080(Spring Boot默認(rèn)端口)我們的目標(biāo)是訪問(wèn)http://localhost看到前端頁(yè)面并且前端頁(yè)面內(nèi)所有以/api/開頭的請(qǐng)求都被Nginx轉(zhuǎn)發(fā)到后端的http://localhost:8080。3.1 最小可行配置示例打開conf/nginx.conf文件找到http塊。我們可以在末尾的include servers/*;這行之前或者直接在里面添加一個(gè)新的server塊。為了清晰我建議先注釋掉默認(rèn)的server塊監(jiān)聽80端口返回歡迎頁(yè)的那個(gè)然后寫上我們自己的http { # ... 其他原有配置如worker_processes, events等保持不變 ... server { # 監(jiān)聽80端口這是HTTP默認(rèn)端口所以瀏覽器訪問(wèn)localhost即可 listen 80; # 服務(wù)器名稱本地開發(fā)寫localhost或127.0.0.1都行 server_name localhost; # 核心配置location 塊用于匹配特定的請(qǐng)求路徑 # 匹配根路徑 /將請(qǐng)求代理到前端開發(fā)服務(wù)器 location / { # proxy_pass 指令是代理的核心后面跟目標(biāo)服務(wù)器的地址 proxy_pass http://localhost:5173; # 以下是一些非常重要的代理頭設(shè)置用于正確傳遞原始請(qǐng)求信息 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/ 開頭的所有請(qǐng)求代理到后端API服務(wù)器 location /api/ { proxy_pass http://localhost:8080/; # 注意這里的結(jié)尾斜杠 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; # 針對(duì)API接口常常需要處理OPTIONS預(yù)檢請(qǐng)求CORS # 如果你的后端已經(jīng)正確配置了CORS下面這段可以不加 # 但如果后端沒配或配置復(fù)雜可以在Nginx層統(tǒng)一處理 if ($request_method OPTIONS) { add_header Access-Control-Allow-Origin *; add_header Access-Control-Allow-Methods GET, POST, OPTIONS, PUT, DELETE; add_header Access-Control-Allow-Headers DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization; add_header Access-Control-Max-Age 1728000; add_header Content-Type text/plain; charsetutf-8; add_header Content-Length 0; return 204; } } # 錯(cuò)誤頁(yè)面配置可選但建議保留用于調(diào)試 error_page 500 502 503 504 /50x.html; location /50x.html { root html; } } }3.2 關(guān)鍵指令深度解讀listen 80;這行告訴Nginx監(jiān)聽本機(jī)localhost的80端口。當(dāng)你在瀏覽器輸入http://localhost時(shí)請(qǐng)求就會(huì)到達(dá)這里。如果你想用其他端口比如8081就改成listen 8081;訪問(wèn)時(shí)就要用http://localhost:8081。location [匹配模式] { ... }這是Nginx配置的靈魂。它根據(jù)請(qǐng)求的URI路徑來(lái)決定如何處理請(qǐng)求。location /這是前綴匹配匹配所有請(qǐng)求。因?yàn)樗亲钔ㄓ玫钠ヅ渫ǔ７旁谧詈蟮谶@個(gè)簡(jiǎn)單配置里順序影響不大只要沒有更具體的沖突。我們把所有非API的請(qǐng)求如請(qǐng)求HTML、JS、CSS、圖片都代理到前端服務(wù)器。location /api/這也是前綴匹配但只匹配以/api/開頭的請(qǐng)求。例如/api/user/login、/api/data/list都會(huì)進(jìn)入這個(gè)塊。proxy_pass http://...;代理轉(zhuǎn)發(fā)指令。這里有一個(gè)超級(jí)重要的細(xì)節(jié)proxy_pass http://localhost:8080;結(jié)尾沒有斜杠當(dāng)請(qǐng)求/api/user到來(lái)時(shí)Nginx會(huì)將其轉(zhuǎn)發(fā)為http://localhost:8080/api/user。它只是替換了協(xié)議、主機(jī)和端口路徑部分原樣附加。proxy_pass http://localhost:8080/;結(jié)尾有斜杠當(dāng)請(qǐng)求/api/user到來(lái)時(shí)Nginx會(huì)將其轉(zhuǎn)發(fā)為http://localhost:8080/user。它把匹配到的/api/前綴從請(qǐng)求路徑中移除了。如何選擇這取決于你的后端API路徑設(shè)計(jì)。如果你的后端接口本來(lái)就是以/api開頭比如RequestMapping(“/api/user”)那么你應(yīng)該用沒有斜杠的版本讓路徑完整傳遞。如果你的后端接口根路徑就是/你希望Nginx幫你“吃掉”/api這個(gè)前綴那么就用有斜杠的版本。我上面配置中用了有斜杠的這是一種常見的“路徑重寫”做法讓前端代碼統(tǒng)一用/api前綴而后端實(shí)際接收干凈的路徑。proxy_set_header這組指令至關(guān)重要。它修改或添加Nginx轉(zhuǎn)發(fā)給后端服務(wù)器的HTTP請(qǐng)求頭。Host $host;將原始請(qǐng)求的Host頭這里是localhost傳遞給后端。有些后端框架如Spring Security OAuth2會(huì)校驗(yàn)這個(gè)頭。X-Real-IP $remote_addr;和X-Forwarded-For $proxy_add_x_forwarded_for;將客戶端的真實(shí)IP地址傳遞給后端。否則在后端日志里所有請(qǐng)求的IP都會(huì)是Nginx服務(wù)器的IP127.0.0.1不利于審計(jì)和排查。X-Forwarded-Proto $scheme;告訴后端原始的請(qǐng)求協(xié)議是http還是https。如果你的應(yīng)用需要生成絕對(duì)URL比如重定向這個(gè)信息就非常關(guān)鍵。關(guān)于CORS的處理我在location /api/塊里寫了一段處理OPTIONS預(yù)檢請(qǐng)求的配置。這是一種“偷懶”但有效的辦法。原理是當(dāng)瀏覽器發(fā)送跨域請(qǐng)求尤其是帶自定義頭的POST請(qǐng)求前會(huì)先發(fā)一個(gè)OPTIONS請(qǐng)求來(lái)詢問(wèn)服務(wù)器是否允許。Nginx如果直接把這個(gè)OPTIONS請(qǐng)求代理到后端后端必須能正確處理并返回正確的CORS頭。如果后端配置麻煩我們可以讓Nginx直接攔截OPTIONS請(qǐng)求并返回允許跨域的響應(yīng)。注意add_header ‘Access-Control-Allow-Origin’ ‘*’;這里的*表示允許任何來(lái)源在生產(chǎn)環(huán)境中這是極不安全的應(yīng)該替換為具體的前端域名。本地開發(fā)為了方便可以先用*。4. 實(shí)戰(zhàn)演練讓配置跑起來(lái)并驗(yàn)證紙上得來(lái)終覺淺絕知此事要躬行。配置寫好了我們得讓它真正工作起來(lái)。4.1 啟動(dòng)服務(wù)與加載配置確保后端和前端服務(wù)已啟動(dòng)分別啟動(dòng)你的Spring Boot應(yīng)用在8080端口和Vite開發(fā)服務(wù)器在5173端口。測(cè)試Nginx配置語(yǔ)法在Nginx根目錄下的命令行執(zhí)行nginx -t如果顯示syntax is ok和test is successful說(shuō)明配置文件沒有語(yǔ)法錯(cuò)誤。首次啟動(dòng)或重新加載Nginx如果是第一次執(zhí)行start nginx(Windows) 或sudo nginx(macOS/Linux)。如果Nginx已經(jīng)在運(yùn)行比如之前測(cè)試歡迎頁(yè)執(zhí)行nginx -s reload來(lái)重新加載配置。這是最安全的做法避免重啟導(dǎo)致現(xiàn)有連接中斷。4.2 逐項(xiàng)驗(yàn)證代理是否生效不要想當(dāng)然一步一步驗(yàn)證每個(gè)環(huán)節(jié)。驗(yàn)證根路徑代理前端打開瀏覽器訪問(wèn)http://localhost。預(yù)期你應(yīng)該看到你的前端應(yīng)用頁(yè)面而不是Nginx的歡迎頁(yè)。查看瀏覽器開發(fā)者工具的“網(wǎng)絡(luò)”(Network)標(biāo)簽加載的JS、CSS資源應(yīng)該來(lái)源于localhost被代理了而不是直接的localhost:5173。可能的問(wèn)題如果看到歡迎頁(yè)說(shuō)明你的server塊沒生效或者默認(rèn)的server塊還在監(jiān)聽80端口。檢查nginx.conf確保你的server塊配置正確并且沒有其他server塊也在監(jiān)聽80端口?？梢詴簳r(shí)注釋掉其他所有server塊再測(cè)試。驗(yàn)證API路徑代理后端在瀏覽器地址欄直接訪問(wèn)一個(gè)后端API比如http://localhost/api/假設(shè)你后端有根路徑接口或http://localhost/api/user/1。預(yù)期你應(yīng)該看到后端返回的JSON數(shù)據(jù)或頁(yè)面。這證明/api/路徑的代理成功了。更專業(yè)的驗(yàn)證使用Postman或curl命令直接向http://localhost/api/xxx發(fā)送請(qǐng)求查看響應(yīng)是否與直接訪問(wèn)http://localhost:8080/xxx一致。curl http://localhost/api/your-endpoint驗(yàn)證前端應(yīng)用內(nèi)的API調(diào)用在你的前端頁(yè)面中執(zhí)行一個(gè)會(huì)調(diào)用/api/xxx接口的操作比如點(diǎn)擊登錄按鈕。打開瀏覽器開發(fā)者工具的“網(wǎng)絡(luò)”標(biāo)簽找到這個(gè)API請(qǐng)求。檢查關(guān)鍵項(xiàng)請(qǐng)求URL應(yīng)該是http://localhost/api/xxx而不是http://localhost:5173/api/xxx或http://localhost:8080/xxx。這說(shuō)明前端代碼里的請(qǐng)求基址配置正確通常Vite里可以配置proxy但我們現(xiàn)在用Nginx前端代碼里的API基址直接寫成/api或http://localhost/api即可。響應(yīng)狀態(tài)應(yīng)該是200或預(yù)期的狀態(tài)碼而不是404或跨域錯(cuò)誤。Response Headers可以看看有沒有Access-Control-Allow-Origin等CORS頭如果你在Nginx或后端配置了的話。4.3 排查問(wèn)題的黃金通道日志分析當(dāng)事情不按預(yù)期發(fā)展時(shí)不要慌張日志是你的第一手資料。查看Nginx錯(cuò)誤日志打開logs/error.log文件。任何配置錯(cuò)誤、權(quán)限問(wèn)題、連接失敗都會(huì)記錄在這里。常見的錯(cuò)誤有connect() failed (10061: No connection could be made because the target machine actively refused it)這意味著Nginx無(wú)法連接到proxy_pass指定的后端服務(wù)器localhost:8080或localhost:5173。請(qǐng)檢查你的前端或后端服務(wù)是否真的已經(jīng)啟動(dòng)并且端口正確。invalid parameter “proxy_set_header”可能是拼寫錯(cuò)誤或者指令寫在了錯(cuò)誤的上下文中比如寫在了http塊外面。permission denied while connecting to upstream在某些系統(tǒng)如Linux上Nginx工作進(jìn)程可能沒有權(quán)限連接到某個(gè)端口?？赡苄枰{(diào)整權(quán)限或以更高權(quán)限運(yùn)行。查看Nginx訪問(wèn)日志打開logs/access.log。這里記錄了所有經(jīng)過(guò)Nginx的請(qǐng)求格式類似127.0.0.1 - - [01/Apr/2024:15:30:00 0800] GET /api/user HTTP/1.1 200 356 - Mozilla/5.0 ...你可以看到客戶端IP、請(qǐng)求時(shí)間、方法、路徑、狀態(tài)碼、響應(yīng)大小等信息。通過(guò)這個(gè)日志你可以確認(rèn)請(qǐng)求是否到達(dá)了Nginx以及Nginx返回了什么狀態(tài)碼。如果狀態(tài)碼是502 Bad Gateway或504 Gateway Timeout說(shuō)明Nginx與上游服務(wù)器你的后端通信出了問(wèn)題。5. 進(jìn)階配置與本地開發(fā)實(shí)用技巧基礎(chǔ)代理跑通后我們可以玩點(diǎn)更花的讓本地開發(fā)環(huán)境更加強(qiáng)大和逼真。5.1 靜態(tài)文件服務(wù)與前端構(gòu)建產(chǎn)物代理之前我們把/代理到了前端開發(fā)服務(wù)器。但有時(shí)候我們想測(cè)試構(gòu)建后的產(chǎn)物比如npm run build生成的dist目錄在生產(chǎn)環(huán)境下的表現(xiàn)。你可以配置一個(gè)特定的路徑或端口來(lái)服務(wù)這些靜態(tài)文件。在nginx.conf里再添加一個(gè)server塊server { listen 8088; # 用一個(gè)不同的端口避免沖突 server_name localhost; # 指定靜態(tài)文件根目錄這里假設(shè)你的前端構(gòu)建產(chǎn)物在 D:/projects/my-app/dist root D:/projects/my-app/dist; index index.html index.htm; # 單頁(yè)應(yīng)用(SPA)路由支持所有非文件請(qǐng)求都返回index.html location / { try_files $uri $uri/ /index.html; } # 可以單獨(dú)代理API也可以不配讓前端代碼直接請(qǐng)求原來(lái)的代理地址localhost/api # location /api/ { # proxy_pass http://localhost:8080/; # ... proxy_set_header 等配置同上 # } }這樣訪問(wèn)http://localhost:8088就能直接看到構(gòu)建后的前端頁(yè)面完全模擬了靜態(tài)資源托管在Nginx下的生產(chǎn)環(huán)境。5.2 路徑重寫Rewrite的妙用proxy_pass結(jié)尾的斜杠是一種簡(jiǎn)單的路徑“修剪”。更復(fù)雜的路徑轉(zhuǎn)換需要使用rewrite指令。例如你的老接口路徑是/v1/old-api但前端想統(tǒng)一用/api前綴而后端暫時(shí)無(wú)法修改。location /api/ { # 先將 /api/xxx 重寫為 /v1/old-api/xxx rewrite ^/api/(.*)$ /v1/old-api/$1 break; # 然后將重寫后的請(qǐng)求代理到后端 proxy_pass http://localhost:8080; # ... 其他頭設(shè)置 }rewrite指令非常強(qiáng)大它使用正則表達(dá)式匹配和替換。break標(biāo)志表示重寫后就在當(dāng)前l(fā)ocation塊內(nèi)停止處理其他重寫規(guī)則。5.3 負(fù)載均衡測(cè)試本地多實(shí)例模擬想測(cè)試負(fù)載均衡或服務(wù)高可用在本地啟動(dòng)兩個(gè)或多個(gè)后端實(shí)例比如分別在8080和8081端口然后用Nginx的upstream模塊輕松實(shí)現(xiàn)。http { # 定義一個(gè)名為 backend_servers 的上游服務(wù)器組 upstream backend_servers { server localhost:8080 weight3; # 權(quán)重3接收更多請(qǐng)求 server localhost:8081 weight1; # 還可以配置 backup備份服務(wù)器、max_fails失敗次數(shù)等參數(shù) } server { listen 80; server_name localhost; location / { proxy_pass http://localhost:5173; # ... 頭設(shè)置 } location /api/ { # 代理到上游服務(wù)器組默認(rèn)使用輪詢(weighted round-robin)算法 proxy_pass http://backend_servers/; proxy_set_header Host $host; # ... 其他頭設(shè)置 } } }配置好后重啟Nginx。此時(shí)你訪問(wèn)/api/下的接口請(qǐng)求會(huì)按3:1的比例分發(fā)到8080和8081端口。你可以通過(guò)在后端日志打印不同標(biāo)識(shí)來(lái)驗(yàn)證。5.4 緩存控制與開發(fā)環(huán)境在開發(fā)階段我們通常不希望任何緩存以確保每次都能拿到最新的代碼和接口數(shù)據(jù)?？梢栽诖盱o態(tài)資源和API時(shí)禁用緩存location / { proxy_pass http://localhost:5173; # 禁用代理緩存 proxy_cache off; proxy_buffering off; # 設(shè)置請(qǐng)求頭告訴瀏覽器不要緩存 add_header Cache-Control no-cache, no-store, must-revalidate; add_header Pragma no-cache; add_header Expires 0; # ... 其他 proxy_set_header } location /api/ { proxy_pass http://localhost:8080/; # 同樣禁用API響應(yīng)緩存 proxy_cache off; proxy_buffering off; # 對(duì)于API通常也建議瀏覽器不緩存 add_header Cache-Control no-cache, no-store, must-revalidate; # ... 其他 proxy_set_header }6. 我踩過(guò)的那些坑與避坑指南配置Nginx的過(guò)程很少一帆風(fēng)順下面是我總結(jié)的幾個(gè)典型坑點(diǎn)希望能幫你節(jié)省時(shí)間?？右籶roxy_pass結(jié)尾斜杠的“魔法”這個(gè)問(wèn)題前面提過(guò)但值得再?gòu)?qiáng)調(diào)一遍。這是新手最容易困惑和出錯(cuò)的地方。規(guī)則很簡(jiǎn)單proxy_pass后面的URL如果包含路徑即使是根路徑/那么匹配到的location路徑部分會(huì)被替換掉。如果不包含路徑則原樣追加。寫配置時(shí)一定要想清楚你希望轉(zhuǎn)發(fā)后的最終URL是什么然后用curl或?yàn)g覽器先測(cè)試一下?？佣渲眯薷暮蟛簧愀牧薾ginx.conf執(zhí)行了nginx -s reload但瀏覽器訪問(wèn)還是老樣子?？赡艿脑?yàn)g覽器緩存這是最常見的“元兇”務(wù)必打開開發(fā)者工具勾選“Disable cache”停用緩存或者直接CtrlF5/CmdShiftR強(qiáng)制刷新。配置文件語(yǔ)法錯(cuò)誤nginx -s reload在配置有語(yǔ)法錯(cuò)誤時(shí)會(huì)失敗但進(jìn)程可能還在運(yùn)行舊的配置。務(wù)必先執(zhí)行nginx -t測(cè)試語(yǔ)法。錯(cuò)誤的server塊或location塊可能有多個(gè)server塊都監(jiān)聽80端口Nginx會(huì)選擇server_name匹配的一個(gè)。確保你的配置在正確的上下文中。reload信號(hào)未送達(dá)在Windows上如果你開了多個(gè)命令行窗口確保nginx -s reload是在能識(shí)別到Nginx進(jìn)程的環(huán)境下執(zhí)行的。有時(shí)直接去任務(wù)管理器結(jié)束nginx.exe進(jìn)程再重啟更干脆?？尤龣?quán)限問(wèn)題多見于Linux/macOS在非Windows系統(tǒng)上如果Nginx以root啟動(dòng)工作進(jìn)程worker_processes可能會(huì)降權(quán)到nginx或www-data用戶。這個(gè)用戶可能沒有權(quán)限讀取你的前端文件目錄或者連接到某些高于1024的端口。解決方案檢查Nginx主進(jìn)程和工作進(jìn)程的運(yùn)行用戶ps aux | grep nginx。確保你的項(xiàng)目目錄對(duì)該用戶有讀取和執(zhí)行權(quán)限chmod -R 755 /your/project?；蛘咴趎ginx.conf的頂部用user your_username;指令指定運(yùn)行用戶需有相應(yīng)權(quán)限。坑四 upstream 服務(wù)器健康檢查與超時(shí)在配置了upstream做負(fù)載均衡時(shí)如果某個(gè)后端服務(wù)掛了Nginx默認(rèn)還會(huì)嘗試向它轉(zhuǎn)發(fā)請(qǐng)求導(dǎo)致部分請(qǐng)求失敗?？梢耘渲酶训?upstreamupstream backend_servers { server localhost:8080 max_fails3 fail_timeout30s; server localhost:8081 max_fails3 fail_timeout30s; }max_fails3表示在fail_timeout時(shí)間內(nèi)失敗3次則將該服務(wù)器標(biāo)記為不可用在接下來(lái)的30秒內(nèi)不再向其分發(fā)請(qǐng)求?？游?413 Request Entity Too Large當(dāng)你調(diào)試文件上傳功能時(shí)可能會(huì)遇到這個(gè)錯(cuò)誤。這是因?yàn)镹ginx默認(rèn)限制客戶端請(qǐng)求體大小為1MB。需要在http、server或location塊中調(diào)整client_max_body_size 20m; # 設(shè)置為20MB根據(jù)你的需要調(diào)整本地項(xiàng)目配置Nginx代理本質(zhì)上是在你的開發(fā)機(jī)器上搭建了一個(gè)微型的、可控的網(wǎng)關(guān)環(huán)境。它不僅能解決眼前的跨域和路徑問(wèn)題更能讓你提前感知生產(chǎn)環(huán)境的配置邏輯。從最簡(jiǎn)單的單服務(wù)代理到靜態(tài)文件服務(wù)、路徑重寫、負(fù)載均衡模擬每一步的實(shí)踐都會(huì)加深你對(duì)網(wǎng)絡(luò)請(qǐng)求流程和服務(wù)器協(xié)作的理解。下次當(dāng)你再遇到環(huán)境問(wèn)題時(shí)不妨先想想能不能用Nginx在本地搭個(gè)橋很多時(shí)候答案都是肯定的。