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

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

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

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

原因二：VITE_PUBLIC_PATH = ./導(dǎo)致資源路徑錯(cuò)位（隱藏原因，也是本文重點(diǎn)）

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

這是因?yàn)?Vite 打包時(shí)，base 配置項(xiàng)（對(duì)應(yīng) VITE_PUBLIC_PATH）決定了 index.html 里所有靜態(tài)資源的引用方式。

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

當(dāng) VITE_PUBLIC_PATH = ./ 時(shí)，打包產(chǎn)物 index.html 內(nèi)容如下：

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

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

當(dāng) VITE_PUBLIC_PATH = / 時(shí)，打包產(chǎn)物 index.html 內(nèi)容如下：

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

/ 開頭是絕對(duì)路徑，瀏覽器無論在哪個(gè) URL 下，都固定從網(wǎng)站根路徑加載：

為什么首次進(jìn)入正常，刷新才白屏？

因?yàn)?quot;首次進(jìn)入"通常是從網(wǎng)站根路徑 / 加載的 index.html，此時(shí) ./ 被正確解析為 /assets/...，資源加載成功，Vue 啟動(dòng)。

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

刷新時(shí)，瀏覽器重新請(qǐng)求 /dashboard/home 對(duì)應(yīng)的 HTML，Nginx 回退返回 index.html，但瀏覽器此時(shí) URL 是 /dashboard/home，./assets/... 被解析為 /dashboard/assets/...，全部 404，白屏。

三、完整修復(fù)步驟

第一步：修改 Vite 打包配置

找到項(xiàng)目里的 .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)絕對(duì)路徑（如 /home/app/dist/index.html），否則 Nginx 會(huì)把它當(dāng) URL 再次查找，導(dǎo)致死循環(huán)或 404。

第三步：重新構(gòu)建并部署

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

第四步：驗(yàn)證構(gòu)建產(chǎn)物

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

正確輸出（絕對(duì)路徑，/ 開頭）：

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

錯(cuò)誤輸出（相對(duì)路徑，./ 開頭）：

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

四、常見錯(cuò)誤配置（避坑）

錯(cuò)誤一：try_files 用文件路徑而非 URI

# ? 錯(cuò)誤：/home/app/dist/index.html 被當(dāng)作 URL 解析
try_files $uri $uri/ /home/app/dist/index.html;

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

錯(cuò)誤二：alias + try_files 兜底路徑寫錯(cuò)

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

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

    # ? 正確：兜底 URI 帶上 location 前綴，讓請(qǐng)求再次進(jìn)入這個(gè) location
    try_files $uri $uri/ /app/index.html;
}

錯(cuò)誤三：Hash 模式不需要任何 Nginx 配置

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

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

五、總結(jié)

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

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