癥狀：Vue 單頁應用（SPA）首次進入頁面正常，一刷新就白屏或 404。

一、問題現(xiàn)象

• 訪問 http://your-server/dashboard/home → 正常
• 在該頁面按 F5 / Ctrl+R 刷新 → 白屏，控制臺報大量 404
• 瀏覽器地址欄 URL 沒變，但頁面什么都加載不出來

二、問題本質：兩個獨立原因疊加

刷新白屏這個現(xiàn)象，背后其實有兩個完全不同的原因，必須同時解決，缺一不可。

原因一：Nginx 不認識 Vue Router 的路由路徑（基礎原因）

Vue Router 使用 HTML5 History 模式（createWebHistory）時，/dashboard/home 這類路徑是純前端路由，不對應任何真實文件。

首次進入為什么正常？

用戶從首頁 / 進入應用，Nginx 找到真實的 index.html 并返回，Vue 的 JS 運行后，Vue Router 接管所有導航。用戶點擊菜單跳轉到 /dashboard/home，這是 Vue Router 通過瀏覽器 History.pushState() 完成的，根本沒有向服務器發(fā)送任何 HTTP 請求，所以正常。

刷新為什么失??？

刷新時瀏覽器向服務器發(fā)出真實的 HTTP 請求：GET /dashboard/home。Nginx 在硬盤上找不到對應的文件，于是返回 404。

瀏覽器刷新  →  HTTP GET /dashboard/home  →  Nginx 找文件  →  找不到  →  404

Nginx 修復方式：配置 try_files，當找不到文件時，統(tǒng)一回退到 index.html，讓 Vue Router 接管路由判斷。

location / {
    root /home/your-app/dist;
    index index.html;
    try_files $uri $uri/ /index.html;   # 關鍵：找不到文件就返回 index.html
}

原因二：VITE_PUBLIC_PATH = ./導致資源路徑錯位（隱藏原因，也是本文重點）

僅修復 Nginx 之后，很多人發(fā)現(xiàn)：刷新后頁面不再 404 了，但變成了白屏——HTML 返回了，JS/CSS 卻全部 404。

這是因為 Vite 打包時，base 配置項（對應 VITE_PUBLIC_PATH）決定了 index.html 里所有靜態(tài)資源的引用方式。

./（相對路徑）vs/（絕對路徑）的區(qū)別

當 VITE_PUBLIC_PATH = ./ 時，打包產物 index.html 內容如下：

<script type="module" crossorigin src="./assets/index-BsHqOBiK.js"></script>
<link rel="stylesheet" href="./assets/index-Df9KKQPD.css" rel="external nofollow" >

./ 是相對于當前頁面 URL 的路徑，瀏覽器會根據(jù)當前 URL 來解析：

當 VITE_PUBLIC_PATH = / 時，打包產物 index.html 內容如下：

<script type="module" crossorigin src="/assets/index-BsHqOBiK.js"></script>
<link rel="stylesheet" href="/assets/index-Df9KKQPD.css" rel="external nofollow" >

/ 開頭是絕對路徑，瀏覽器無論在哪個 URL 下，都固定從網站根路徑加載：

為什么首次進入正常，刷新才白屏？

因為"首次進入"通常是從網站根路徑 / 加載的 index.html，此時 ./ 被正確解析為 /assets/...，資源加載成功，Vue 啟動。

后續(xù)的頁面跳轉（/dashboard/home）是 Vue Router 純前端路由，不觸發(fā)新的 HTML 請求，資源早就加載完畢了，所以一切正常。

刷新時，瀏覽器重新請求 /dashboard/home 對應的 HTML，Nginx 回退返回 index.html，但瀏覽器此時 URL 是 /dashboard/home，./assets/... 被解析為 /dashboard/assets/...，全部 404，白屏。

三、完整修復步驟

第一步：修改 Vite 打包配置

找到項目里的 .env.production（或 vite.config.ts 里的 base 字段）：

# .env.production
- VITE_PUBLIC_PATH = ./
+ VITE_PUBLIC_PATH = /

或直接在 vite.config.ts 里：

export default defineConfig({
-  base: './',
+  base: '/',
})

第二步：檢查 Nginx 配置

確保 Nginx 有正確的 try_files 兜底：

server {
    listen 80;
    server_name your-domain.com;

    root /home/your-app/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;   # 必須有這行
    }

    # 靜態(tài)資源緩存（可選）
    location ~* \.(js|css|png|jpg|gif|ico|svg|woff2?)$ {
        expires 30d;
        access_log off;
    }
}

注意 try_files 最后參數(shù)必須是 URI（如 /index.html），不能是文件系統(tǒng)絕對路徑（如 /home/app/dist/index.html），否則 Nginx 會把它當 URL 再次查找，導致死循環(huán)或 404。

第三步：重新構建并部署

npm run build
# 將 dist/ 目錄上傳到服務器
nginx -s reload

第四步：驗證構建產物

grep -o 'src="[^"]*"' dist/index.html | head -5

正確輸出（絕對路徑，/ 開頭）：

src="/assets/index-BsHqOBiK.js"

錯誤輸出（相對路徑，./ 開頭）：

src="./assets/index-BsHqOBiK.js"

四、常見錯誤配置（避坑）

錯誤一：try_files 用文件路徑而非 URI

# ? 錯誤：/home/app/dist/index.html 被當作 URL 解析
try_files $uri $uri/ /home/app/dist/index.html;

# ? 正確：/index.html 是 URL 路徑，Nginx 會用 root 拼接找到真實文件
try_files $uri $uri/ /index.html;

錯誤二：alias + try_files 兜底路徑寫錯

location /app {
    alias /home/app/dist/;

    # ? 錯誤：兜底 URI 用 /index.html，
    # 這會跳回 location /，然后用 root 目錄找文件，與 alias 目錄不同
    try_files $uri $uri/ /index.html;

    # ? 正確：兜底 URI 帶上 location 前綴，讓請求再次進入這個 location
    try_files $uri $uri/ /app/index.html;
}

錯誤三：Hash 模式不需要任何 Nginx 配置

如果你使用的是 createWebHashHistory（URL 帶 #，如 /#/dashboard/home），# 后面的內容不會發(fā)送給服務器，Nginx 永遠只收到 GET /，不存在刷新 404 問題，無需任何特殊配置。

只有 createWebHistory（無 # 的干凈 URL）才需要上述配置。

五、總結

兩個問題獨立存在，必須同時解決。實際排查時，往往先修了 Nginx 發(fā)現(xiàn)還是白屏，再去查資源請求路徑，才發(fā)現(xiàn)是打包配置的問題。

以上就是Vue3+Vite+Nginx部署后刷新404白屏問題的完整排查指南的詳細內容，更多關于Vue3 Vite Nginx部署后刷新404白屏的資料請關注腳本之家其它相關文章！

最新評論