Vue + Vite 项目通过 /dist 子路径访问首页空白问题的完整分析与解决方案

前言
[1 问题背景与现象说明](#1 问题背景与现象说明)
[2 问题分析过程](#2 问题分析过程)
- [2.1 初步排查：确认 Nginx 是否正常工作](#2.1 初步排查：确认 Nginx 是否正常工作)
- [2.2 关键步骤：浏览器控制台与 Network 分析](#2.2 关键步骤：浏览器控制台与 Network 分析)
[3 问题根本原因剖析](#3 问题根本原因剖析)
- [3.1 Vite 的默认构建假设](#3.1 Vite 的默认构建假设)
- [3.2 子路径部署导致的资源路径失配](#3.2 子路径部署导致的资源路径失配)
- [3.3 Vue Router 的隐藏问题](#3.3 Vue Router 的隐藏问题)
[4 解决方案详解](#4 解决方案详解)
- [4.1 修改 Vite 的 base 配置](#4.1 修改 Vite 的 base 配置)
- [4.2 修改 Vue Router 的 base 路径](#4.2 修改 Vue Router 的 base 路径)
- [4.3 重新构建项目](#4.3 重新构建项目)
[5 Nginx 配置中的配合要点](#5 Nginx 配置中的配合要点)
[6 常见部署场景对比说明](#6 常见部署场景对比说明)
[7 常见误区与总结提醒](#7 常见误区与总结提醒)
结语
参考资料

前言

在前端工程化实践中，将 Vue 应用构建后部署到 Nginx 是一件再常见不过的事情。很多开发者在本地调试或单应用部署时，往往默认将应用部署在站点根路径（/）下，一切运行良好。然而，当项目需要以子路径形式部署 （例如通过 http://example.com/dist/ 访问）时，却经常会遇到一个看似"诡异"的问题：页面能访问，但首页内容为空白。

这种问题往往并非单点配置错误，而是前端构建假设、路由机制与实际部署路径不一致 所共同导致的结果。本文将围绕"通过域名 /dist/ 访问 Vue + Vite 项目首页空白"这一典型问题，系统梳理问题现象、分析思路、根本原因，并给出一套完整、可复用的解决方案，帮助你在类似部署场景中少走弯路。

1 问题背景与现象说明

在实际部署中，常见操作步骤如下：

使用 Vite 构建 Vue 项目，生成 dist 目录
将 dist 目录直接拷贝到 Nginx 的静态资源根目录
通过浏览器访问 http://example.com/dist/

结果却发现：

请求返回 HTTP 200，说明页面路径可访问
浏览器显示空白页，没有任何业务内容
页面未出现明显报错提示，乍看之下难以定位问题

从表象上看，Nginx 配置似乎没有问题，文件也确实存在，但 Vue 应用并未真正运行起来。

2 问题分析过程

2.1 初步排查：确认 Nginx 是否正常工作

分析此类问题时，第一步通常不是怀疑前端代码，而是验证基础设施是否正常：

直接访问 http://example.com/dist/index.html
查看页面源代码，确认 HTML 内容是否返回
确认 Nginx root 或 alias 配置是否正确

如果 index.html 能被正常访问并返回，基本可以确认：

Nginx 静态资源服务是可用的
dist 目录路径映射没有问题

这一步的结论是：问题并非出在 Nginx 是否能访问到 index.html。

2.2 关键步骤：浏览器控制台与 Network 分析

接下来，排查重点应转向浏览器侧：

打开开发者工具（DevTools）
重点关注 Console 和 Network 面板

在大多数情况下，会发现以下现象之一：

多个 .js、.css 文件请求返回 404
Vue 应用未挂载，但控制台无明显报错
资源请求路径与服务器实际目录不一致

例如，Network 面板中可能出现如下请求：

复制代码

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

而服务器上的真实路径却是：

复制代码

/dist/assets/index-xxxxx.js

到这里，问题已经基本明确：静态资源路径出现了偏差。

3 问题根本原因剖析

3.1 Vite 的默认构建假设

Vite 在默认配置下，假设应用部署在站点根路径 /：

ts 复制代码

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

在这种假设下，构建产物中的 index.html 会生成大量以 / 开头的绝对路径，例如：

html 复制代码

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

当应用确实部署在 / 下时，这种路径是完全正确的。

3.2 子路径部署导致的资源路径失配

当你通过 /dist/ 访问应用时：

浏览器正确请求了 /dist/index.html
但 index.html 中引用的资源仍然指向 /assets/...

这就导致浏览器尝试在站点根目录查找资源，而不是在 /dist 目录下查找，从而产生 404。由于核心 JS 文件未加载，Vue 应用自然无法初始化，最终呈现为空白页面。

3.3 Vue Router 的隐藏问题

如果项目中使用了 Vue Router（history 模式），问题还会进一步放大。

Vue Router 默认使用：

ts 复制代码

createWebHistory()

这意味着路由系统同样假设应用运行在 / 下。当应用实际运行在 /dist/ 子路径时，就会出现以下问题：

路由解析与真实 URL 不一致
页面刷新或直接访问子路由时 404
导航行为异常

因此，该问题并不仅仅是"资源路径错误"，而是构建路径与运行时路由基准路径的双重不一致。

4 解决方案详解

解决该问题的核心目标只有一个：
让前端应用在构建阶段就明确知道自己是部署在 /dist/ 下的。

4.1 修改 Vite 的 base 配置

在 vite.config.ts 中明确指定子路径：

ts 复制代码

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

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

这样做的效果是：

所有构建生成的资源路径都会自动加上 /dist/ 前缀
index.html 中的资源引用与真实部署路径保持一致

构建后的资源引用形式将变为：

html 复制代码

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

4.2 修改 Vue Router 的 base 路径

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

ts 复制代码

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

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

export default router

这样可以确保：

路由系统以 /dist/ 作为基准路径
/dist/home 能正确映射到 /home 路由
页面刷新和直接访问路由时不再出错

4.3 重新构建项目

需要特别强调的是：
base 属于构建期配置，修改后必须重新执行构建命令：

bash 复制代码

pnpm build
 或 npm run build

如果只修改配置而不重新构建，旧的路径信息仍然会保留在构建产物中，问题依旧存在。

5 Nginx 配置中的配合要点

在前端配置正确的前提下，Nginx 通常只需要最基础的静态资源映射即可，例如：

nginx 复制代码

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

如果项目使用 Vue Router 的 history 模式，建议增加兜底配置：

nginx 复制代码

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

该配置用于解决刷新页面或直接访问子路由时的 404 问题。

6 常见部署场景对比说明

部署方式	是否需要配置 base	典型访问方式
根路径部署	否（默认即可）	`/`
子路径部署	是	`/dist/`
独立二级域名	否	`app.example.com`
多前端应用共存	是	`/app1/`、`/app2/`

通过对比可以看出，只要不是部署在根路径下，就必须显式配置 base。

7 常见误区与总结提醒

在实际排查过程中，开发者往往会反复尝试修改 Nginx，却忽略了前端构建假设本身的问题。以下是一个常见误区列表（本文中唯一一次无序列表）：

认为"能访问 index.html 就说明前端没问题"
试图通过 Nginx rewrite 修复前端路径问题
忽略 Vue Router 与部署路径的关系
修改配置后忘记重新构建项目

结语

通过本文的分析可以看到，/dist 子路径访问首页空白问题，本质上并不是一个"Bug"，而是前端工程默认假设与实际部署方式不匹配所带来的结果。Vite 与 Vue Router 都需要在构建或初始化阶段明确自己的运行基准路径，一旦这一步缺失，就会在浏览器侧以"空白页"的形式暴露出来。

在现代前端项目中，子路径部署、多应用共存已是常态。建立正确的部署认知，并在构建阶段同步处理资源路径与路由基准，是一项非常值得沉淀为团队规范的工程经验。

参考资料

Vite 官方文档：Static Asset Handling
https://vitejs.dev/guide/build.html#public-base-path
Vue Router 官方文档：HTML5 History Mode
https://router.vuejs.org/guide/essentials/history-mode.html
Nginx 官方文档：try_files 指令说明
https://nginx.org/en/docs/http/ngx_http_core_module.html#try_files