断网后 WebView 加载单页面应用：页面跳转 JS 加载失败的处理方案

1. 问题背景

在移动端开发中，WebView 加载单页面应用（SPA）是常见场景。SPA 依赖 JavaScript 动态渲染页面内容，当用户处于断网状态时，页面跳转往往会导致 JS 资源加载失败，进而出现白屏、页面无法切换等问题。本文围绕这一场景，梳理常见原因并给出可落地的处理方案。

2. 问题现象与原因分析

断网后 WebView 加载 SPA 页面跳转失败，通常表现为以下几种现象：

点击页面内链接或按钮后，页面长时间白屏，无任何内容渲染。
控制台报错提示 JS 文件加载失败，如 Failed to load resource: net::ERR_INTERNET_DISCONNECTED。
路由跳转后页面停留在上一个视图，无法切换到目标页面。

产生上述问题的核心原因包括：

资源依赖网络：SPA 的 JS、CSS 等静态资源默认从远程服务器加载，断网后资源请求失败，页面无法完成渲染。
路由懒加载：SPA 常采用路由级代码分割，跳转时按需加载对应 chunk，断网时 chunk 请求失败导致页面空白。
缓存策略缺失：WebView 未配置合理的离线缓存，导致已访问过的资源也无法在断网时复用。
错误处理不完善：前端代码未对资源加载失败做兜底处理，异常被静默吞掉，用户无感知。

3. 整体处理思路

解决断网场景下 SPA 页面跳转失败，需要从资源缓存、离线能力、错误兜底三个层面协同处理。整体思路如下：

通过 WebView 缓存策略和 Service Worker 实现资源离线可用。
对路由懒加载的 chunk 请求做失败拦截与重试。
在页面层面对加载失败做降级提示，避免白屏。

4. 方案一：WebView 缓存策略配置

在原生端（Android / iOS）配置 WebView 缓存模式，让已加载过的静态资源在断网时优先从本地缓存读取。

4.1 Android 端配置

Android 的 WebView 支持通过 WebSettings 设置缓存模式，推荐使用 LOAD_CACHE_ELSE_NETWORK，即优先使用缓存，缓存不存在时才请求网络。

java 复制代码

WebSettings settings = webView.getSettings();
settings.setCacheMode(WebSettings.LOAD_CACHE_ELSE_NETWORK);
settings.setDomStorageEnabled(true);
settings.setAppCacheEnabled(true);
settings.setAppCachePath(getCacheDir().getAbsolutePath());

4.2 iOS 端配置

iOS 的 WKWebView 默认使用系统 URL 缓存，可通过配置 URLCache 提升离线命中率。

swift 复制代码

let cache = URLCache(memoryCapacity: 4 * 1024 * 1024,
                     diskCapacity: 20 * 1024 * 1024,
                     diskPath: nil)
URLCache.shared = cache

需要注意的是，缓存模式只能解决「已访问过」的资源，首次未加载过的资源在断网时依然无法获取，因此需要配合离线包方案。

5. 方案二：Service Worker 离线缓存

Service Worker 是 Web 端实现离线能力的标准方案，可以在浏览器层面拦截网络请求，将静态资源和页面骨架缓存到本地。断网时，SPA 的 HTML、JS、CSS 均可从缓存中读取，页面跳转不再依赖网络。

5.1 注册 Service Worker

javascript 复制代码

if ('serviceWorker' in navigator) {
  window.addEventListener('load', function () {
    navigator.serviceWorker.register('/sw.js').then(function (registration) {
      console.log('Service Worker 注册成功', registration.scope);
    }).catch(function (error) {
      console.log('Service Worker 注册失败', error);
    });
  });
}

5.2 缓存静态资源

javascript 复制代码

const CACHE_NAME = 'spa-cache-v1';
const ASSETS = [
  '/',
  '/index.html',
  '/static/js/main.js',
  '/static/css/main.css'
];

self.addEventListener('install', function (event) {
  event.waitUntil(
    caches.open(CACHE_NAME).then(function (cache) {
      return cache.addAll(ASSETS);
    })
  );
});

5.3 请求拦截与离线回退

javascript 复制代码

self.addEventListener('fetch', function (event) {
  event.respondWith(
    caches.match(event.request).then(function (response) {
      if (response) {
        return response;
      }
      // 网络请求失败时回退到缓存中的 index.html，保证 SPA 路由可跳转
      return fetch(event.request).catch(function () {
        return caches.match('/index.html');
      });
    })
  );
});

这里的关键点是：当某个 chunk 请求失败时，回退到缓存的 index.html，让 SPA 的路由逻辑继续运行，避免白屏。

6. 方案三：路由懒加载失败兜底

SPA 使用路由懒加载时，跳转会动态加载对应 chunk。断网时 chunk 加载失败，需要在前端做兜底处理。

6.1 动态导入失败捕获

javascript 复制代码

const loadPage = (componentPath) => {
  return import(componentPath).catch((error) => {
    console.error('页面组件加载失败', error);
    // 返回一个降级页面组件
    return import('./FallbackPage');
  });
};

6.2 路由级错误处理

在 Vue Router 或 React Router 中，可以监听路由跳转错误并展示降级提示。

javascript 复制代码

// Vue Router 示例
router.onError((error) => {
  console.error('路由跳转失败', error);
  router.replace({ name: 'offline' });
});

javascript 复制代码

// React Router 示例
<ErrorBoundary fallback={<OfflinePage />}>
  <Routes>
    <Route path="/" element={<Home />} />
  </Routes>
</ErrorBoundary>

7. 方案四：离线包与资源预加载

对于对体验要求较高的业务，可以在 App 启动时或网络良好时，将 SPA 的静态资源打包为离线包下发到本地。断网时 WebView 直接加载本地资源，彻底摆脱网络依赖。

离线包机制：服务端将构建产物打包，客户端下载后解压到本地目录，WebView 通过自定义协议或本地路径加载。
资源预加载：在网络空闲时，提前拉取后续可能访问的路由 chunk 并写入缓存。
版本管理：离线包需要配套版本号与增量更新机制，避免资源过期。

8. 方案对比与选型建议

方案	实现成本	离线效果	适用场景
WebView 缓存策略	低	仅已访问资源	轻量页面、快速接入
Service Worker	中	全量静态资源	标准 Web 离线方案
路由懒加载兜底	低	降级提示	配合其他方案使用
离线包	高	完整离线体验	强离线需求、核心业务

实际项目中，建议组合使用：以 Service Worker 或离线包保证资源可用，以路由兜底保证异常可感知，以 WebView 缓存策略作为补充。

9. 总结

断网后 WebView 加载 SPA 页面跳转失败，本质是静态资源依赖网络导致的渲染中断。通过 WebView 缓存策略、Service Worker 离线缓存、路由懒加载兜底以及离线包预加载四种方案，可以覆盖从轻量到强离线的不同需求。开发时建议优先保证「不白屏、可降级、有提示」，再逐步提升离线资源的覆盖率，从而获得更稳定的用户体验。