React项目构建部署后旧标签页空白问题求助

核心原因 #

浏览器缓存了旧的index.html文件，该文件里引用的是旧版本的chunk文件名（React构建时会给chunk加哈希值，新版本哈希不同），部署后旧chunk已被移除，导致加载失败；刷新页面时浏览器会重新请求最新的index.html，从而加载正确的新chunk。

具体解决方案 #

• 配置服务器缓存策略：
  给index.html设置不缓存或短缓存时间，以Nginx为例，配置如下：

  location / {
    try_files $uri $uri/ /index.html;
    add_header Cache-Control "no-cache, no-store, must-revalidate";
    add_header Pragma "no-cache";
    add_header Expires 0;
  }
  

  对于带哈希的静态资源（js、css、图片等），可以设置长缓存时间：

  location ~* \.(js|css|png|jpg|jpeg|gif|ico)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
  }
  

• 添加版本检测与自动刷新：
  在项目中加入版本校验逻辑，自动触发页面更新：

  1. 在public/index.html添加版本标识meta标签：

  <meta name="app-version" content="%REACT_APP_VERSION%">
  

  2. 在.env文件设置版本号，每次部署更新该值：

  REACT_APP_VERSION=1.0.1
  

  3. 在App组件中加入校验逻辑：

  useEffect(() => {
    const currentVersion = document.querySelector('meta[name="app-version"]').content;
    const storedVersion = localStorage.getItem('app-version');
    
    if (storedVersion && storedVersion !== currentVersion) {
      localStorage.setItem('app-version', currentVersion);
      window.location.reload(true);
    } else {
      localStorage.setItem('app-version', currentVersion);
    }
  }, []);
  

• 利用Service Worker强制更新：
  若项目使用PWA功能，修改Service Worker逻辑实现自动更新：

  1. 在src/service-worker.js中更新激活与安装逻辑：

  self.addEventListener('install', (event) => {
    event.waitUntil(
      caches.open('app-cache').then(cache => cache.addAll([/* 需缓存的资源列表 */]))
    );
    self.skipWaiting();
  });
  
  self.addEventListener('activate', (event) => {
    event.waitUntil(
      caches.keys().then(cacheNames => 
        Promise.all(
          cacheNames.filter(name => name !== 'app-cache').map(name => caches.delete(name))
        )
      )
    );
    self.clients.claim();
  });
  

  2. 在App组件中监听更新事件：

  useEffect(() => {
    if ('serviceWorker' in navigator) {
      navigator.serviceWorker.register('/service-worker.js').then(registration => {
        registration.addEventListener('updatefound', () => {
          const newWorker = registration.installing;
          newWorker.addEventListener('statechange', () => {
            if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
              window.location.reload(true);
            }
          });
        });
      });
    }
  }, []);
  

临时应急方案 #

如果暂时无法修改配置或代码，可让用户执行强制刷新（Ctrl+F5 / Cmd+Shift+R），但这仅为临时手段，无法从根源解决问题。

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