Capacitor服务器URL不可用时展示本地错误页面方案咨询

核心思路 #

当配置server.url后，WebView会优先加载远程资源，但无网络时加载失败会显示空白。此时需要在原生端（Android/iOS）监听WebView的加载错误事件，一旦检测到无网络或加载失败，就切换到本地www目录下的离线错误页面。

步骤1：准备本地离线错误页 #

在Ionic项目的src目录下创建offline.html，编写离线提示内容：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>无网络连接</title>
    <style>
        body { display: flex; flex-direction: column; align-items: center; justify-content: center; height: 100vh; margin: 0; font-family: sans-serif; }
        h1 { color: #333; }
        p { color: #666; }
    </style>
</head>
<body>
    <h1>网络连接失败</h1>
    <p>请检查你的网络设置后重试</p>
</body>
</html>

执行ionic build，确保该文件被打包到www目录中。

步骤2：Android端修改 #

打开Android项目的app/src/main/java/[你的包名]/MainActivity.java（或Kotlin文件），添加WebView错误监听：

Java版本 #

import android.net.ConnectivityManager;
import android.net.NetworkInfo;
import android.webkit.WebResourceError;
import android.webkit.WebResourceRequest;
import android.webkit.WebView;
import android.webkit.WebViewClient;
import com.getcapacitor.BridgeActivity;

public class MainActivity extends BridgeActivity {
    @Override
    public void onResume() {
        super.onResume();
        WebView webView = getBridge().getWebView();
        webView.setWebViewClient(new WebViewClient() {
            @Override
            public void onReceivedError(WebView view, WebResourceRequest request, WebResourceError error) {
                super.onReceivedError(view, request, error);
                // 检查网络状态
                ConnectivityManager cm = (ConnectivityManager) getSystemService(CONNECTIVITY_SERVICE);
                NetworkInfo activeNetwork = cm.getActiveNetworkInfo();
                boolean isConnected = activeNetwork != null && activeNetwork.isConnectedOrConnecting();
                
                if (!isConnected) {
                    // 加载本地离线页
                    view.loadUrl("file:///android_asset/www/offline.html");
                }
            }
        });
    }
}

Kotlin版本 #

import android.net.ConnectivityManager
import android.net.NetworkInfo
import android.webkit.WebResourceError
import android.webkit.WebResourceRequest
import android.webkit.WebView
import android.webkit.WebViewClient
import com.getcapacitor.BridgeActivity

class MainActivity : BridgeActivity() {
    override fun onResume() {
        super.onResume()
        val webView = bridge.webView
        webView.webViewClient = object : WebViewClient() {
            override fun onReceivedError(view: WebView?, request: WebResourceRequest?, error: WebResourceError?) {
                super.onReceivedError(view, request, error)
                val cm = getSystemService(CONNECTIVITY_SERVICE) as ConnectivityManager
                val activeNetwork: NetworkInfo? = cm.activeNetworkInfo
                val isConnected = activeNetwork != null && activeNetwork.isConnectedOrConnecting
                
                if (!isConnected) {
                    view?.loadUrl("file:///android_asset/www/offline.html")
                }
            }
        }
    }
}

步骤3：iOS端修改 #

打开iOS项目的AppDelegate.swift，添加WebView导航代理和网络检测逻辑：

import UIKit
import Capacitor
import Reachability

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        return true
    }

    // ... 保留其他默认方法 ...

    func applicationDidBecomeActive(_ application: UIApplication) {
        guard let webView = Bridge.shared?.webView else { return }
        webView.navigationDelegate = self
    }
}

extension AppDelegate: WKNavigationDelegate {
    func webView(_ webView: WKWebView, didFail navigation: WKNavigation!, withError error: Error) {
        // 检查网络状态
        let reachability = try? Reachability()
        let isConnected = reachability?.connection != .unavailable
        
        if !isConnected {
            // 加载本地离线页
            guard let offlineUrl = Bundle.main.url(forResource: "www/offline", withExtension: "html") else { return }
            webView.loadFileURL(offlineUrl, allowingReadAccessTo: offlineUrl.deletingLastPathComponent())
        }
    }
}

注意：iOS需先添加Reachability依赖，在iOS项目的Podfile中添加pod 'ReachabilitySwift'，执行pod install完成安装。

步骤4：验证 #

1. 断开设备网络
2. 重启应用，应显示自定义的离线错误页
3. 恢复网络后，重启应用会正常加载远程URL

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