将Vite Vue.js应用部署到Apache服务器的白屏问题排查

问题 #

本地使用XAMPP Apache服务器，执行npm run preview和serve -s dist时应用可通过带端口的地址（如localhost:3000）正常访问。将dist文件夹复制到XAMPP的htdocs/production目录（文档根路径为C:/xampp/htdocs/production/）后，尝试通过localhost/production访问时页面白屏，仅能看到标题栏图标，控制台无报错。已配置.htaccess并检查过js、css文件路径。

相关文件内容：

当前.htaccess文件 #

Options -MultiViews
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.html [QSA,L]
RewriteCond %{REQUEST_URI} index.html$1

index.html文件 #

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <link rel="icon" href="/production/assets/denr-cdf828ad.png">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>NGPDBS</title>
    <script type="module" crossorigin src="/production/assets/index-c66d07a1.js"></script>
    <link rel="stylesheet" href="/production/assets/index-5f93e947.css">
  </head>
  <body>
    <div id="app"></div>
    
  </body>
</html>

vite.config.js文件 #

import { fileURLToPath, URL } from 'node:url'

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

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    vue(),
  ],
  base: '/production/',
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
})

解决方法 #

1. 修正.htaccess文件的无效规则 #

当前.htaccess最后一行RewriteCond %{REQUEST_URI} index.html$1属于无效规则（无对应RewriteRule且语法错误），直接删除该行。同时针对子目录部署场景，调整重写路径确保路由正确：

Options -MultiViews
RewriteEngine On
# 非文件/目录请求重写到子目录下的index.html
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ /production/index.html [QSA,L]

2. 验证资源路径的实际可达性 #

通过浏览器开发者工具的网络面板确认：

• 访问localhost/production，查看js、css、图标文件的请求状态，若出现404则说明路径或文件存在问题
• 核对C:/xampp/htdocs/production/assets目录下是否存在对应哈希命名的资源文件

3. 重新构建应用（推荐） #

确保vite的base配置正确后，执行重新构建命令覆盖旧文件，避免缓存导致的路径异常：

npm run build

将新生成的dist文件夹内容覆盖到htdocs/production目录。

4. 启用Apache重写模块 #

打开XAMPP的httpd.conf配置文件，确保重写模块未被注释（去掉行首的#）：

LoadModule rewrite_module modules/mod_rewrite.so

修改后重启Apache服务。

5. 确认Apache目录权限配置 #

检查httpd.conf中的文档根及目录权限设置，确保.htaccess规则能生效：

DocumentRoot "C:/xampp/htdocs"
<Directory "C:/xampp/htdocs">
    Options Indexes FollowSymLinks Includes ExecCGI
    AllowOverride All
    Require all granted
</Directory>

内容的提问来源于stack exchange，提问作者Jiel