React应用断网怎么办？如何用Service Worker拦截请求并显示离线提示页面

在现代Web应用中，网络连接的不稳定性是影响用户体验的关键因素之一。当用户在移动网络信号较弱或完全断网的环境下操作React应用时，如果没有做离线处理，页面往往会卡死在加载状态或者直接抛出未经处理的网络错误，导致应用不可用。为了解决这个问题，我们可以引入Service Worker作为浏览器与网络之间的代理层，拦截失败的请求并在React应用中渲染一个友好的离线提示页面，从而保证应用在极端网络条件下的可用性与交互完整性。

Service Worker在React应用中的注册与生命周期

Service Worker是一种在浏览器后台独立于网页运行的脚本，它充当了浏览器与网络之间的拦截器。在React应用中集成离线功能的第一步，就是正确地注册Service Worker。Service Worker的生命周期包含安装、激活和运行三个主要阶段。在安装阶段，我们通常需要预缓存一些静态资源或离线页面的HTML片段；在激活阶段，则可以清理旧的缓存；而在运行阶段，它将监听并拦截页面的网络请求。

在React项目中，通常会在应用的入口文件中进行注册。需要注意的是，Service Worker只能在安全上下文（HTTPS或localhost）中运行，并且它的注册是异步的。我们可以编写一个独立的注册函数，在主组件挂载完成后调用它。通过判断环境变量来决定是否注册，可以避免在开发环境下因为缓存导致代码更新不生效的问题。

下面是在React入口文件中注册Service Worker的示例代码。我们将注册逻辑封装在一个函数中，并在其中处理了注册失败和更新found的情况，确保应用主线程的加载不会被阻塞。

export function registerServiceWorker() {
  if ('serviceWorker' in navigator) {
    window.addEventListener('load', () => {
      const swUrl = `${process.env.PUBLIC_URL}/service-worker.js`;
      navigator.serviceWorker.register(swUrl)
        .then(registration => {
          console.log('ServiceWorker registration successful');
        })
        .catch(error => {
          console.error('ServiceWorker registration failed:', error);
        });
    });
  }
}

拦截网络请求与离线状态判断

注册完成后，Service Worker就可以开始工作了。要实现离线提示，核心在于拦截fetch事件。当页面发起网络请求时，Service Worker可以通过监听fetch事件来决定是直接从网络获取，还是从缓存读取，亦或是返回一个离线降级响应。对于离线场景的处理，我们需要区分静态资源请求和API数据请求。

对于静态资源，如果请求失败且缓存中没有匹配项，可以返回一个自定义的离线页面。对于API请求，如果网络断开，应该返回一个带有特定状态码或标识的Response对象，这样前端的React代码就能识别出这是离线状态，进而触发UI更新。在拦截请求时，我们可以利用navigator.onLine属性作为初步判断，但更可靠的方式是直接捕获fetch的异常，因为在某些弱网环境下，navigator.onLine可能仍为true，但请求实际已经超时失败。

在下面的Service Worker代码示例中，我们监听了fetch事件。当检测到网络请求失败时，如果是页面导航请求，我们会返回一个预缓存的离线提示页面；如果是接口请求，则返回一个状态码为503的Response，并在Header中标记离线状态。

self.addEventListener('fetch', (event) => {
  const { request } = event;
  
  // 处理页面导航请求
  if (request.mode === 'navigate') {
    event.respondWith(
      fetch(request)
        .catch(() => {
          // 网络断开时返回离线页面
          return caches.match('/offline.html');
        })
    );
    return;
  }

  // 处理API数据请求
  if (request.url.includes('/api/')) {
    event.respondWith(
      fetch(request)
        .catch(() => {
          // 返回自定义离线响应
          return new Response(JSON.stringify({ error: 'offline' }), {
            status: 503,
            headers: { 'Content-Type': 'application/json', 'X-Offline': 'true' }
          });
        })
    );
  }
});

结合React组件实现动态离线提示UI

虽然Service Worker可以拦截请求并返回离线页面，但在单页应用（SPA）中，直接跳转到一个静态HTML会破坏React的状态和路由。更好的方案是让React应用自己管理离线状态，通过监听网络状态变化和拦截API错误，动态渲染一个离线提示组件，而不是强制刷新页面。

在React中，我们可以创建一个自定义Hook，比如useOnlineStatus，来统一管理网络状态。这个Hook不仅监听浏览器的online和offline事件，还可以结合Service Worker拦截返回的特定响应头（如前面定义的X-Offline）来判断应用是否处于离线状态。当检测到离线时，React组件可以在当前页面上覆盖显示一个半透明的提示层，而不是渲染一个全新的<div>容器，这样既不打断用户的操作流程，又能提供清晰的反馈。

下面是一个React离线提示组件的实现示例。我们通过监听window对象的online和offline事件来更新状态，并在组件卸载时移除监听器。当isOnline状态为false时，渲染一个绝对定位的提示框，这样既不打断用户的操作流程，又能提供清晰的反馈。

import { useState, useEffect } from 'react';

function useOnlineStatus() {
  const [isOnline, setIsOnline] = useState(navigator.onLine);

  useEffect(() => {
    const handleOnline = () => setIsOnline(true);
    const handleOffline = () => setIsOnline(false);

    window.addEventListener('online', handleOnline);
    window.addEventListener('offline', handleOffline);

    return () => {
      window.removeEventListener('online', handleOnline);
      window.removeEventListener('offline', handleOffline);
    };
  }, []);

  return isOnline;
}

function OfflineNotification() {
  const isOnline = useOnlineStatus();

  if (isOnline) return null;

  return (
    <div style={{ position: 'fixed', top: 0, left: 0, right: 0, padding: '10px', backgroundColor: '#ffcc00', textAlign: 'center', zIndex: 9999 }}>
      <strong>网络连接已断开</strong>，请检查您的网络设置，应用将在恢复连接后继续工作。
    </div>
  );
}

通过这种分层设计，Service Worker负责底层的网络拦截与降级响应，而React组件则负责上层的状态同步与UI渲染。两者协同工作，既保证了应用在断网时的稳定性，又为用户提供了流畅且友好的交互体验。在实际项目中，还可以进一步扩展，比如在离线状态下将用户操作存入队列，待网络恢复后自动重试，从而实现真正的离线优先架构。

React离线页面Service Worker请求拦截修改时间：2026-08-30 06:00:42