Electron中BrowserWindow网络离线时出现白屏如何有效检测？

问题原因 #

离线状态下触发did-finish-load而非did-fail-load，通常是因为Chromium内核返回了状态码为200的空响应（比如命中空缓存、Service Worker返回空内容），Electron会判定页面加载成功，所以不会触发失败回调。

推荐解决方案 #

方案1：DOM特征校验（性能最优，首选方案）

在did-finish-load触发后，主动注入脚本检测目标站点的特征节点是否存在、页面内容长度是否符合预期即可快速判断是否白屏。

const win = new BrowserWindow();
// 替换为你加载的外部站点实际存在的根节点选择器，比如React的#root、Vue的#app等
const TARGET_ROOT_SELECTOR = '#app';
// 正常页面body内容最少字符数阈值，根据站点实际情况调整
const MIN_CONTENT_LENGTH = 100;

win.loadURL('https://.../app');

const checkPageValid = async () => {
  try {
    const isValid = await win.webContents.executeJavaScript(`
      !!document.querySelector('${TARGET_ROOT_SELECTOR}') && document.body.innerText.length > ${MIN_CONTENT_LENGTH}
    `);
    if (!isValid) {
      // 检测到白屏，执行兜底逻辑，比如加载本地离线错误页
      win.loadFile('error-offline.html');
    }
  } catch (err) {
    // 脚本执行异常也判定为加载失败
    win.loadFile('error-offline.html');
  }
}

win.webContents.on('did-finish-load', () => {
  checkPageValid();
});

win.webContents.on('did-fail-load', () => {
  win.loadFile('error-offline.html');
});

globalShortcut.register('CommandOrControl+R', () => win.webContents.reload());

方案2：网络状态预校验

主进程提前判断网络状态，离线时直接跳转本地错误页，避免加载外部站点出现白屏。

const { net, BrowserWindow, globalShortcut } = require('electron');
const win = new BrowserWindow();
// 监听全局网络状态
let isOnline = net.isOnline();
net.on('online', () => isOnline = true);
net.on('offline', () => isOnline = false);

const loadTargetPage = () => {
  if (!isOnline) {
    win.loadFile('error-offline.html');
    return;
  }
  win.loadURL('https://.../app');
}

loadTargetPage();

// 刷新操作前先校验网络状态
globalShortcut.register('CommandOrControl+R', () => {
  if (!isOnline) {
    win.loadFile('error-offline.html');
    return;
  }
  win.webContents.reload();
});

方案3：截图像素校验（兜底方案）

如果外部站点没有固定特征节点，可在页面加载完成后截图统计白色像素占比，超过阈值判定为白屏。

win.webContents.on('did-finish-load', async () => {
  const captureImage = await win.webContents.capturePage();
  const bitmap = captureImage.getBitmap();
  let whitePixelCount = 0;
  // 每4个字节对应一个像素的RGBA值
  for (let i = 0; i < bitmap.length; i += 4) {
    const r = bitmap[i], g = bitmap[i+1], b = bitmap[i+2];
    // 接近白色的阈值，可根据实际调整
    if (r > 250 && g > 250 && b > 250) {
      whitePixelCount++;
    }
  }
  const whiteRatio = whitePixelCount / (bitmap.length / 4);
  // 白色占比超过90%判定为白屏
  if (whiteRatio > 0.9) {
    win.loadFile('error-offline.html');
  }
});

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