React+Vite应用推送更新后首次加载失败，求解决方案

问题成因 #

这是浏览器缓存旧的index.html导致的。Vite打包时会给静态资源文件名加上唯一哈希（比如index-b9f535df.js），更新后新资源的哈希会变化，但用户浏览器缓存了旧的index.html，里面引用的还是旧哈希的脚本。而旧脚本已经被替换删除，服务器找不到文件时会默认返回index.html（MIME类型为text/html），但脚本标签要求加载的是JavaScript模块，因此触发MIME类型不匹配的错误。刷新页面后，浏览器会重新请求最新的index.html，自然就能加载到新的脚本文件。

基础解决：缓存策略优化 #

1. 服务器端配置缓存规则 #

核心思路是：给/assets/目录下的静态资源设置长期缓存（因为哈希唯一，内容变哈希就变，不会出现缓存脏数据）；而index.html必须设置禁止缓存或短时间缓存，确保用户每次请求都能拿到最新的入口文件。

以Nginx为例，配置示例如下：

# 静态资源长期缓存
location /assets/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

# 入口文件禁止缓存
location / {
    expires -1;
    add_header Cache-Control "no-cache, no-store, must-revalidate";
    try_files $uri $uri/ /index.html;
}

其他服务器（Apache、Netlify、Vercel等）对应调整缓存配置即可，核心逻辑一致。

2. 确认Vite打包配置 #

Vite默认已经开启静态资源哈希命名，但可以显式配置确保生效，修改vite.config.js：

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

export default defineConfig({
  plugins: [react()],
  build: {
    rollupOptions: {
      output: {
        assetFileNames: 'assets/[name]-[hash][extname]',
        chunkFileNames: 'assets/[name]-[hash].js',
        entryFileNames: 'assets/[name]-[hash].js',
      },
    },
  },
});

进阶：实现自动检测更新并刷新 #

如果想让应用自动识别更新，无需用户手动刷新，可以加入版本检测逻辑：

1. 构建时生成版本标识 #

在Vite构建完成后，生成一个包含版本信息的version.json文件，比如用时间戳或Git Commit Hash作为版本标识：
修改vite.config.js，添加构建钩子：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import fs from 'fs';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  build: {
    rollupOptions: {
      output: {
        assetFileNames: 'assets/[name]-[hash][extname]',
        chunkFileNames: 'assets/[name]-[hash].js',
        entryFileNames: 'assets/[name]-[hash].js',
      },
    },
    onEnd: () => {
      // 用当前时间戳作为版本，也可以替换成git commit hash
      const version = Date.now().toString();
      fs.writeFileSync(
        path.resolve(__dirname, 'dist/version.json'),
        JSON.stringify({ version })
      );
    },
  },
});

2. 应用内检测版本并触发更新 #

在React根组件中，定时请求version.json，对比本地存储的版本号，不一致则提示用户刷新或自动刷新：

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    const checkForUpdate = async () => {
      try {
        const res = await fetch('/version.json');
        const { version } = await res.json();
        const storedVersion = localStorage.getItem('appVersion');

        if (storedVersion && storedVersion !== version) {
          if (confirm('应用有更新，点击确定刷新获取最新版本！')) {
            window.location.reload(true);
          }
        } else if (!storedVersion) {
          localStorage.setItem('appVersion', version);
        }
      } catch (err) {
        console.error('检测更新失败:', err);
      }
    };

    // 页面加载时检测一次
    checkForUpdate();
    // 每5分钟检测一次，可按需调整间隔
    const checkInterval = setInterval(checkForUpdate, 5 * 60 * 1000);

    return () => clearInterval(checkInterval);
  }, []);

  return (
    <div className="App">
      {/* 你的应用内容 */}
    </div>
  );
}

export default App;

3. 更流畅的更新：使用Service Worker #

如果需要无感知更新体验，可以用vite-plugin-pwa插件生成Service Worker，自动缓存新资源并处理更新：

首先安装插件：

npm install vite-plugin-pwa --save-dev

修改vite.config.js配置：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { VitePWA } from 'vite-plugin-pwa';

export default defineConfig({
  plugins: [
    react(),
    VitePWA({
      registerType: 'autoUpdate',
      workbox: {
        globPatterns: ['**/*.{js,css,html,ico,png,svg}'],
      },
      manifest: {
        name: '你的应用名称',
        short_name: '应用简称',
        start_url: '/',
        display: 'standalone',
        background_color: '#ffffff',
        theme_color: '#41b883',
        icons: [
          {
            src: 'icon-192x192.png',
            sizes: '192x192',
            type: 'image/png',
          },
          {
            src: 'icon-512x512.png',
            sizes: '512x512',
            type: 'image/png',
          },
        ],
      },
    }),
  ],
});

这个插件会自动生成Service Worker，当检测到新构建时，会自动缓存新资源，并可配置为自动刷新或提示用户，实现更流畅的更新体验。

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