“為什么我訪問 http://127.0.0.1:5501/index.html 白屏，刪了 index.html 再訪問 / 就又活過來了？”

—— 你的項(xiàng)目與 SPA 路由的“宮斗大戲”

一、問題復(fù)現(xiàn)

場景

• 本地通過 VSCode Live Server（或其他靜態(tài)服務(wù)器）啟動了打包后的 Vue3 應(yīng)用目錄（假設(shè)為 dist/）。
• 訪問 http://127.0.0.1:5501/index.html，頁面一片空白（白屏）。
• 刪掉根目錄下的 index.html，再次訪問 http://127.0.0.1:5501/，頁面又瞬間正常渲染了！

本能誤區(qū)

• “是不是文件丟了？是不是打包壞了？”
• 反復(fù)打包、重裝依賴，也無濟(jì)于事。

二、幕后黑手：靜態(tài)掛載 & 路由攔截雙重鍋

1. 靜態(tài)服務(wù)器掛載順序

多數(shù)本地靜態(tài)服務(wù)器（Live Server、http-server、serve 等）默認(rèn)會：

• 優(yōu)先尋找請求路徑對應(yīng)的靜態(tài)文件（如 index.html、.js、.css 等）。
• 若文件存在，則直接返回該文件，不再回退到其它目錄。
• 若文件不存在，則“fallback”到根目錄的 index.html（如果開啟了單頁應(yīng)用回退）。

因果分析

當(dāng)你在項(xiàng)目根目錄下也放置了一份 “空白” index.html（比如不小心把源碼的空白模板也上傳進(jìn) dist/），訪問 /index.html 時(shí)，服務(wù)器把它當(dāng)作靜態(tài)文件直接返回，就一片白。

刪除后，請求 /index.html 找不到后，觸發(fā)回退，將真正的打包入口 dist/index.html 返回，于是頁面正常。

2. Vue Router History 模式“誤判”

如果你在項(xiàng)目中使用了 createWebHistory()（History 模式）：

訪問 http://…/index.html

• 瀏覽器加載了文件后，Vue 啟動時(shí)會把當(dāng)前 URL 路徑 /index.html 當(dāng)成一個(gè)路由去匹配。
• 由于通常路由表里并沒有對應(yīng) /index.html 的條目，結(jié)果匹配失敗，組件不渲染，就白屏了。

訪問 http://…/

路徑是 /，正好匹配首頁組件，應(yīng)用正常啟動。

三、最終解法：規(guī)范掛載 & 路由回退

下面以 Nginx 為例，示范如何在生產(chǎn)（或本地模擬生產(chǎn)）環(huán)境下正確部署，徹底杜絕“刪了才行”的尷尬。

1. Nginx 標(biāo)準(zhǔn)配置

server {
    listen       80;
    server_name  your.domain.com;            # 替換成你的域名或 IP
 
    # ① 指定根目錄為打包輸出
    root   /var/www/myapp;                   # 假設(shè)你把 dist 放這里
    index  index.html;
 
    # ② 靜態(tài)資源走文件系統(tǒng)，開啟長緩存
    location ~* \.(js|css|png|jpg|jpeg|gif|svg|ico|ttf|woff2?)$ {
        expires    30d;
        access_log off;
    }
 
    # ③ 單頁應(yīng)用路由回退
    location / {
        try_files $uri $uri/ /index.html;
    }
 
    # ④ 全部 404 也返回入口頁（可選）
    error_page 404 /index.html;
}

部署步驟

1.打包 & 上傳

npm run build
scp -r dist/* user@server:/var/www/myapp/

2.放置配置

CentOS：直接放在 /etc/nginx/conf.d/myapp.conf

3.測試 & 重載

sudo nginx -t
sudo systemctl reload nginx

2. VSCode Live Server（本地調(diào)試）快速修復(fù)

在項(xiàng)目根目錄下新建或修改 .vscode/settings.json：

{
  "liveServer.settings.root": "dist"
}

保存后重啟 Live Server，即可讓它把 dist/ 當(dāng)作站點(diǎn)根，不再被源碼根目錄下的文件干擾。

四、補(bǔ)充技巧

1.避免手動地址欄寫 index.html

直接訪問 / 即可，現(xiàn)代服務(wù)器都會自動加載 index.html。

2.Hash 模式降級

如果你不想配置服務(wù)器路由回退，可在 Vue Router 中改為：

import { createRouter, createWebHashHistory } from 'vue-router'
const router = createRouter({
  history: createWebHashHistory(),
  routes: [ /* ... */ ]
});

所有 URL 會加上 #/，徹底繞過服務(wù)器路由判斷。

3.CI/CD 自動發(fā)布

在打包完成后，結(jié)合 GitHub Actions / GitLab CI 自動將 dist/ 同步到服務(wù)器或 CDN，避免漏傳、錯(cuò)傳文件。

五、結(jié)語

原來「刪除一份文件就能跑起來」背后的真相，既有靜態(tài)服務(wù)器的掛載機(jī)制，也有 Vue Router 的路由解析邏輯。掌握了這兩點(diǎn)，你就能：

保證打包目錄干凈、無冗余模板

正確配置服務(wù)器根目錄和單頁應(yīng)用回退

根據(jù)場景靈活切換 History/Hash 模式

從此，無論在本地調(diào)試還是在線上發(fā)布，都能穩(wěn)穩(wěn)啟動，再也不用靠“刪檔”才能爽跑！如果你也碰到過類似詭異白屏，趕緊對照本文排查一遍吧~

到此這篇關(guān)于Vue3本地打包啟動出現(xiàn)白屏的解決思路詳解的文章就介紹到這了,更多相關(guān)Vue打包啟動出現(xiàn)白屏內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評論