React单页应用集成Workbox后index.html预缓存旧版本问题求助

这个问题我在帮React项目做PWA优化时碰到过好多次，本质是预缓存的index.html没有和Service Worker的更新机制绑定起来。因为你用了带哈希后缀的JS文件，新版本发布后旧的index.html还在引用过时的JS文件名，而控制页面的旧Service Worker又不肯“让位”，自然就会出现找不到文件的错误。下面是我总结的几个靠谱解决步骤：

1. 调整workbox-build配置，确保SW能及时更新 #

首先检查你的generateSW或injectManifest配置，一定要开启skipWaiting和clientsClaim，这两个选项能让新的Service Worker安装完成后立即激活，接管所有打开的页面，而不是等用户关闭所有页面再生效。同时要确保index.html被包含在预缓存列表里：

const { generateSW } = require('workbox-build');

generateSW({
  globDirectory: 'build/',
  globPatterns: [
    'index.html',
    'static/js/*.js',
    'static/css/*.css',
    // 其他需要预缓存的静态资源
  ],
  swDest: 'build/sw.js',
  // 关键配置，让新SW立即接管
  skipWaiting: true,
  clientsClaim: true,
}).then(({ warnings }) => {
  warnings.forEach(warn => console.warn(warn));
  console.log('Service Worker 生成成功');
});

2. 给index.html添加版本标识，触发SW的更新检测 #

因为index.html本身没有像JS/CSS那样的哈希后缀，workbox默认可能检测不到它的内容变化。你可以在构建时给index.html注入一个唯一的版本标识，比如git commit哈希或者时间戳：

在public/index.html里添加一个meta标签：

<meta name="build-revision" content="%REACT_APP_BUILD_REV%">

然后在构建脚本里设置这个环境变量（比如在package.json的scripts里）：

{
  "scripts": {
    "build": "REACT_APP_BUILD_REV=$(git rev-parse --short HEAD) react-scripts build && workbox generateSW workbox-config.js"
  }
}

这样每次构建时，index.html的内容都会有变化，workbox生成预缓存清单时就会给它分配新的revision值，从而触发Service Worker的更新。

3. 在React应用中添加SW更新提示 #

即使新的Service Worker已经安装，用户当前打开的页面还是由旧SW控制的，所以需要在应用里主动检测更新并提示用户刷新：

在你的根组件（比如App.js）里添加这个逻辑：

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    if ('serviceWorker' in navigator) {
      navigator.serviceWorker.register('/sw.js')
        .then(reg => {
          reg.addEventListener('updatefound', () => {
            const newWorker = reg.installing;
            newWorker.addEventListener('statechange', () => {
              if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
                // 这里可以换成更友好的UI提示，比如一个弹窗
                if (confirm('发现新版本，刷新页面获取最新内容？')) {
                  window.location.reload();
                }
              }
            });
          });
        });
    }
  }, []);

  // 其他组件内容...
}

export default App;

4. 验证预缓存清单 #

构建完成后，打开build/sw.js，找到self.__WB_MANIFEST数组，检查index.html的revision值是否每次构建都不一样。如果这个值固定不变，说明workbox没检测到index.html的变化，你需要回头检查globPatterns或者版本标识的注入是否正确。

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