Electron加载URL报错-21(ERR_NETWORK_CHANGED)问题排查求助

问题背景 #

使用Electron框架开发桌面应用，启动时先加载本地静态页file:///C:/Users/212807091/Desktop/laoding.html，检查条件通过后调用win.loadURL加载运行在Kubernetes集群的Web应用https://localhost:8443/mayapp，但加载过程中间歇性出现错误码-21（描述为ERR_NETWORK_CHANGED），错误捕获代码如下：

win.webContents.on("did-fail-load", function (event, errorCode, errorDescription) {
      log.error(`Unable to load login page with error: ${errorCode}-${errorDescription}`);
 });

可能原因 #

• 端口转发不稳定：本地localhost:8443大概率是通过kubectl port-forward映射到K8s集群内的服务，这种转发方式本身是临时的，存在连接超时、短暂断开的可能，刚好在loadURL触发时就会抛出网络变更错误。
• 网络状态切换冲突：从本地file协议切换到网络协议时，Electron基于的Chromium内核可能残留了之前的网络状态，或者主机网络接口（如WiFi/有线网卡）发生了切换，导致连接初始化失败。
• 网络栈缓存干扰：Chromium的网络缓存或会话数据可能影响新连接的建立，尤其是跨协议（file到https）切换时，缓存的网络状态与实际网络环境不匹配。
• Electron版本bug：部分旧版本Electron的Chromium内核存在网络连接相关的已知bug，会间歇性触发此类错误。

解决办法 #

1. 优化K8s端口转发稳定性 #

如果使用kubectl port-forward，改用更可靠的转发方式或调整参数：

• 改用Ingress暴露K8s服务，直接通过域名访问，避免依赖本地端口转发。
• 调整kubectl port-forward的参数，增加连接保持时长：

  kubectl port-forward --address 0.0.0.0 --pod-running-timeout=10m svc/your-app-service 8443:443
  

• 使用第三方持久化端口转发工具（如kube-forwarder）替代原生kubectl port-forward。

2. 增加错误重试机制 #

在did-fail-load事件中针对ERR_NETWORK_CHANGED错误进行有限次数的重试：

win.webContents.on("did-fail-load", function (event, errorCode, errorDescription) {
  log.error(`Unable to load login page with error: ${errorCode}-${errorDescription}`);
  
  // 仅针对ERR_NETWORK_CHANGED(-21)进行重试
  if (errorCode === -21 && errorDescription === "ERR_NETWORK_CHANGED") {
    const MAX_RETRIES = 3;
    let retryCount = 0;
    
    const retryLoad = () => {
      if (retryCount < MAX_RETRIES) {
        retryCount++;
        log.info(`Retrying app load, attempt ${retryCount}/${MAX_RETRIES}`);
        setTimeout(() => {
          win.loadURL("https://localhost:8443/mayapp");
        }, 1500); // 延迟1.5秒重试，给网络恢复时间
      } else {
        log.error("Max retry attempts reached, failed to load app");
        // 可在此处向用户展示网络错误提示
      }
    };
    
    retryLoad();
  }
});

3. 切换协议前清理网络状态 #

在调用loadURL前清理WebContents的缓存，避免旧状态干扰：

// 清理网络缓存后加载目标URL
win.webContents.session.clearCache()
  .then(() => win.webContents.session.clearStorageData())
  .then(() => win.loadURL("https://localhost:8443/mayapp"))
  .catch(err => log.error("Failed to clear cache:", err));

4. 前置网络连通性检查 #

在加载目标URL前，先检查本地端口的连通性，确保服务可达后再加载：

const { URL } = require('url');
const https = require('https');

function checkServiceReachable(url) {
  return new Promise(resolve => {
    const urlObj = new URL(url);
    const options = {
      hostname: urlObj.hostname,
      port: urlObj.port,
      path: urlObj.pathname,
      method: 'HEAD'
    };

    const req = https.request(options, res => {
      resolve(res.statusCode >= 200 && res.statusCode < 400);
    });

    req.on('error', () => resolve(false));
    req.setTimeout(3000, () => resolve(false)); // 3秒超时
    req.end();
  });
}

// 检查通过后再加载
checkServiceReachable("https://localhost:8443/mayapp")
  .then(isReachable => {
    if (isReachable) {
      win.loadURL("https://localhost:8443/mayapp");
    } else {
      log.warn("Service not reachable, retrying in 2 seconds");
      setTimeout(() => win.loadURL("https://localhost:8443/mayapp"), 2000);
    }
  });

5. 升级Electron版本 #

如果使用的是较旧的Electron版本，尝试升级到最新稳定版，修复Chromium内核的已知网络bug。

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