第一次跑 Electron 的人,大多会经历三个相似的瞬间。第一个:照着教程建好目录,执行 npx electron .,命令行只留下一行「Unable to find Electron app」或者「Cannot find module」,窗口根本没出现。第二个:把入口修好,窗口终于出来了,但里面一片白,DevTools 的 Network 面板里一条 404。第三个:开发环境一切正常,打包发给客户,双击后还是白屏,日志里说找不到某个 HTML 文件。
这三个现象看起来都是「Electron 有 bug」,实际上分别对应三件不同的事:入口没配对、页面路径没配对、打包后的路径和开发时不一样。它们都绕不开同一个基础认知——Electron 不是一个进程,它至少有两个:主进程和渲染进程。
这篇用一个四文件的最小应用把这套结构跑通:package.json、main.js、index.html、preload.js。跑通之后,再逐条讲开发与生产的加载差异、预加载脚本路径、单实例锁、窗口关闭行为,以及白屏到底该按什么顺序查。版本说明:本机装的是 Electron 45.2.3、Node v24.21.0。四个文件搭起来了,依赖也装完了(node_modules\electron\dist 73 个文件、356.8 MB),但 Electron 进程在这台机器上启动即崩(0xC0000005,加 --no-sandbox --disable-gpu 也一样),所以窗口是否正常出现、白屏排查的每一步没有运行时证据,下面标出哪些是照官方模板写的、哪些需要在能跑的环境里补验证。
两个进程:一个管窗口,一个管页面
把 Electron 应用想成一家小店。主进程是店长,负责开门、关店、租场地、办手续;渲染进程是店里的店员,负责接待顾客、展示商品。店长不直接接待顾客,店员也不能随便改租约。两边要做跨职责的事,就得走内部流程,也就是后面要讲的 IPC。
window 上。除了这两个,任务管理器里还会看到 GPU 进程、网络服务、工具进程,这些是 Chromium 自己的基础设施,不需要你写代码,但它们解释了为什么一个空窗口也会占上百 MB 内存。渲染进程崩溃通常只影响一个窗口,主进程崩溃则整个应用退出,这个差别在排查线上问题时很关键。
最容易搞混的一条边界是:窗口是主进程创建的资源,页面是渲染进程里的内容。所以「窗口不出现」要去查主进程,「窗口出来了但内容白」要去查渲染进程和加载路径。把这两类问题分开,排查范围立刻缩小一半。
场景走查:四个文件跑起来
需求很简单:一个 960×640 的窗口,显示一行标题,页面能读到当前平台和架构,关闭窗口后程序退出,重复启动时只保留一个实例。先建目录、初始化、安装 Electron:
mkdir electron-hello
cd electron-hello
npm init -y
npm i -D electron
安装完成后,Electron 会出现在 devDependencies 里,版本号由 npm 按当前稳定版写入,这里不手写。接着改 package.json,把入口和执行脚本补上。main 指向主进程文件,少了它,electron . 就找不到应用入口。
{
"name": "electron-hello",
"private": true,
"version": "0.1.0",
"main": "main.js",
"scripts": {
"start": "electron ."
}
}
主进程文件 main.js 做五件事:抢单实例锁、创建窗口、加载页面、处理 macOS 的激活事件、在最后一个窗口关闭时决定是否退出。
const { app, BrowserWindow } = require('electron');
const path = require('node:path');
let mainWindow = null;
function createWindow() {
const win = new BrowserWindow({
width: 960,
height: 640,
show: false,
title: 'Electron 起步',
webPreferences: {
preload: path.join(__dirname, 'preload.js'),
contextIsolation: true,
nodeIntegration: false,
sandbox: true
}
});
mainWindow = win;
win.once('ready-to-show', () => win.show());
win.webContents.on('did-fail-load', (_event, code, description, url) => {
console.error('页面加载失败', code, description, url);
});
win.webContents.on('render-process-gone', (_event, details) => {
console.error('渲染进程退出', details.reason);
});
win.loadFile(path.join(__dirname, 'index.html'));
win.on('closed', () => {
mainWindow = null;
});
}
const gotTheLock = app.requestSingleInstanceLock();
if (!gotTheLock) {
app.quit();
} else {
app.on('second-instance', () => {
if (!mainWindow) return;
if (mainWindow.isMinimized()) mainWindow.restore();
mainWindow.focus();
});
app.whenReady().then(() => {
createWindow();
app.on('activate', () => {
if (BrowserWindow.getAllWindows().length === 0) createWindow();
});
});
}
app.on('window-all-closed', () => {
if (process.platform !== 'darwin') app.quit();
});
页面文件 index.html 不需要任何构建工具,直接写静态 HTML。里面加一段判断,预加载脚本没加载成功时能看到提示,而不是只看到空白。
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>Electron 起步</title>
<style>
body { font-family: system-ui, sans-serif; padding: 32px; }
</style>
</head>
<body>
<h1>Electron 已启动</h1>
<p id="info">正在读取环境…</p>
<script>
const info = document.getElementById('info');
if (window.appInfo) {
info.textContent = `平台:${window.appInfo.platform} / 架构:${window.appInfo.arch}`;
} else {
info.textContent = '预加载脚本没有加载';
}
</script>
</body>
</html>
预加载脚本 preload.js 只暴露两个只读字符串。不要在页面里直接 require('fs'),那是打开 nodeIntegration 的错误做法。
const { contextBridge } = require('electron');
contextBridge.exposeInMainWorld('appInfo', {
platform: process.platform,
arch: process.arch
});
启动:npm start,或者直接 npx electron .。预期结果:一两秒后出现一个 960×640 的窗口,标题是「Electron 起步」,页面显示「Electron 已启动」和「平台:win32 / 架构:x64」(具体值随机器变化)。窗口不会先闪一下白屏再显示内容,因为 show: false 加 ready-to-show 把显示时机推到了页面准备好之后。
再开一个终端,重复执行 npm start。预期是第二个进程立刻退出,第一个窗口被恢复并聚焦到前台,而不是出现两个窗口。关闭窗口,Windows 和 Linux 上进程应当退出;macOS 上应用还留在 Dock,点击 Dock 图标会重新创建窗口。这些行为分别由单实例锁、window-all-closed 和 activate 控制,下一节逐个说清。
开发与生产:路径、锁、关闭与激活
先看加载方式。开发时页面通常来自一个本地开发服务器,用 loadURL;生产时页面是构建产物,用 loadFile。两者不是「随便选一个」,而是对应两种完全不同的路径和协议。
loadURL
加载一个 http 地址,需要开发服务器先启动。热更新方便,但服务器没起来就是白屏或连接拒绝。前端路由、接口请求、Cookie 都按浏览器规则走。
loadFile
加载本地文件,路径必须是绝对路径。打包后文件通常在一个 asar 归档里,路径拼接错了就是 404 白屏,而且错误只在主进程终端或 DevTools 里看得到。
开发与生产的分支不要靠「猜」,要用明确条件。app.isPackaged 在打包后为真,开发时为假;也可以用一个环境变量显式传入开发地址。下面这种写法比在代码里写死 http://localhost 更稳:
const devServer = process.env.VITE_DEV_SERVER_URL;
if (devServer) {
win.loadURL(devServer);
} else {
win.loadFile(path.join(__dirname, 'dist', 'index.html'));
}
如果生产环境用 file:// 加载,有几条限制要提前知道。第一,fetch 读本地 JSON 会被当成跨域,很多在浏览器里正常的请求会失败。第二,前端路由如果是基于 History API 的 BrowserRouter,刷新或跳转后 file:// 下找不到对应文件,页面会白。第三,相对路径资源在多层目录下容易解析错。常见做法是改用 HashRouter,或者注册一个自定义协议来提供页面,而不是裸用 file://。
预加载脚本的路径只有一种正确写法:绝对路径。path.join(__dirname, 'preload.js') 在开发和打包后都能指向正确位置,因为 __dirname 始终是主进程文件所在目录;打包成 asar 之后,Electron 也能从归档里读预加载脚本。反过来,写相对路径、写死开发机的绝对路径、把文件名拼错,都会出现「页面能开,但 window.appInfo 是 undefined」,而且控制台里往往只有一条不显眼的警告。预加载脚本加载失败不会让窗口消失,只会让桥悄悄消失,这类问题比崩溃更难查。
单实例锁的顺序很重要。app.requestSingleInstanceLock() 必须在创建窗口之前调用;拿不到锁就立刻退出,拿到锁才注册 second-instance 并创建窗口。如果先创建窗口再判断锁,第二个实例可能已经闪出一个窗口才退出,用户会看到「双击两次,窗口闪两下」。second-instance 里做的事通常不是「再开一个窗口」,而是把已有窗口从最小化恢复并聚焦,或者把启动参数交给第一个实例处理——比如用户双击一个文件,希望用已经打开的窗口打开它。
window-all-closed 决定「最后一个窗口关了,应用要不要退出」。Windows 和 Linux 的惯例是退出,macOS 的惯例是留着,所以上面的代码判断了 process.platform !== 'darwin'。如果你的应用有托盘、后台同步、常驻任务,就不能直接退出,而要改成隐藏窗口;但这时要同时处理托盘菜单里的「退出」,否则用户找不到结束程序的办法。macOS 的 activate 事件对应点击 Dock 图标,标准做法是「没有窗口就创建一个」,不写这段,用户关窗后再点 Dock 会以为程序坏了。
还有一个容易忽略的细节:show: false 是为了避免白屏闪烁,但它把「窗口什么时候出现」交给 ready-to-show。如果页面加载失败、路径不存在、渲染进程直接崩了,这个事件可能永远不触发,结果就是「进程在跑,窗口不出现」。调试阶段可以临时改成 show: true,先确认窗口本身没问题,再排除加载失败。生产环境保留 show: false 时,务必加上 did-fail-load 和 render-process-gone 的日志,别让失败无声无息。
现象、原因与第一步
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
执行 electron . 报找不到应用 | package.json 缺 main,或入口文件不存在 | 看 package.json 的 main 是否指向真实文件,文件名大小写是否一致 |
| 窗口出现,但里面全白 | 页面路径错、文件不存在,或开发服务器没启动 | 看主进程终端的 did-fail-load,再打开 DevTools 看 Network 里的 404 |
| 进程在跑,窗口一直不出现 | show: false 且 ready-to-show 没触发,通常是加载失败 | 临时改成 show: true,同时加加载失败日志 |
| 开发正常,打包后白屏 | 构建产物没进包、asar 内路径不对,或用了开发机的绝对路径 | 解开 asar 看 dist/index.html 是否存在,核对 __dirname 和构建配置 |
页面里的 window.appInfo 是 undefined | 预加载路径错、文件没进包,或预加载执行时报错 | DevTools 控制台找预加载错误,确认路径是绝对路径且文件存在 |
| 双击启动出现两个窗口 | 单实例锁在窗口创建之后才判断,或根本没加锁 | 确认 requestSingleInstanceLock 在 whenReady 和创建窗口之前 |
| macOS 关窗后程序还在,点 Dock 没反应 | window-all-closed 没有按平台区分,或没处理 activate | 检查平台判断,确认 activate 里会重新创建窗口 |
| 打包后接口请求全部失败 | file:// 下的跨域限制、相对路径或前端路由问题 | 看 DevTools 的请求地址与错误,改用绝对接口地址、Hash 路由或自定义协议 |
白屏排查:按顺序来,别乱猜
白屏是 Electron 最常见也最容易被误判的问题。有人一上来就怀疑显卡、怀疑 Electron 版本、重装依赖,折腾半天,最后发现只是 loadFile 少写了一层目录。按下面的顺序走,每一步都能排除一类原因。
第一步,先分清「没有窗口」和「有窗口但白」。前者是主进程没创建成功,可能是入口错、锁逻辑错、创建时抛异常;后者是窗口创建了,但页面没加载出来。任务管理器里看进程在不在,只能说明主进程活着,不能说明窗口存在。第二步,回到启动命令的终端,主进程的 console.error、未捕获异常、模块找不到都会打在这里;很多人只看 DevTools,其实错误根本不在渲染进程。
第三步,在窗口里按 Ctrl+Shift+I 打开 DevTools,或者临时在主进程里调用 win.webContents.openDevTools()。先看 Console 有没有红色报错,再看 Network 里主文档的请求状态:404 说明路径错,ERR_CONNECTION_REFUSED 说明开发服务器没起,net::ERR_FILE_NOT_FOUND 说明本地文件不存在。第四步,把实际加载的路径打印出来,用 fs.existsSync 验证;路径问题不要靠肉眼比对,打印出来最省事。
第五步,如果只有打包后白屏,去输出目录里确认构建产物真的进了包。asar 是一个归档文件,可以用 npx asar list resources/app.asar 查看内容;找不到 dist/index.html,就回头查构建配置的 files 字段,而不是继续改主进程代码。第六步,开发模式下白屏,先确认开发服务器地址能从浏览器打开,再确认端口、防火墙、自签名证书;loadURL 不会替你启动服务器,也不会替你忽略证书错误。
nodeIntegration: true 来解决「页面拿不到文件」的问题。它确实能让 require('fs') 立刻可用,但同时把整个 Node 环境交给了页面;一旦页面里有 XSS,攻击者就能读任意文件、执行命令。正确的方向是把文件操作放在主进程,通过预加载脚本暴露一个参数受控的接口,这也是下一篇的主题。边界与代价
第一,Electron 的版本和 Chromium 绑在一起。升级 Electron 往往同时升级 Chromium 和 Node,渲染行为、废弃 API、原生模块的 ABI 都会变。长期项目要留出升级和回归的时间,不能等到安全公告出来才临时抱佛脚。反过来说,不升级就意味着把一个旧 Chromium 发给客户,安全风险会累积。
第二,原生模块要按 Electron 的 ABI 重新编译。串口、数据库驱动、图像处理这些依赖,在普通 Node 里装好不等于在 Electron 里能用,需要 electron-rebuild 之类的工具;打包时还要把二进制文件从 asar 里解出来,否则加载会失败。这是「前端项目」里突然冒出来的一段原生构建工作。
第三,路径问题不会因为「开发时跑通了」而消失。开发时的当前目录、打包后的 asar、用户机器的安装目录、只读的 Program Files,都是不同环境。规则很简单:加载页面用绝对路径,读写用户数据用 app.getPath('userData'),不要把配置写进安装目录,也不要把开发机的路径带进代码。
第四,窗口生命周期比网页复杂。网页关掉标签页就结束了,桌面应用要处理最小化到托盘、关闭前确认、多窗口、单实例、开机自启、系统休眠恢复。每一个都要显式设计,否则就会出现「关了窗口进程还在」「开机自启后不显示」「第二实例抢焦点」这类体验问题。
第五,多进程让调试变复杂。渲染进程的问题看 DevTools,主进程的问题看终端和日志文件,两者时间线要能对上。线上环境不可能让用户开 DevTools,所以启动日志、崩溃上报、渲染进程退出记录要在第一版就加上,而不是等客户投诉「白屏」再补。
第六,签名和分发是另一条战线。Windows 的代码签名、macOS 的公证、Linux 的包格式、自动更新的签名校验,都要在「能跑」之后继续做。一个能在本机 npm start 的应用,离能安全地装到客户机器上还有相当距离。
第七,最小应用不等于产品。右键菜单、快捷键、拖拽文件、高 DPI、输入法、无障碍、崩溃恢复、离线提示,这些在浏览器里由浏览器兜底,在 Electron 里要自己补。壳只提供了窗口,桌面体验仍要一项项做。
小结与练习
Electron 的起点不是「写个网页塞进去」,而是分清主进程和渲染进程:主进程管窗口和系统,渲染进程管页面,预加载脚本是两者之间那条窄桥。开发用 loadURL、生产用 loadFile,路径一律绝对;单实例锁要在创建窗口之前;关闭行为和 macOS 激活要按平台处理。白屏先分清「没窗口」还是「白窗口」,再按主进程终端、DevTools、路径、打包产物的顺序查。
当天可以自己验证的练习:
- 把
package.json里的main改成不存在的文件,执行npm start,记下终端报错,再改回来。 - 把
loadFile的路径故意改成index2.html,观察窗口是否出现、did-fail-load打印了什么,最后在 DevTools 里找到那条 404。 - 删掉
preload.js的contextBridge调用,确认页面显示「预加载脚本没有加载」,再恢复。 - 去掉单实例锁,连续启动两次,观察两个窗口;再把
second-instance的逻辑补上,确认第二次只聚焦。 - 把
webPreferences里的nodeIntegration改成true,在 DevTools 里执行require('node:fs'),确认它能跑,然后立刻改回false,想清楚为什么不能这样交付。
窗口能稳定出现之后,下一个问题就是「页面怎么和系统说话」。下一篇讲进程间通信与预加载脚本:invoke 与 handle 怎么配对、参数和来源怎么校验、错误为什么只剩一句话、监听器为什么会越积越多。这一篇只把桥搭好,下一篇才决定桥该开多大。