VueJS+Vite构建预览/生产环境首次加载白屏404问题求助

核心原因 #

首次加载时浏览器或Service Worker缓存了旧的index.html，而旧index.html引用的带哈希资源已被新构建覆盖，导致404；刷新后浏览器拉取最新index.html，即可加载正确的新资源。

具体修复步骤 #

1. 修正构建输出的哈希占位符配置

你的build.rollupOptions.output中使用了未定义的hash变量，会导致哈希生成异常，正确写法应使用Rollup内置的[hash]占位符：

build: {
  manifest: true,
  sourcemap: true,
  isDynamicEntry: true,
  rollupOptions: {
    output: {
      // 直接使用Rollup内置占位符，无需箭头函数（自定义逻辑除外）
      chunkFileNames: 'assets/[name].[hash].js',
      entryFileNames: '[name].[hash].js',
      assetFileNames: '[name].[hash][extname]',
      // 如需自定义哈希长度，可写成[hash:8]
      // chunkFileNames: 'assets/[name].[hash:8].js',
    },
  },
},

若必须用箭头函数，需接收chunk参数并使用内置哈希：

chunkFileNames: (chunkInfo) => `assets/${chunkInfo.name}.${chunkInfo.hash}.js`,

2. 配置VitePWA缓存策略，避免缓存旧index.html

VitePWA默认会缓存静态资源，需确保不对index.html设置永久缓存，同时开启自动更新：

VitePWA({
  registerType: 'autoUpdate',
  manifest: { name: 'Strategy in Action', theme_color: '#2f80ed' },
  workbox: {
    // 排除index.html，避免被Service Worker缓存
    exclude: ['index.html'],
    // 配置缓存策略：哈希资源长期缓存，index.html仅短期缓存
    runtimeCaching: [
      {
        urlPattern: /^.*\.(js|css|png|svg)$/,
        handler: 'CacheFirst',
        options: {
          cacheName: 'static-assets-cache',
          expiration: {
            maxEntries: 50,
            maxAgeSeconds: 30 * 24 * 60 * 60, // 30天
          },
        },
      },
      {
        urlPattern: /^\/$/, // 匹配首页index.html
        handler: 'NetworkFirst',
        options: {
          cacheName: 'index-html-cache',
          expiration: {
            maxAgeSeconds: 60, // 仅缓存1分钟，强制频繁检查更新
          },
        },
      },
    ],
  },
}),

3. 生产服务器配置：禁止index.html强缓存

部署到生产服务器时，需为index.html设置协商缓存，避免浏览器缓存旧文件：

• Nginx示例配置：

location = /index.html {
  add_header Cache-Control "no-cache, no-store, must-revalidate";
  add_header Pragma "no-cache";
  add_header Expires 0;
}
# 哈希资源可设置强缓存
location ~* \.(js|css|png|svg)$ {
  add_header Cache-Control "public, max-age=31536000, immutable";
}

• Apache示例配置：

<FilesMatch "index\.html">
  Header set Cache-Control "no-cache, no-store, must-revalidate"
  Header set Pragma "no-cache"
  Header set Expires 0
</FilesMatch>
<FilesMatch "\.(js|css|png|svg)$">
  Header set Cache-Control "public, max-age=31536000, immutable"
</FilesMatch>

4. 清理冗余配置

Vite中baseUrl是已废弃的配置，只需保留base: './'即可，移除baseUrl: './'。

验证步骤 #

1. 删除旧的dist目录，执行vite build重新构建
2. 运行vite preview，用隐私窗口（规避浏览器缓存）访问http://localhost:4173/，检查是否正常加载
3. 部署到生产服务器后，同样用隐私窗口测试，确认首次加载无白屏和404

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