React JS如何在Web应用首次加载时编程清理浏览器缓存解决生产更新不生效问题

问题根源 #

你配置的meta缓存标签无效，是因为Web服务器（Nginx/Apache等）返回的HTTP响应头优先级高于页面内的meta标签，浏览器会优先遵循服务器返回的缓存规则。此外你的问题还涉及懒加载分片资源缓存、静态资源文件名未哈希导致的缓存命中、PWA service worker缓存三个常见原因。

解决方案步骤 #

1. 优先配置Web服务器的缓存规则 #

这是最核心的解决方案，不需要前端写额外逻辑就能解决90%的问题，以Nginx为例，添加如下配置：

# 对index.html做不缓存配置
location = /index.html {
    add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate";
    add_header Pragma "no-cache";
    add_header Expires 0;
}

# 带哈希后缀的静态资源配置一年长缓存，因为内容变了文件名会自动变
location ~* \.(js|css|png|jpg|jpeg|gif|svg|ico)$ {
    expires 365d;
    add_header Cache-Control "public, immutable";
}

如果用的是云服务静态托管（比如阿里云OSS、腾讯云COS），直接在后台配置index.html的响应头为上述规则即可。

2. 确认打包配置开启静态资源哈希 #

如果你用的是官方Create React App脚手架，默认已经开启了contenthash，打包后的js/css/图片文件名都会带内容哈希后缀，只要index.html不被缓存，资源更新后会自动拉取最新文件。
如果是自定义webpack配置，确认以下配置：

// webpack.config.js
module.exports = {
  output: {
    filename: '[name].[contenthash].js',
    chunkFilename: '[name].[contenthash].chunk.js',
  },
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif|svg)$/i,
        type: 'asset/resource',
        generator: {
          filename: 'assets/[name].[hash][ext]'
        }
      }
    ]
  }
}

3. 前端添加版本检测逻辑主动刷新 #

如果无法修改服务器配置，可以在前端加版本校验逻辑，实现自动清理缓存刷新：
第一步，每次打包的时候在public目录生成version.json，内容如下，你可以写个简单的node脚本在打包前自动更新版本号：

{
  "version": "1.0.2",
  "buildTime": "2024-05-20 12:00:00"
}

第二步，在App.js的useEffect中添加校验逻辑：

useEffect(() => {
  const checkVersion = async () => {
    try {
      // 加时间戳防止version.json本身被缓存
      const res = await fetch(`/version.json?t=${Date.now()}`);
      const latestVersion = await res.json();
      const localVersion = localStorage.getItem('app_version');
      
      if (localVersion && localVersion !== latestVersion.version) {
        // 版本不一致，清除本地存储缓存
        localStorage.clear();
        sessionStorage.clear();
        // 可选：如果用了service worker，也卸载
        if ('serviceWorker' in navigator) {
          const registrations = await navigator.serviceWorker.getRegistrations();
          for (let registration of registrations) {
            await registration.unregister();
          }
        }
        // 保存新版本号，刷新页面
        localStorage.setItem('app_version', latestVersion.version);
        window.location.reload(true); // 强制绕过缓存刷新
      } else if (!localVersion) {
        localStorage.setItem('app_version', latestVersion.version);
      }
    } catch (e) {
      console.error('版本检测失败', e);
    }
  }
  checkVersion();
  // 原有逻辑保留
  props.onTryAutoSignup();
}, [props.phoneNumber])

4. 处理懒加载异常导致的白屏 #

你用了React.lazy做代码分片，部署后旧版本的分片文件被删除会导致加载失败白屏，可以添加ErrorBoundary捕获这个错误，触发刷新：

class LazyLoadErrorBoundary extends React.Component {
  state = { hasError: false }
  static getDerivedStateFromError() {
    return { hasError: true }
  }
  componentDidCatch(error) {
    if (error.message.includes('Failed to fetch dynamically imported module')) {
      localStorage.clear();
      window.location.reload(true);
    }
  }
  render() {
    if (this.state.hasError) {
      return <div>版本更新中，正在刷新...</div>
    }
    return this.props.children
  }
}
// 然后包裹你的Suspense组件
return (
  <div className="app">
    <LazyLoadErrorBoundary>
      <Suspense fallback={<div style={{ textAlign: "center" }}><img src={LoadingGif} alt="Loading...." /></div>}>
        {/* 原有路由逻辑 */}
      </Suspense>
    </LazyLoadErrorBoundary>
  </div>
)

5. 可选：关闭PWA缓存 #

如果你的项目不需要PWA功能，直接删除index.html里的<link rel="manifest" href="%PUBLIC_URL%/manifest.json">标签，同时在package.json中关闭service worker相关的配置即可，避免service worker缓存静态资源导致更新不生效。

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