Vite項目Nginx子路徑部署全攻略

更新時間：2026年05月22日 10:09:44 作者：龔雋婭Percy

本文介紹了解決Vite項目部署到Nginx路徑后后后后頁面空白、資源加載失敗問題的方法,文中通過示例代碼介紹的非常詳細,對大家的學習或者工作具有一定的參考學習價值,需要的朋友們下面隨著小編來一起學習學習吧

1. Vite項目配置（核心步驟）

1.1 設置base路徑

打開項目根目錄的vite.config.js文件，添加base配置項指定子路徑名稱：

export default defineConfig({
  base: '/vite-app/',  // 子路徑名稱，必須以/開頭和結(jié)尾
  // 其他配置...
})

?? 注意：base值必須與Nginx配置中的location路徑完全一致。例如Nginx配置/app/，則此處必須設為/app/。

1.2 構(gòu)建生產(chǎn)版本

執(zhí)行構(gòu)建命令生成優(yōu)化后的靜態(tài)文件：

npm run build  # 構(gòu)建產(chǎn)物默認輸出到dist目錄

構(gòu)建完成后，檢查dist/index.html文件，確認所有資源引用路徑已自動加上/vite-app/前綴。

2. Nginx服務器配置

2.1 基礎配置模板

在Nginx配置文件（通常位于/etc/nginx/conf.d/目錄）中添加以下配置：

server {
    listen 80;
    server_name yourdomain.com;  # 替換為你的域名

    # 子路徑部署核心配置
    location /vite-app/ {
        alias /path/to/your/vite/dist/;  # 替換為實際dist目錄絕對路徑
        try_files $uri $uri/ /vite-app/index.html;  # 解決SPA路由刷新404問題
        
        # 緩存控制 - 靜態(tài)資源長期緩存
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
            expires 30d;
            add_header Cache-Control "public, max-age=2592000";
        }
    }
}

2.2 配置說明

參數(shù)	作用	示例值
location /vite-app/	匹配子路徑請求	/admin/或/portal/
alias	指定靜態(tài)文件目錄	/var/www/vite-app/dist/
try_files	實現(xiàn)SPA路由重定向	$uri $uri/ /vite-app/index.html

配置完成后，執(zhí)行以下命令使配置生效：

nginx -t  # 測試配置是否有誤
systemctl reload nginx  # 平滑重啟Nginx

3. 部署驗證與故障排除

3.1 基本訪問測試

在瀏覽器中訪問 http://yourdomain.com/vite-app/，驗證：

首頁是否正常加載
點擊導航后URL是否顯示為 /vite-app/about 格式
刷新頁面是否仍能正常顯示

3.2 常見問題解決方案

問題1：靜態(tài)資源404錯誤

原因：Vite構(gòu)建的資源路徑與Nginx配置不匹配
解決：檢查vite.config.js中的base值是否與Nginx的location路徑完全一致

問題2：路由刷新后404

原因：Nginx未配置SPA路由重定向
解決：確保try_files指令正確設置為 $uri $uri/ /vite-app/index.html

問題3：CSS/JS加載跨域

原因：Nginx未正確配置CORS頭
解決：在location塊中添加：

add_header Access-Control-Allow-Origin *;

4. 高級優(yōu)化配置

4.1 啟用Gzip壓縮

在Nginx配置中添加壓縮配置，減少傳輸體積：

gzip on;
gzip_types text/css application/javascript image/svg+xml;
gzip_min_length 1k;
gzip_comp_level 6;

4.2 配置HTTPS（推薦）

通過Let's Encrypt獲取免費SSL證書后，配置HTTPS：

server {
    listen 443 ssl;
    server_name yourdomain.com;
    
    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
    
    # 其他SSL配置...
    
    location /vite-app/ {
        # 同上配置...
    }
}