踩坑记录：Vite+Vue3 本地运行正常，打包上线白屏、无报错、空白页

最近重构公司内部后台系统，技术栈用的Vite4 + Vue3 + Vue-Router4 + Pinia。

本地 dev 环境跑起来一切正常，页面、路由、接口全部没问题。执行 build 打包部署到测试服务器后，直接纯白屏。

最离谱的是：浏览器控制台没有报错、没有404、没有红标，网络请求也正常，就是页面一片空白。

折腾了半个多小时终于定位到问题，顺便把 Vite 打包白屏的高频原因一次性整理全，方便以后踩坑直接复用。

一、现场问题现象

完整复现条件：

npm run dev：本地完全正常
npm run build + 部署 nginx / 静态服务器：页面纯白
F12 控制台无任何报错，资源全部加载成功
DOM 结构为空，#app 内部没有渲染内容

这种无报错白屏是最恶心的，因为完全没有排查线索。

二、本次直接根因（我的真实坑点）

1. 路由模式不匹配 + 部署二级目录

很多人本地开发都是 history 模式，本地根路径访问没问题。

但我这次项目部署在 服务器二级子目录，不是网站根目录。

例如：本地访问 http://localhost:5173/，线上实际地址是 https://xxx.com/admin/

结果就是：

打包后静态资源路径错位 + history 路由匹配不到，导致页面直接不挂载

2. Vite 未配置 base 公共路径

Vue2 + Webpack 时代很多人习惯忽略 publicPath，但是 Vite 必须手动配置。

Vite 默认打包根路径是 /，如果项目部署在二级目录，不改 base 必然资源路径错误。

3. 路由 createWebHistory 传空

history 模式下，如果部署目录和路由基础路径不统一，路由匹配失败，App 组件不会渲染，页面直接空白，而且不会报错。

三、完整修复方案

第一步：修改 vite.config.ts 配置 base

根据你的部署目录填写，我这里是 /admin/，末尾斜杠必须加。

复制代码

import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [vue()], // 关键：和部署二级目录一致 base: '/admin/', server: { host: '0.0.0.0', port: 5173 } })

第二步：路由统一配置 history 基础路径

router/index.ts 中，createWebHistory 传入和 base 一致的路径。

复制代码

import { createRouter, createWebHistory } from 'vue-router' import type { RouteRecordRaw } from 'vue-router' const routes: RouteRecordRaw[] = [ { path: '/', redirect: '/home' }, { path: '/home', component: () => import('@/views/home/index.vue') } ] // 关键：参数和vite base保持一致 const router = createRouter({ history: createWebHistory('/admin/'), routes }) export default router

第三步：Nginx 配置适配 history 模式

如果不配置 try_files，刷新页面会 404，打包部署必须配。

复制代码

location /admin/ { root /你的静态资源目录; index index.html; try_files $uri $uri/ /admin/index.html; }

改完重新 build 打包上传，页面直接恢复正常。

四、整理：Vite打包白屏 90% 都是这 5 个原因

结合我多年踩坑经验，总结 Vite 打包白屏高频问题，以后遇到直接对照排查。

1. 部署二级目录未配置 base（最高频）

现象：本地正常，打包白屏，资源路径404（有时被缓存掩盖）。

解决：vite base + router history 路径统一。

2. 路由模式问题

hash 模式基本不会白屏，history 模式最容易出问题。

没有配置 Nginx 重写、路径不统一，直接空白。

3. 环境变量未兼容生产环境

开发用 .env.development，打包没配置 .env.production，接口地址、全局变量缺失导致组件初始化失败。

4. 依赖版本兼容问题

部分旧 UI 库、lodash 老版本、svg 插件在 dev 正常，build 压缩后报错静默失败。

5. 开启严格模式 / 打包压缩移除代码

Vite 生产打包会 tree-shaking、压缩、去除开发代码，部分不规范的写法（未定义变量、隐性全局变量）dev 不报错，build 直接挂。

五、个人总结（避坑经验）

Vite 项目只要是非根目录部署，第一件事就是改 base 和路由 history 路径，不要等上线翻车再改。
白屏优先看 资源路径、路由基础路径、Nginx 重写规则，90% 问题出在这里。
本地正常线上异常，基本都是环境差异、打包差异、路径差异，不是代码逻辑问题。
以后所有 Vue3 + Vite 项目，直接统一一套部署配置，不用每次踩坑复盘。

希望这篇复盘能帮到正在白屏折磨的朋友，少踩坑，少加班。