Vue3+Vite項目部署后刷新白屏問題的解決方法

更新時間：2025年03月25日 16:16:57 作者：從文處安

Vue3 + Vite 項目部署后出現(xiàn)了手動刷新頁面時出現(xiàn)白屏的問題,下面小編就來和大家探討一下白屏出現(xiàn)的原因以及具體的解決方法,需要的可以參考下

問題現(xiàn)象

使用 Vue3 + Vite + vue-router 的項目在本地開發(fā)正常，但打包部署到服務器后：

直接訪問首頁正常
通過路由跳轉頁面正常
手動刷新頁面時出現(xiàn)白屏
控制臺可能顯示 404 錯誤或資源加載失敗

核心原因分析

1. 路由模式與服務器配置沖突

Vue-router 使用 createWebHistory()，實際使用的是瀏覽器原生 History API。

這種模式需要服務器配合處理非根路徑的請求，否則刷新時服務器會嘗試查找不存在的物理文件。

2. Vite 基礎路徑配置

// vite.config.js
export default defineConfig({
  base: '/this/is/a/path/', // 該路徑必須與部署目錄完全一致
})

3. Vue Router 配置

const router = createRouter({
  history: createWebHistory('/this/is/a/path/'), // 與 Vite base 配置一致
  routes
})

解決方案

1. 驗證配置一致性

配置項	正確示例	驗證方法
Vite base	/this/is/a/path/	檢查打包后的 index.html 資源路徑
Router history	createWebHistory('/this/is/a/path/')	檢查路由初始化代碼
實際部署路徑	http://domain.com/this/is/a/path/	檢查服務器部署目錄

注意：所有路徑配置必須保持完全一致，特別注意結尾的 /

2. 服務器配置示例

Nginx 配置

location /this/is/a/path/ {
  # 指向打包后的目錄
  alias /your/project/dist/;
  try_files $uri $uri/ /this/is/a/path/index.html;
  
  # 開啟 gzip
  gzip on;
  gzip_types text/plain application/xml application/javascript text/css;
}

Apache 配置（.htaccess）

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /this/is/a/path/
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /this/is/a/path/index.html [L]
</IfModule>

3. 驗證資源加載路徑

打開瀏覽器開發(fā)者工具，檢查以下資源是否正常加載：

JS/CSS 文件路徑
圖標等靜態(tài)資源
異步加載的 chunk 文件

正確路徑示例：

https://your-domain.com/this/is/a/path/assets/index.123abc.js

4. 處理靜態(tài)資源 404

如果出現(xiàn)靜態(tài)資源 404，可嘗試以下方案：

// vite.config.js
export default defineConfig({
  build: {
    assetsDir: 'static', // 將資源分類到 static 目錄
    rollupOptions: {
      output: {
        assetFileNames: 'static/[name]-[hash][extname]'
      }
    }
  }
})

常見錯誤排查表

錯誤現(xiàn)象	可能原因	解決方案
所有頁面顯示 404	服務器未指向正確目錄	檢查服務器配置的 root/alias
僅刷新時白屏	缺少 try_files/rewrite 規(guī)則	添加 history fallback 配置
部分資源 404	base 路徑不一致	統(tǒng)一所有路徑配置
控制臺顯示路由錯誤	路由配置路徑沖突	檢查路由的 path 定義
開發(fā)環(huán)境正常，生產環(huán)境異常	環(huán)境變量未正確處理	檢查 .env 文件配置

進階優(yōu)化

動態(tài)路徑配置

// vite.config.js
export default defineConfig({
  base: process.env.NODE_ENV === 'production' 
    ? '/this/is/a/path/' 
    : '/'
})

自定義 404 頁面處理

// router.js
const router = createRouter({
  history: createWebHistory('/this/is/a/path/'),
  routes: [
    // ...
    { 
      path: '/:pathMatch(.*)*', 
      component: () => import('@/views/404.vue')
    }
  ]
})

部署路徑健康檢查

// main.js
if (import.meta.env.PROD) {
  const expectedBase = '/this/is/a/path/';
  const currentPath = window.location.pathname;
  
  if (!currentPath.startsWith(expectedBase)) {
    window.location.replace(expectedBase);
  }
}