React应用离线刷新时显示自定义离线页面的实现方法

要解决离线刷新无法加载应用的问题，核心是让应用具备离线缓存能力——通过Service Worker实现PWA（渐进式Web应用）特性，确保关键资源在离线时能从本地缓存读取，这样应用就能正常加载，再通过react-use-is-online检测状态显示自定义提示。

步骤1：添加Service Worker缓存核心资源 #

在项目根目录创建service-worker.js，用来缓存HTML、JS、CSS等必须资源：

const CACHE_NAME = 'offline-app-cache-v1';
// 按需添加你的静态资源路径，比如打包后的JS、CSS文件
const ASSETS_TO_CACHE = [
  '/',
  '/index.html'
];

// 安装阶段缓存资源
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then(cache => cache.addAll(ASSETS_TO_CACHE))
      .then(() => self.skipWaiting())
  );
});

// 激活阶段清理旧缓存
self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then(cacheNames => {
      return Promise.all(
        cacheNames.filter(name => name !== CACHE_NAME)
          .map(name => caches.delete(name))
      );
    }).then(() => self.clients.claim())
  );
});

// 拦截请求，优先从缓存读取
self.addEventListener('fetch', (event) => {
  if (event.request.method !== 'GET') return;

  event.respondWith(
    caches.match(event.request)
      .then(cachedResponse => {
        // 有缓存直接返回，无缓存则尝试网络请求
        return cachedResponse || fetch(event.request)
          .then(networkResponse => {
            // 把新请求的资源存入缓存（可选）
            caches.open(CACHE_NAME)
              .then(cache => cache.put(event.request, networkResponse.clone()));
            return networkResponse;
          })
          // 网络请求失败时返回缓存的首页
          .catch(() => caches.match('/'));
      })
  );
});

步骤2：在React应用中注册Service Worker #

在入口文件（如index.js）中添加注册逻辑：

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/service-worker.js')
      .then(reg => console.log('Service Worker 注册成功:', reg.scope))
      .catch(err => console.log('Service Worker 注册失败:', err));
  });
}

步骤3：适配项目打包配置（以Create React App为例） #

如果用Create React App开发：

• 生产环境默认支持Service Worker注册，开发环境可在Chrome DevTools的Application > Service Workers中勾选Offline测试离线状态
• 若需自定义缓存策略，可安装workbox-webpack-plugin扩展配置

步骤4：保留原有的离线提示逻辑 #

你的react-use-is-online检测逻辑可以直接复用，应用离线加载后，它依然能正确识别网络状态：

import { useIsOnline } from 'react-use-is-online';

function App() {
  const isOnline = useIsOnline();

  return (
    <div>
      {!isOnline && <div className="offline-tip">当前处于离线状态，请检查网络连接</div>}
      {/* 应用其他内容 */}
    </div>
  );
}

关键注意事项 #

• 缓存列表维护：确保ASSETS_TO_CACHE包含所有启动应用必须的静态资源，避免漏缓存导致加载失败
• HTTPS要求：Service Worker仅支持HTTPS环境（localhost开发环境除外），部署时需确保服务器配置HTTPS
• 缓存版本管理：更新缓存时需修改CACHE_NAME，避免旧缓存干扰新资源加载

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