Workbox与Create React App无法加载新版index.html的解决方案咨询

• 使用create-react-app my-app --template cra-template-pwa-typescript初始化PWA项目
• 保留模板中precacheAndRoute(self.__WB_MANIFEST)代码
• 部署在AWS S3上
• 核心问题：Service Worker无法检测React应用及index.html更新，经排查是Workbox未给index.html生成新的__WB_REVISION后缀
• 已尝试操作：移除Workbox预缓存、Chrome控制台注销Workbox、重新加载页面注册新版缓存

一、让index.html每次构建生成新__WB_REVISION后缀 #

CRA默认不对index.html添加哈希后缀，但可以通过自定义Workbox配置让其生成基于内容或依赖资源的revision：

1. 使用react-app-rewired自定义Workbox配置（无需eject） #

• 安装依赖：

  npm install react-app-rewired customize-cra --save-dev
  

• 在项目根目录创建config-overrides.js：

  const { override, adjustWorkbox } = require('customize-cra');
  
  module.exports = override(
    adjustWorkbox(wbConfig => {
      // 让index.html的revision依赖于打包后的JS/CSS资源（这些资源带哈希）
      wbConfig.templatedUrls = {
        'index.html': ['./static/js/*.js', './static/css/*.css']
      };
      // 确保index.html被纳入预缓存清单
      wbConfig.globPatterns.push('index.html');
      wbConfig.globIgnores = wbConfig.globIgnores.filter(pattern => pattern !== 'index.html');
      return wbConfig;
    })
  );
  

• 修改package.json的scripts命令，替换为react-app-rewired启动：

  "scripts": {
    "start": "react-app-rewired start",
    "build": "react-app-rewired build",
    "test": "react-app-rewired test",
    "eject": "react-scripts eject"
  }
  

• 原理：通过templatedUrls让index.html的revision关联到带哈希的JS/CSS资源，只要这些资源更新，index.html的revision就会同步变化，触发Workbox的预缓存更新。

2. Eject后直接修改Workbox配置（不推荐，不可逆） #

如果已eject项目，可在config/webpack.config.js中找到Workbox相关配置，添加index.html的处理逻辑，强制生成内容哈希作为revision：

// 找到WorkboxWebpackPlugin的配置部分
new WorkboxWebpackPlugin.InjectManifest({
  swSrc: './src/service-worker.js',
  swDest: 'service-worker.js',
  // 添加index.html到预缓存并计算内容哈希
  include: [/\.html$/, /\.js$/, /\.css$/],
  // 自定义revision生成
  manifestTransforms: [
    (manifestEntries) => {
      const updatedEntries = manifestEntries.map(entry => {
        if (entry.url === 'index.html') {
          // 基于文件内容生成哈希作为revision
          const fs = require('fs');
          const content = fs.readFileSync(path.resolve(__dirname, '../public/index.html'), 'utf8');
          const hash = require('crypto').createHash('md5').update(content).digest('hex');
          return { ...entry, revision: hash };
        }
        return entry;
      });
      return { manifest: updatedEntries, warnings: [] };
    }
  ]
})

二、强制加载新版index.html的方法（从非友好到友好） #

非用户友好方案（临时应急） #

• 手动清除浏览器缓存：告知用户清除Chrome的“缓存的图片和文件”后刷新页面，仅适合临时测试或小范围用户。
• DevTools强制更新：在Chrome DevTools的Application > Service Workers中勾选Update on reload，点击Unregister后刷新页面，仅开发者可用。

半用户友好方案（手动版本控制） #

在public/index.html中添加版本标识meta标签，每次构建手动更新版本号：

<meta name="app-version" content="v2.0.0">

然后在service-worker.js中添加fetch监听，对比版本号更新缓存：

self.addEventListener('fetch', (event) => {
  if (event.request.mode === 'navigate') {
    event.respondWith(
      Promise.all([
        fetch(event.request),
        caches.open('static-cache')
      ]).then(([networkResponse, cache]) => {
        return networkResponse.text().then(newHtml => {
          const newVersion = newHtml.match(/<meta name="app-version" content="(.*?)"/)?.[1] || '';
          return cache.match(event.request).then(cachedResponse => {
            if (!cachedResponse) {
              cache.put(event.request, networkResponse.clone());
              return networkResponse;
            }
            return cachedResponse.text().then(oldHtml => {
              const oldVersion = oldHtml.match(/<meta name="app-version" content="(.*?)"/)?.[1] || '';
              if (newVersion !== oldVersion) {
                cache.put(event.request, networkResponse.clone());
                return networkResponse;
              }
              return cachedResponse;
            });
          });
        });
      })
    );
  }
});

用户友好方案（生产推荐） #

1. 监听Service Worker更新并提示用户刷新

在src/index.tsx中修改Service Worker注册逻辑，添加更新提示：

import * as serviceWorkerRegistration from './service-worker-registration';

serviceWorkerRegistration.register({
  onUpdate: (registration) => {
    if (confirm('发现应用新版本，点击确定刷新更新')) {
      registration.waiting?.postMessage({ type: 'SKIP_WAITING' });
      window.location.reload();
    }
  },
});

在src/service-worker.js中添加消息监听，触发SW激活：

self.addEventListener('message', (event) => {
  if (event.data?.type === 'SKIP_WAITING') {
    self.skipWaiting();
  }
});

原理：当Workbox检测到预缓存清单更新（包括index.html的新revision），会触发onUpdate回调，提示用户确认后激活新版SW并刷新页面，加载最新index.html。

2. 配置AWS S3缓存策略

确保index.html的缓存策略为短时效，强制浏览器每次请求时验证最新版本：

• 在S3控制台找到index.html文件，设置元数据：Cache-Control: no-cache, must-revalidate
• 若使用CloudFront，对index.html路径设置缓存行为：
  • 缓存策略选择“Cache based on selected request headers”，勾选Origin
  • 设置TTL为0，确保每次请求都回源S3获取最新内容

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