Electron 白屏问题排查及解决记录

1. 先看是哪种白屏

Electron 白屏,排查时可以先分两种情况 :一种是整个页面都是白的,看不到前端渲染的内容;另一种是页面里已经出现项目名称、导航栏之类的东西,只是部分区域空白。

如果是整个页面都没出来,先查前端有没有准备好、资源有没有加载、代码执行有没有报错。如果已经显示了一部分,就顺着空白区域去查对应的路由和组件。

2. 整个页面都是白的,怎么排查?

首先看前端是不是还在构建。有时候 Electron 已经启动了,但是前端还没准备好,窗口自然加载不出来。

看一下终端,等前端构建完成后重新加载页面。如果恢复正常,就去调整启动顺序,让 Electron 等前端编译完成、页面可访问后再加载。

如果构建已经完成,还是白屏,就打开开发者工具,看 Network 中页面和 JS 有没有加载成功。有没有 404,加载地址对不对,JS 请求返回的是不是 HTML。

开发时主要检查地址和端口,打包后则检查入口文件和静态资源路径。

如果这些都正常,再看 Console 有没有报错。资源能下载下来,不代表里面的代码能正常执行。入口代码报错,前端还没挂载,页面也会一直是白的。

如果没有明确报错,再去 Elements 看根节点里有没有内容。有 DOM 但是看不到,就检查样式,比如内容是不是被隐藏了、被其他元素挡住了,或者容器没有高度。

3. 页面已经显示一部分,怎么排查?

比如导航栏正常,但是中间的业务页面没出来,就先看当前路由有没有匹配到组件,懒加载的 JS 有没有请求失败。

路由没问题,再检查组件有没有报错,或者某个显示条件一直没有满足。有些页面要等接口或 IPC 返回数据才显示,如果请求失败后没有处理,页面就可能一直停在加载状态。

同样可以去 Elements 看一下,内容到底是没生成,还是生成了但被样式藏起来了。

4. 这次实际遇到的问题

这次是在调整静态预览的构建脚本之后,Electron 窗口能打开,但是整个业务页面都是白的。

先看构建,已经完成了。再看资源请求,页面和主要 JS 都是 200,返回内容也正常。接着查看渲染进程的错误日志,发现:

text 复制代码
Uncaught ReferenceError: $RefreshReg$ is not defined

这个标识符和 React 的 Fast Refresh 有关,也就是开发时修改代码后刷新组件的功能。于是去生成的 JS 中搜索,发现确实还有 $RefreshReg$ 的调用。

再回头看构建脚本,问题找到了:为了关闭静态预览中的开发刷新,只移除了 webpack 的 ReactRefreshPlugin,但是 Babel 中的 react-refresh/babel 还开着。

也就是说,Babel 还在往代码里插入 Refresh 调用,但是配套的运行时已经被删掉了。构建时不会因此报错,等页面执行到这里,找不到对应的函数,就白屏了。

5. 怎么解决?

这个项目用的是 CRA + react-app-rewired。静态预览不需要 Fast Refresh,在生成配置之前设置 FAST_REFRESH=false,让 CRA 把对应的转换和运行时一起关掉。

构建脚本的关键代码如下:

js 复制代码
process.env.NODE_ENV = 'development'
process.env.BABEL_ENV = 'development'
process.env.FAST_REFRESH = 'false'

const createWebpackConfig = require(
  'react-app-rewired/config/webpack.config'
)

const config = createWebpackConfig('development')

这里要先设置环境变量,再加载并生成配置。配置已经生成了,再去改环境变量,已有配置不会跟着更新。其他构建工具则要找各自对应的配置方式。

改完后重新构建,检查通过再替换预览资源。替换后核对一下实际加载的文件,别构建出了新文件,窗口还在加载旧资源。

当时还用真实 Babel 转换复现了一次:保留 Refresh 转换、不给运行时,能得到同样的报错;关闭转换后,示例入口可以正常执行。重新构建的页面也经使用者确认恢复显示。

最后给这条静态预览链路加了配置和产物检查,如果又残留了 Refresh 转换、插件或相关调用,就拦下来,避免同样的问题再次进入预览环境。

相关推荐
htzyl20614 分钟前
前端监控最容易写错的 18 个地方:从平均值到 beforeunload
前端·浏览器
鹿鹿鹿鹿isNotDefined18 分钟前
布局更新后,canvas 重新绘制,出现了只持续一帧的闪烁?!
前端·javascript·vue.js
zhanlang021722 分钟前
HTML 零基础入门到企业实战【第六章 表格标签】6.3 单元格合并:跨行 rowspan、跨列 colspan 实战技巧
前端·html
技术分享官24 分钟前
Geejing WebBuilder 新手指导:用 Wb.Button 按钮组件跑通企业级快速开发平台的前后端闭环
前端·javascript·低代码
SameX24 分钟前
ArkTS 没有 AbortController 怎么取消 setTimeout 链用自增 token 的做法
前端
不可能片场44 分钟前
工程实践 雪花id进JS别当数字传
前端·electron
涛涛ing1 小时前
AI帮我生成了一个炫酷的3D大屏,上线3天就卡崩了
前端
jerrywus1 小时前
用 AMD Radeon Cloud 免费跑 ComfyUI:从开机到打开界面
前端·agent·claude
学以智用1 小时前
CKEditor5 完整详解
前端·后端