“為什么我訪問
http://127.0.0.1:5501/index.html白屏，刪了index.html再訪問/就又活過來了？”
—— 你的項目與 SPA 路由的“宮斗大戲”
一、問題復現
-
場景
-
本地通過 VSCode Live Server（或其他靜態服務器）啟動了打包后的 Vue3 應用目錄（假設為
dist/）。 -
訪問
http://127.0.0.1:5501/index.html，頁面一片空白（白屏）。 -
刪掉根目錄下的
index.html，再次訪問http://127.0.0.1:5501/，頁面又瞬間正常渲染了！
-
-
本能誤區
-
“是不是文件丟了？是不是打包壞了？”
-
反復打包、重裝依賴，也無濟于事。
-
二、幕后黑手：靜態掛載 & 路由攔截雙重鍋
1. 靜態服務器掛載順序
多數本地靜態服務器（Live Server、http-server、serve 等）默認會：
-
優先尋找請求路徑對應的靜態文件（如
index.html、.js、.css等）。 -
若文件存在，則直接返回該文件，不再回退到其它目錄。
-
若文件不存在，則“fallback”到根目錄的
index.html（如果開啟了單頁應用回退）。
因果分析
-
當你在項目根目錄下也放置了一份 “空白”
index.html（比如不小心把源碼的空白模板也上傳進dist/），訪問/index.html時，服務器把它當作靜態文件直接返回，就一片白。 -
刪除后，請求
/index.html找不到后，觸發回退，將真正的打包入口dist/index.html返回，于是頁面正常。
2. Vue Router History 模式“誤判”
如果你在項目中使用了 createWebHistory()（History 模式）：
-
訪問
http://…/index.html-
瀏覽器加載了文件后，Vue 啟動時會把當前 URL 路徑
/index.html當成一個路由去匹配。 -
由于通常路由表里并沒有對應
/index.html的條目，結果匹配失敗，組件不渲染，就白屏了。
-
-
訪問
http://…/-
路徑是
/，正好匹配首頁組件，應用正常啟動。
-
三、最終解法：規范掛載 & 路由回退
下面以 Nginx 為例，示范如何在生產（或本地模擬生產）環境下正確部署，徹底杜絕“刪了才行”的尷尬。
1. Nginx 標準配置
server {listen 80;server_name your.domain.com; # 替換成你的域名或 IP# ① 指定根目錄為打包輸出root /var/www/myapp; # 假設你把 dist 放這里index index.html;# ② 靜態資源走文件系統，開啟長緩存location ~* \.(js|css|png|jpg|jpeg|gif|svg|ico|ttf|woff2?)$ {expires 30d;access_log off;}# ③ 單頁應用路由回退location / {try_files $uri $uri/ /index.html;}# ④ 全部 404 也返回入口頁（可選）error_page 404 /index.html;
}
部署步驟
-
打包 & 上傳
npm run build scp -r dist/* user@server:/var/www/myapp/ -
放置配置
-
CentOS：直接放在
/etc/nginx/conf.d/myapp.conf
-
-
測試 & 重載
sudo nginx -t sudo systemctl reload nginx
2. VSCode Live Server（本地調試）快速修復
在項目根目錄下新建或修改 .vscode/settings.json：
{"liveServer.settings.root": "dist"
}
保存后重啟 Live Server，即可讓它把
dist/當作站點根，不再被源碼根目錄下的文件干擾。
四、補充技巧
-
避免手動地址欄寫
index.html
直接訪問/即可，現代服務器都會自動加載index.html。 -
Hash 模式降級
如果你不想配置服務器路由回退，可在 Vue Router 中改為：import { createRouter, createWebHashHistory } from 'vue-router' const router = createRouter({history: createWebHashHistory(),routes: [ /* ... */ ] });所有 URL 會加上
#/，徹底繞過服務器路由判斷。 -
CI/CD 自動發布
在打包完成后，結合 GitHub Actions / GitLab CI 自動將dist/同步到服務器或 CDN，避免漏傳、錯傳文件。
五、結語
原來「刪除一份文件就能跑起來」背后的真相，既有靜態服務器的掛載機制，也有 Vue Router 的路由解析邏輯。掌握了這兩點，你就能：
-
保證打包目錄干凈、無冗余模板
-
正確配置服務器根目錄和單頁應用回退
-
根據場景靈活切換 History/Hash 模式
從此，無論在本地調試還是在線上發布，都能穩穩啟動，再也不用靠“刪檔”才能爽跑！如果你也碰到過類似詭異白屏，趕緊對照本文排查一遍吧~
