前言

在前端工程化實(shí)踐中，將 Vue 應(yīng)用構(gòu)建后部署到 Nginx 是一件再常見(jiàn)不過(guò)的事情。很多開(kāi)發(fā)者在本地調(diào)試或單應(yīng)用部署時(shí)，往往默認(rèn)將應(yīng)用部署在站點(diǎn)根路徑（/）下，一切運(yùn)行良好。然而，當(dāng)項(xiàng)目需要以子路徑形式部署（例如通過(guò) http://example.com/dist/ 訪問(wèn)）時(shí)，卻經(jīng)常會(huì)遇到一個(gè)看似“詭異”的問(wèn)題：頁(yè)面能訪問(wèn)，但首頁(yè)內(nèi)容為空白。

這種問(wèn)題往往并非單點(diǎn)配置錯(cuò)誤，而是前端構(gòu)建假設(shè)、路由機(jī)制與實(shí)際部署路徑不一致所共同導(dǎo)致的結(jié)果。本文將圍繞“通過(guò)域名 /dist/ 訪問(wèn) Vue + Vite 項(xiàng)目首頁(yè)空白”這一典型問(wèn)題，系統(tǒng)梳理問(wèn)題現(xiàn)象、分析思路、根本原因，并給出一套完整、可復(fù)用的解決方案，幫助你在類似部署場(chǎng)景中少走彎路。

1 問(wèn)題背景與現(xiàn)象說(shuō)明

在實(shí)際部署中，常見(jiàn)操作步驟如下：

1. 使用 Vite 構(gòu)建 Vue 項(xiàng)目，生成 dist 目錄
2. 將 dist 目錄直接拷貝到 Nginx 的靜態(tài)資源根目錄
3. 通過(guò)瀏覽器訪問(wèn) http://example.com/dist/

結(jié)果卻發(fā)現(xiàn)：

• 請(qǐng)求返回 HTTP 200，說(shuō)明頁(yè)面路徑可訪問(wèn)
• 瀏覽器顯示空白頁(yè)，沒(méi)有任何業(yè)務(wù)內(nèi)容
• 頁(yè)面未出現(xiàn)明顯報(bào)錯(cuò)提示，乍看之下難以定位問(wèn)題

從表象上看，Nginx 配置似乎沒(méi)有問(wèn)題，文件也確實(shí)存在，但 Vue 應(yīng)用并未真正運(yùn)行起來(lái)。

2 問(wèn)題分析過(guò)程

2.1 初步排查：確認(rèn) Nginx 是否正常工作

分析此類問(wèn)題時(shí)，第一步通常不是懷疑前端代碼，而是驗(yàn)證基礎(chǔ)設(shè)施是否正常：

• 直接訪問(wèn) http://example.com/dist/index.html
• 查看頁(yè)面源代碼，確認(rèn) HTML 內(nèi)容是否返回
• 確認(rèn) Nginx root 或 alias 配置是否正確

如果 index.html 能被正常訪問(wèn)并返回，基本可以確認(rèn)：

• Nginx 靜態(tài)資源服務(wù)是可用的
• dist 目錄路徑映射沒(méi)有問(wèn)題

這一步的結(jié)論是：問(wèn)題并非出在 Nginx 是否能訪問(wèn)到 index.html。

2.2 關(guān)鍵步驟：瀏覽器控制臺(tái)與 Network 分析

接下來(lái)，排查重點(diǎn)應(yīng)轉(zhuǎn)向?yàn)g覽器側(cè)：

• 打開(kāi)開(kāi)發(fā)者工具（DevTools）
• 重點(diǎn)關(guān)注 Console 和 Network 面板

在大多數(shù)情況下，會(huì)發(fā)現(xiàn)以下現(xiàn)象之一：

• 多個(gè) .js、.css 文件請(qǐng)求返回 404
• Vue 應(yīng)用未掛載，但控制臺(tái)無(wú)明顯報(bào)錯(cuò)
• 資源請(qǐng)求路徑與服務(wù)器實(shí)際目錄不一致

例如，Network 面板中可能出現(xiàn)如下請(qǐng)求：

http://example.com/assets/index-xxxxx.js

而服務(wù)器上的真實(shí)路徑卻是：

/dist/assets/index-xxxxx.js

到這里，問(wèn)題已經(jīng)基本明確：靜態(tài)資源路徑出現(xiàn)了偏差。

3 問(wèn)題根本原因剖析

3.1 Vite 的默認(rèn)構(gòu)建假設(shè)

Vite 在默認(rèn)配置下，假設(shè)應(yīng)用部署在站點(diǎn)根路徑 /：

export default defineConfig({
  base: '/'
})

在這種假設(shè)下，構(gòu)建產(chǎn)物中的 index.html 會(huì)生成大量以 / 開(kāi)頭的絕對(duì)路徑，例如：

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

當(dāng)應(yīng)用確實(shí)部署在 / 下時(shí)，這種路徑是完全正確的。

3.2 子路徑部署導(dǎo)致的資源路徑失配

當(dāng)你通過(guò) /dist/ 訪問(wèn)應(yīng)用時(shí)：

• 瀏覽器正確請(qǐng)求了 /dist/index.html
• 但 index.html 中引用的資源仍然指向 /assets/...

這就導(dǎo)致瀏覽器嘗試在站點(diǎn)根目錄查找資源，而不是在 /dist 目錄下查找，從而產(chǎn)生 404。由于核心 JS 文件未加載，Vue 應(yīng)用自然無(wú)法初始化，最終呈現(xiàn)為空白頁(yè)面。

3.3 Vue Router 的隱藏問(wèn)題

如果項(xiàng)目中使用了 Vue Router（history 模式），問(wèn)題還會(huì)進(jìn)一步放大。

Vue Router 默認(rèn)使用：

createWebHistory()

這意味著路由系統(tǒng)同樣假設(shè)應(yīng)用運(yùn)行在 / 下。當(dāng)應(yīng)用實(shí)際運(yùn)行在 /dist/ 子路徑時(shí)，就會(huì)出現(xiàn)以下問(wèn)題：

• 路由解析與真實(shí) URL 不一致
• 頁(yè)面刷新或直接訪問(wèn)子路由時(shí) 404
• 導(dǎo)航行為異常

因此，該問(wèn)題并不僅僅是“資源路徑錯(cuò)誤”，而是構(gòu)建路徑與運(yùn)行時(shí)路由基準(zhǔn)路徑的雙重不一致。

4 解決方案詳解

解決該問(wèn)題的核心目標(biāo)只有一個(gè)：
讓前端應(yīng)用在構(gòu)建階段就明確知道自己是部署在 /dist/ 下的。

4.1 修改 Vite 的 base 配置

在 vite.config.ts 中明確指定子路徑：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  base: '/dist/'
})

這樣做的效果是：

• 所有構(gòu)建生成的資源路徑都會(huì)自動(dòng)加上 /dist/ 前綴
• index.html 中的資源引用與真實(shí)部署路徑保持一致

構(gòu)建后的資源引用形式將變?yōu)椋?/p>

<script type="module" src="/dist/assets/index-xxxxx.js"></script>

4.2 修改 Vue Router 的 base 路徑

在路由配置中同步指定 base：

import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory('/dist/'),
  routes: [
    // 路由定義
  ]
})

export default router

這樣可以確保：

• 路由系統(tǒng)以 /dist/ 作為基準(zhǔn)路徑
• /dist/home 能正確映射到 /home 路由
• 頁(yè)面刷新和直接訪問(wèn)路由時(shí)不再出錯(cuò)

4.3 重新構(gòu)建項(xiàng)目

需要特別強(qiáng)調(diào)的是：
base 屬于構(gòu)建期配置，修改后必須重新執(zhí)行構(gòu)建命令：

pnpm build
 或 npm run build

如果只修改配置而不重新構(gòu)建，舊的路徑信息仍然會(huì)保留在構(gòu)建產(chǎn)物中，問(wèn)題依舊存在。

5 Nginx 配置中的配合要點(diǎn)

在前端配置正確的前提下，Nginx 通常只需要最基礎(chǔ)的靜態(tài)資源映射即可，例如：

location /dist/ {
    root /usr/share/nginx/html;
    index index.html;
}

如果項(xiàng)目使用 Vue Router 的 history 模式，建議增加兜底配置：

try_files $uri $uri/ /dist/index.html;

該配置用于解決刷新頁(yè)面或直接訪問(wèn)子路由時(shí)的 404 問(wèn)題。

6 常見(jiàn)部署場(chǎng)景對(duì)比說(shuō)明

通過(guò)對(duì)比可以看出，只要不是部署在根路徑下，就必須顯式配置 base。

7 常見(jiàn)誤區(qū)與總結(jié)提醒

在實(shí)際排查過(guò)程中，開(kāi)發(fā)者往往會(huì)反復(fù)嘗試修改 Nginx，卻忽略了前端構(gòu)建假設(shè)本身的問(wèn)題。以下是一個(gè)常見(jiàn)誤區(qū)列表（本文中唯一一次無(wú)序列表）：

• 認(rèn)為“能訪問(wèn) index.html 就說(shuō)明前端沒(méi)問(wèn)題”
• 試圖通過(guò) Nginx rewrite 修復(fù)前端路徑問(wèn)題
• 忽略 Vue Router 與部署路徑的關(guān)系
• 修改配置后忘記重新構(gòu)建項(xiàng)目

結(jié)語(yǔ)

通過(guò)本文的分析可以看到，/dist 子路徑訪問(wèn)首頁(yè)空白問(wèn)題，本質(zhì)上并不是一個(gè)“Bug”，而是前端工程默認(rèn)假設(shè)與實(shí)際部署方式不匹配所帶來(lái)的結(jié)果。Vite 與 Vue Router 都需要在構(gòu)建或初始化階段明確自己的運(yùn)行基準(zhǔn)路徑，一旦這一步缺失，就會(huì)在瀏覽器側(cè)以“空白頁(yè)”的形式暴露出來(lái)。

在現(xiàn)代前端項(xiàng)目中，子路徑部署、多應(yīng)用共存已是常態(tài)。建立正確的部署認(rèn)知，并在構(gòu)建階段同步處理資源路徑與路由基準(zhǔn)，是一項(xiàng)非常值得沉淀為團(tuán)隊(duì)規(guī)范的工程經(jīng)驗(yàn)。

以上就是Vue + Vite項(xiàng)目通過(guò)/dist子路徑訪問(wèn)首頁(yè)空白問(wèn)題的完整分析與解決方案的詳細(xì)內(nèi)容，更多關(guān)于Vue /dist子路徑訪問(wèn)首頁(yè)空白的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！

最新評(píng)論