Vue项目部署到 Nginx 子路径白屏问题排查与解决

问题描述

Vue 3 + Vite 项目部署到 Nginx 服务器的子路径 /qk/ 下，访问页面时出现白屏，浏览器控制台无明显 JS 报错。

环境

• Vue 3 + Vue Router 5 + Vite
• Nginx（宝塔面板）
• 部署路径：/qk/（非根目录）

排查过程

1. 检查资源加载（排除资源 404）

打开浏览器 F12 → Network 面板，确认所有 JS/CSS 文件均返回 200：

资源加载正常，排除资源路径问题。

2. 检查控制台报错

Console 中仅有 SES Removing unpermitted intrinsics，这是 MetaMask 等浏览器扩展的日志，与项目无关。

3. 定位根因：Router 路径不匹配

资源加载正常、无 JS 报错，但页面空白 —— 说明 Vue Router 没有匹配到任何路由，导致无组件渲染。

原因分析：

• 应用部署在 /qk/ 子路径下

• 用户访问 https://gyqaq.fun/qk/
• Vue Router 使用 createWebHistory() 未设置 base 路径

• Router 将完整路径 /qk/ 去匹配路由表，但路由表中只有 /、/home、/login 等
• 没有路由匹配 → 无组件渲染 → 白屏

解决方案

需要同时修改两处配置：

1. vite.config.ts — 设置 base

export default defineConfig({
  base: '/qk/',  // 构建产物的资源路径前缀
  // ...
})

这一步让 Vite 构建时，index.html 中引用的 JS/CSS 路径变为 /qk/assets/xxx，而不是 /assets/xxx。

2. src/router/index.ts — 设置 Router base

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),  // 路由基准路径
  routes,
})

这一步让 Vue Router 知道应用运行在 /qk/ 下，路由匹配时会正确处理路径前缀。

3. 重新构建部署

npm run build

将 dist 目录内容上传到服务器 /www/wwwroot/gyqaq.fun/qk/ 下。

Nginx 配置参考

location ^~ /qk {
    try_files $uri $uri/ /qk/index.html;
}

try_files 确保所有未匹配的路径都回退到 index.html，交给前端路由处理（SPA 的核心配置）。

总结

核心原则：部署到子路径时，vite.config.ts 的 base 和 createWebHistory() 的参数必须与 Nginx 的 location 路径保持一致。