PWA离线缓存不生效，刷新就白屏怎么办？

书生シ春艳提问于 2026-03-27 14:55:21 阅读 12

移动

我用 Create React App 搭了个 PWA 应用，本地测试时 service worker 注册成功了，但一断网刷新页面就白屏，资源根本没被缓存下来。是不是哪里配置错了？

我试过在 index.js 里调用 register()，也确认 workbox 被引入了，但离线完全不能用：

import { register } from './serviceWorkerRegistration';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<App />);

// 注册 service worker
register({
  onSuccess: () => console.log('SW registered'),
  onUpdate: () => console.log('SW updated')
});

是不是还需要手动配置缓存策略？现在连首页 HTML 都加载不出来……

我来解答赞 3 收藏

反馈

1 条解答

欧阳静依 Lv1

看起来你遇到了PWA缓存配置的问题。别担心，我来帮你一步步排查和解决。

第一步是确认你的 serviceWorkerRegistration.js 文件配置是否正确。这个文件通常会包含 Workbox 的配置，用来定义哪些资源需要被缓存。

import { registerRoute } from 'workbox-routing';

import { CacheFirst, StaleWhileRevalidate } from 'workbox-strategies';

import { precacheAndRoute } from 'workbox-precaching';



// 这行代码很重要，确保生成的 manifest 被预缓存

precacheAndRoute(self.__WB_MANIFEST);



// 缓存策略：首页使用Cache First策略

registerRoute(

  ({ request }) => request.mode === 'navigate',

  new CacheFirst({

    cacheName: 'html-cache',

    plugins: [

      new workbox.expiration.Plugin({

        maxEntries: 1,

      }),

    ],

  })

);



// 其他静态资源使用Stale While Revalidate策略

registerRoute(

  /.(?:js|css)$/,

  new StaleWhileRevalidate({

    cacheName: 'assets-cache',

  })

);

第二步是要确认在开发模式下 service worker 是否正常工作。Create React App 默认在开发环境禁用了 PWA 功能，你需要修改 src/index.js 来强制启用：

// 修改这个 import 语句

import { register } from './serviceWorkerRegistration';



const root = ReactDOM.createRoot(document.getElementById('root'));

root.render();



// 注册 service worker，并设置 dev 模式也开启

register({ 

  onUpdate: () => {

    if (navigator.serviceWorker) {

      navigator.serviceWorker.getRegistration().then(registration => {

        if (registration && registration.waiting) {

          registration.waiting.postMessage({ type: 'SKIP_WAITING' });

        }

      });

    }

  },

  skipWaiting: true // 强制更新 SW

});

这里的关键是 skipWaiting: true，这可以保证每次更新时立即生效，而不是等到所有标签页关闭。

第三步要检查 Chrome DevTools 的 Application 标签页里 service worker 的状态。确保它已注册并处于 active 状态。如果还是有问题，尝试清除所有站点数据再重试。

原理上，PWA 需要明确告诉浏览器哪些资源要缓存、用什么策略缓存。默认情况下，只有打包进 manifest 的资源会被缓存。所以我们要手动为 HTML 页面添加缓存规则。

最后吐槽一句，PWA 确实是个好东西，但调试起来真挺头疼的。特别是开发环境下各种奇怪的问题，我都经历过...希望能帮到你！

2026-03-27 15:02