适用环境：本文适用于 Vue CLI 3.x/4.x/5.x + Nginx 1.18+ 或 Apache 2.4+ + Node.js 12+ 环境。若你的环境与上述不同，执行前请先确认版本兼容性。

一、问题/场景描述

在使用 Vue.js 框架开发完项目后，执行 npm run build 打包，将生成的 dist 目录部署到 Nginx 或 Apache 服务器上，访问页面时发现浏览器显示空白，控制台无报错或仅显示资源加载失败（如 404 错误）。这是 Vue 项目部署中常见的问题，通常由资源路径配置或路由模式引起。

二、原因分析

Vue 项目打包后页面空白的核心原因有两个：一是资源文件（如 JS、CSS）的路径错误，导致浏览器无法加载；二是路由模式（如 History 模式）在非根路径下刷新时，服务器未正确配置回退。默认情况下，Vue CLI 打包时资源路径为相对路径（./），但部署到子目录时需改为绝对路径；而 History 模式需要服务器将所有请求重定向到 index.html，否则刷新页面会返回 404 并导致空白。

三、详细解决步骤

步骤1：检查并修改打包配置

打开项目的 vue.config.js 或 package.json，设置 publicPath 为绝对路径或相对路径。如果部署在根目录，使用 /；若在子目录（如 /myapp/），使用 /myapp/。示例配置如下：

// vue.config.js
module.exports = {
  publicPath: process.env.NODE_ENV === 'production' ? '/myapp/' : '/',
  outputDir: 'dist',
  assetsDir: 'static'
};

步骤2：处理路由模式

如果使用了 Vue Router 的 History 模式（mode: 'history'），需要服务器端支持。以 Nginx 为例，在配置文件中添加以下规则：

location / {
  try_files $uri $uri/ /index.html;
}

如果是 Apache，在 .htaccess 中添加：

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.html [L]

步骤3：验证资源路径

重新打包后，打开浏览器开发者工具（F12），查看 Network 面板，检查 JS 和 CSS 文件的请求 URL 是否正确。如果显示 404，说明 publicPath 设置错误。例如，部署在 http://example.com/myapp/ 下，则资源路径应为 /myapp/static/js/xxx.js。

步骤4：检查并清理缓存

有时浏览器缓存了旧的 index.html 或资源文件，导致空白。在部署后，强制刷新浏览器（Ctrl+F5）或清除浏览器缓存。如果使用 Service Worker（如 PWA），需在 vue.config.js 中禁用或重新注册：

// vue.config.js
pwa: {
  workboxPluginMode: 'InjectManifest',
  workboxOptions: {
    swSrc: 'src/service-worker.js',
    swDest: 'service-worker.js'
  }
}

步骤5：使用相对路径打包（备选方案）

如果服务器无法修改配置，可以设置 publicPath 为 './'（注意是点斜杠），使所有资源使用相对路径。但此方式在嵌套路由中可能失效，建议优先使用绝对路径。

// vue.config.js
module.exports = {
  publicPath: './',
  outputDir: 'dist'
};

四、注意事项

修改 publicPath 后，必须重新执行 npm run build 生成新 dist 目录。部署时确保服务器静态文件指向 dist 根目录。如果使用 CDN，需将 publicPath 设为 CDN 域名。另外，History 模式下的服务器配置需重启生效。

五、适用环境

本文适用于 Vue CLI 3.x/4.x/5.x 项目，配合 Nginx 1.18+ 或 Apache 2.4+，以及 Node.js 12+ 环境。其他构建工具（如 Vite）配置类似，但 publicPath 属性名不同（Vite 中为 base）。

Vue项目打包后页面空白：原因与解决方案