Create React App中ServiceWorkerRegistration的onUpdate回调未触发问题

问题描述 #

我使用Create React App开发第一个React应用，配置PWA时遇到问题：尝试在新Service Worker注册时显示snackbar，但即使使用模板代码，onUpdate回调始终无法触发，而onSuccess回调正常工作。

相关代码文件 #

./src/service-worker.js（与CRA模板一致）

/* eslint-disable no-restricted-globals */

// This service worker can be customized!
// See https://developers.google.com/web/tools/workbox/modules
// for the list of available Workbox modules, or add any other
// code you'd like.
// You can also remove this file if you'd prefer not to use a
// service worker, and the Workbox build step will be skipped.

import { clientsClaim } from 'workbox-core';
import { ExpirationPlugin } from 'workbox-expiration';
import { precacheAndRoute, createHandlerBoundToURL } from 'workbox-precaching';
import { registerRoute } from 'workbox-routing';
import { StaleWhileRevalidate } from 'workbox-strategies';

clientsClaim();

// Precache all of the assets generated by your build process.
// Their URLs are injected into the manifest variable below.
// This variable must be present somewhere in your service worker file,
// even if you decide not to use precaching. See https://cra.link/PWA
precacheAndRoute(self.__WB_MANIFEST);

// Set up App Shell-style routing, so that all navigation requests
// are fulfilled with your index.html shell. Learn more at
// https://developers.google.com/web/fundamentals/architecture/app-shell
const fileExtensionRegexp = new RegExp('/[^/?]+\\.[^/]+$');
registerRoute(
  // Return false to exempt requests from being fulfilled by index.html.
  ({ request, url }) => {
    // If this isn't a navigation, skip.
    if (request.mode !== 'navigate') {
      return false;
    } // If this is a URL that starts with /_, skip.

    if (url.pathname.startsWith('/_')) {
      return false;
    } // If this looks like a URL for a resource, because it contains // a file extension, skip.

    if (url.pathname.match(fileExtensionRegexp)) {
      return false;
    } // Return true to signal that we want to use the handler.

    return true;
  },
  createHandlerBoundToURL(process.env.PUBLIC_URL + '/index.html')
);

// An example runtime caching route for requests that aren't handled by the
// precache, in this case same-origin .png requests like those from in public/
registerRoute(
  // Add in any other file extensions or routing criteria as needed.
  ({ url }) => url.origin === self.location.origin && url.pathname.endsWith('.png'), // Customize this strategy as needed, e.g., by changing to CacheFirst.
  new StaleWhileRevalidate({
    cacheName: 'images',
    plugins: [
      // Ensure that once this runtime cache reaches a maximum size the
      // least-recently used images are removed.
      new ExpirationPlugin({ maxEntries: 50 }),
    ],
  })
);

// This allows the web app to trigger skipWaiting via
// registration.waiting.postMessage({type: 'SKIP_WAITING'})
self.addEventListener('message', (event) => {
  if (event.data && event.data.type === 'SKIP_WAITING') {
    self.skipWaiting();
  }
});

// Any other custom service worker logic can go here.

./src/utils/serviceWorkerRegistration.js（仅修改位置和一条console.log）

// This optional code is used to register a service worker.
// register() is not called by default.

// This lets the app load faster on subsequent visits in production, and gives
// it offline capabilities. However, it also means that developers (and users)
// will only see deployed updates on subsequent visits to a page, after all the
// existing tabs open on the page have been closed, since previously cached
// resources are updated in the background.

// To learn more about the benefits of this model and instructions on how to
// opt-in, read https://cra.link/PWA

const isLocalhost = Boolean(
  window.location.hostname === 'localhost' ||
    // [::1] is the IPv6 localhost address.
    window.location.hostname === '[::1]' ||
    // 127.0.0.0/8 are considered localhost for IPv4.
    window.location.hostname.match(/^127(?:\\.(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)){3}$/)
);

export function register(config) {
  if (process.env.NODE_ENV === 'production' && 'serviceWorker' in navigator) {
    // The URL constructor is available in all browsers that support SW.
    const publicUrl = new URL(process.env.PUBLIC_URL, window.location.href);
    if (publicUrl.origin !== window.location.origin) {
      // Our service worker won't work if PUBLIC_URL is on a different origin
      // from what our page is served on. This might happen if a CDN is used to
      // serve assets; see https://github.com/facebook/create-react-app/issues/2374
      return;
    }

    window.addEventListener('load', () => {
      const swUrl = `${process.env.PUBLIC_URL}/service-worker.js`;

      if (isLocalhost) {
        // This is running on localhost. Let's check if a service worker still exists or not.
        checkValidServiceWorker(swUrl, config);

        // Add some additional logging to localhost, pointing developers to the
        // service worker/PWA documentation.
        navigator.serviceWorker.ready.then(() => {
          console.log(
            'This web app is being served cache-first by a service ' +
              'worker. To learn more, visit https://cra.link/PWA'
          );
        });
      } else {
        // Is not localhost. Just register service worker
        registerValidSW(swUrl, config);
      }
    });
  }
}

function registerValidSW(swUrl, config) {
  navigator.serviceWorker
    .register(swUrl)
    .then((registration) => {
      registration.onupdatefound = () => {
        const installingWorker = registration.installing;
        if (installingWorker == null) {
          return;
        }
        installingWorker.onstatechange = () => {
          if (installingWorker.state === 'installed') {
            if (navigator.serviceWorker.controller) {
              // At this point, the updated precached content has been fetched,
              // but the previous service worker will still serve the older
              // content until all client tabs are closed.
              console.log(
                'New content is available! Click the pop-up notification to update it!'
              );

              // Execute callback
              if (config && config.onUpdate) {
                config.onUpdate(registration);
              }
            } else {
              // At this point, everything has been precached.
              // It's the perfect time to display a
              // "Content is cached for offline use." message.
              console.log('Content is cached for offline use.');

              // Execute callback
              if (config && config.onSuccess) {
                config.onSuccess(registration);
              }
            }
          }
        };
      };
    })
    .catch((error) => {
      console.error('Error during service worker registration:', error);
    });
}

function checkValidServiceWorker(swUrl, config) {
  // Check if the service worker can be found. If it can't reload the page.
  fetch(swUrl, {
    headers: { 'Service-Worker': 'script' },
  })
    .then((response) => {
      // Ensure service worker exists, and that we really are getting a JS file.
      const contentType = response.headers.get('content-type');
      if (
        response.status === 404 ||
        (contentType != null && contentType.indexOf('javascript') === -1)
      ) {
        // No service worker found. Probably a different app. Reload the page.
        navigator.serviceWorker.ready.then((registration) => {
          registration.unregister().then(() => {
            window.location.reload();
          });
        });
      } else {
        // Service worker found. Proceed as normal.
        registerValidSW(swUrl, config);
      }
    })
    .catch(() => {
      console.log('No internet connection found. App is running in offline mode.');
    });
}

export function unregister() {
  if ('serviceWorker' in navigator) {
    navigator.serviceWorker.ready
      .then((registration) => {
        registration.unregister();
      })
      .catch((error) => {
        console.error(error.message);
      });
  }
}

注册Service Worker的useEffect代码

useEffect(() => {
  registerSW({
    onSuccess: () => setShowSuccess(true),
    onUpdate: sw => {
      console.log('onUpdate triggered')
      setShowReload(true)
      setSW(sw)
    },
  });
}, []);

问题分析与解决 #

1. onUpdate的触发时机 #

onUpdate只有在已有激活的Service Worker，且新的Service Worker安装完成但还未激活时才会触发。也就是说：

• 你必须先让浏览器缓存旧版本的SW（部署旧版应用，打开页面完成SW注册激活）
• 然后部署新版本应用（确保SW内容或哈希有变化）
• 再打开旧版本的页面，此时浏览器后台检测到新SW，安装完成后才会触发onUpdate

2. 常见排查点 #

• 测试流程错误：如果直接部署新版本后打开页面，此时没有旧SW存在，只会触发onSuccess，不会触发onUpdate
• 本地测试注意：localhost环境下，CRA会检查SW有效性，但更新触发需要你手动构建新版本，不能依赖hot reload，必须重新build后刷新旧页面
• SW内容无变化：CRA会给SW生成哈希，如果新版本SW内容和旧版完全一致，浏览器会认为是同一个文件，不会触发更新检测

3. 替代实现方案（使用controllerchange事件） #

如果onUpdate还是无法触发，可以直接监听浏览器的controllerchange事件，结合waiting状态的SW实现更新提示：

useEffect(() => {
  let registration;

  async function setupSW() {
    if (process.env.NODE_ENV !== 'production' || !('serviceWorker' in navigator)) return;

    registration = await navigator.serviceWorker.register(`${process.env.PUBLIC_URL}/service-worker.js`);

    // 检查是否有已安装等待激活的SW
    if (registration.waiting) {
      setShowReload(true);
      setSW(registration);
    }

    // 监听新SW安装事件
    registration.addEventListener('updatefound', () => {
      const installingWorker = registration.installing;
      installingWorker.addEventListener('statechange', () => {
        if (installingWorker.state === 'installed' && navigator.serviceWorker.controller) {
          setShowReload(true);
          setSW(registration);
        }
      });
    });

    // 监听SW控制器变化（新SW激活后触发）
    navigator.serviceWorker.addEventListener('controllerchange', () => {
      // 可以自动刷新页面，或者提示用户已更新
      window.location.reload();
    });
  }

  setupSW();

  // 清理监听
  return () => {
    if (registration) {
      registration.removeEventListener('updatefound', () => {});
      navigator.serviceWorker.removeEventListener('controllerchange', () => {});
    }
  };
}, []);

4. 两种方式的区别 #

• CRA模板的onUpdate：封装了updatefound和statechange逻辑，触发时机是新SW安装完成但未激活，适合提示用户手动触发更新（比如发送SKIP_WAITING消息）
• controllerchange事件：触发时机是新SW激活并接管页面后，适合自动刷新页面或提示用户页面已更新

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