Electron 调试指南
Electron 里有多个独立的 JS 运行环境,这是调试的第一道坎:报错出现在哪里,决定了你该用哪套工具。
| 运行环境 | 典型代码 | 用什么调试 |
|---|---|---|
| 主进程(Main) | main.js、app.whenReady()、IPC 处理、文件读写 | VS Code 断点(–inspect)、终端日志 |
| 渲染进程(Renderer) | 页面里的 Vue/React、DOM、fetch | Chrome DevTools(Ctrl+Shift+I) |
| preload 脚本 | contextBridge.exposeInMainWorld | 渲染进程 DevTools 的 Console(有 Node 能力)+ preload-error 事件 |
排查顺序建议:先看日志定位是哪个进程出错 → 再在该进程上打断点 → 用 CDP / Inspector 看运行时状态。
一、渲染进程:Chrome DevTools 断点调试
渲染进程本质就是一个 Chromium 页面,调试方式和调网页完全一样。
1.1 打开 DevTools
开发期最省事的做法是在创建窗口时直接打开:
- snippet.js
const win = new BrowserWindow({ width: 1200, height: 800 }); win.loadFile('index.html'); // 分离窗口模式,避免和页面布局互相挤压 win.webContents.openDevTools({ mode: 'detach' });
或者保留默认菜单后按 Ctrl+Shift+I(macOS 为 Cmd+Option+I)。如果快捷键没反应,通常是应用自定义了菜单、把 toggleDevTools 角色去掉了,可以手动加一个:
- snippet.js
const { Menu } = require('electron'); Menu.setApplicationMenu(Menu.buildFromTemplate([ { label: '开发', submenu: [{ role: 'toggleDevTools' }, { role: 'reload' }] } ]));
也可以在代码里用快捷键兜底:
- snippet.js
const { globalShortcut } = require('electron'); globalShortcut.register('CommandOrControl+Shift+I', () => { BrowserWindow.getFocusedWindow()?.webContents.toggleDevTools(); });
1.2 在 Sources 面板打断点
- 打开 DevTools → Sources 面板。
- 左侧
Page树里找到你的源码文件(webpack:下通常是原始 TS/Vue 文件)。或vite: - 点行号打红点 → 触发对应操作 → 命中断点后可看作用域变量、调用栈、
Watch表达式。 - 也可以直接在代码里写
debugger;,等价于一个硬断点,适合临时定位。
断点不生效的常见原因:打包工具压缩了代码、sourcemap 没生成或路径不对。检查构建配置里 devtool: 'source-map'(webpack)或 build.sourcemap: true'(Vite),并确认 DevTools → Settings → Preferences 里启用了 Enable JavaScript source maps。
1.3 远程调试端口
想在外部 Chrome 里调渲染进程(比如内嵌页面不好操作、或在容器/远程机器上跑),启动时加:
- snippet.bash
electron --remote-debugging-port=9222 .
然后在本机 Chrome 打开 chrome:inspect,点击 ,点 Configure… 添加 localhost:9222,就能看到该窗口的页面并 attach 断点。
==== 1.4 用 CDP 在代码里主动抓信息 ====
webContents.debugger 让你用 Chrome DevTools Protocol 直接下命令,适合自动化排查网络、性能问题:
–inspectjs
win.webContents.debugger.attach('1.3');
win.webContents.debugger.on('message', (_e, method, params) => {
if (method === 'Network.responseReceived') {
console.log('响应:', params.response.status, params.response.url);
}
});
win.webContents.debugger.sendCommand('Network.enable');
===== 二、主进程:断点调试 =====
主进程是 Node.js 环境,DevTools 的 Console 看不到它,必须用 Node Inspector。
==== 2.1 命令行 ====
chrome:inspectbash
# 启动并开启 Inspector,端口 5858
electron --inspect=5858 .
# 在第一行代码前就停下(适合调试启动阶段的逻辑)
electron --inspect-brk=5858 .
然后用 Chrome 打开 Configure… 添加 localhost:5858,在 Remote Target 里点 inspect 即可看到主进程的 Sources / Console,行号上可以直接打断点。
提示:''--inspect'' 只监听调试端口,进程照常运行;''--inspect-brk'' 会**暂停在第一行**,让你有机会在初始化逻辑前下断点。
2.2 VS Code:最推荐的方式
在项目根目录建 .vscode/launch.json:
- snippet.json
{ "version": "0.2.0", "configurations": [ { "name": "调试主进程", "type": "node", "request": "launch", "cwd": "${workspaceFolder}", "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron", "windows": { "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd" }, "args": [".", "--no-sandbox"], "outputCapture": "std", "console": "integratedTerminal", "resolveSourceMapLocations": [ "${workspaceFolder}/**", "!**/node_modules/**" ] }, { "name": "附加到主进程(attach)", "type": "node", "request": "attach", "port": 5858 }, { "name": "附加到渲染进程", "type": "chrome", "request": "attach", "port": 9222, "webRoot": "${workspaceFolder}" } ] }
要点:
runtimeExecutable指向项目内的 electron,不要指向全局。- Windows 必须用
electron.cmd,否则拉起的是electron.exe的 shell 脚本而无法附加。 outputCapture: “std”让主进程的console.log显示在 VS Code 的调试终端里,日志和断点一起看。- 修改主进程代码后必须重启调试会话(Electron 主进程不支持热重载)。想省事可以装
electronmon或nodemon:
- snippet.bash
nodemon --watch main.js --exec "electron --inspect=5858 ."
2.3 Electron Forge / electron-builder 项目
- Electron Forge:
forge start已经带 Inspector 支持,直接跑npm start – –inspect=5858,或按官方 VS Code 插件模板生成 launch.json。 - electron-builder + vite / webpack 模板:多数模板已内置
调试主进程配置,直接用;没有的话按 2.2 的 launch.json 手写。 - 使用 TypeScript 时,
outDir产物和源码靠 sourcemap 关联,确保tsconfig.json里sourceMap: true。
2.4 主进程卡死怎么查
界面无响应、日志突然断掉,通常是主进程被同步代码阻塞。处理办法:
- 用
–inspect启动,在 DevTools 里点 Pause(或 F8),看当前停在哪个调用栈——卡死时通常能直接抓到阻塞点。 - 排查常见元凶:
fs.readFileSync大文件、execSync、超长循环、重复的dialog.showMessageBoxSync。 - 打印活跃句柄,看有没有未释放的 timer / socket:
- snippet.js
console.log(process._getActiveHandles()); console.log(process._getActiveRequests());
三、日志调试
断点适合“知道大概在哪”,日志适合“线上/打包后不知道在哪”。Electron 的日志有两个坑:
- 主进程的
console.log输出到启动它的终端,Windows 上打包成 GUI 程序后没有终端,等于全部丢失。 - 渲染进程的
console.log只进 DevTools 的 Console,不进终端,也不好留存。
所以正经项目建议直接上 electron-log,把三个进程的日志汇总到一个文件。
3.1 原生方式:先确认日志去哪了
- snippet.bash
# 让 Chromium / Electron 内部日志(含渲染进程 console)输出到 stderr electron --enable-logging . # 等价的环境变量写法 ELECTRON_ENABLE_LOGGING=1 electron .
–enable-logging 之后,渲染进程的 console 也会打到终端,这在排查“页面白屏但 DevTools 打不开”时非常有用。
3.2 推荐:electron-log
- snippet.bash
npm i electron-log
主进程里初始化一次:
- snippet.js
// electron-log v5 const log = require('electron-log/main'); log.initialize(); // electron-log v4 的写法 // const log = require('electron-log'); log.transports.file.level = 'info'; // 文件日志级别 log.transports.console.level = 'debug'; log.info('应用启动', { version: app.getVersion() }); log.warn('配置缺失,使用默认值'); log.error('请求失败', err);
日志文件默认落在平台标准目录(app.getPath('logs')),可以直接在界面上加一个“打开日志目录”按钮方便用户反馈:
- snippet.js
const { shell } = require('electron'); shell.openPath(app.getPath('logs'));
在 preload 里暴露给渲染进程,页面日志就能和主进程日志写进同一个文件:
- snippet.js
// preload.js const log = require('electron-log/renderer'); contextBridge.exposeInMainWorld('log', log);
- snippet.js
// 渲染进程 window.log.info('用户点击了导出按钮');
3.3 不用库:手动汇总渲染进程日志
不想引依赖时,用 web-contents-created 把所有窗口的 console、加载失败、崩溃事件统一接管:
- snippet.js
app.on('web-contents-created', (_event, wc) => { wc.on('console-message', (_e, level, message, line, sourceId) => { console.log(`[renderer:${level}] ${message} (${sourceId}:${line})`); }); wc.on('did-fail-load', (_e, code, desc, url) => { console.error(`[renderer] 加载失败 ${code} ${desc} ${url}`); }); wc.on('render-process-gone', (_e, details) => { console.error('[renderer] 进程退出', details.reason, details.exitCode); }); wc.on('preload-error', (_e, preloadPath, err) => { console.error('[preload] 出错', preloadPath, err); }); });
preload-error 尤其值得加:preload 报错不会显示在页面里,表现为“window.myApi 是 undefined”,非常难猜。
3.4 兜住未捕获异常与崩溃
- snippet.js
process.on('uncaughtException', (err) => { log.error('[main] uncaughtException', err); }); process.on('unhandledRejection', (reason) => { log.error('[main] unhandledRejection', reason); }); const { crashReporter } = require('electron'); crashReporter.start({ productName: 'MyApp', companyName: 'MyCompany', submitURL: 'https://example.com/crash', uploadToServer: false, // 先落本地,确认稳定再上传 compress: true });
四、打包之后的调试
打包后调试变难,主要是源码被 asar 包起来、被压缩、没有 sourcemap。对策:
- 提供一个开发构建(
NODE_ENV=development、不压缩、带 sourcemap)用于排查,不要直接调生产包。 - 保留 Inspector:
MyApp.exe –inspect=5858在打包版上同样有效,前提是 Electron Fuses 里的EnableNodeCliInspectArguments没被关闭。如果公司安全规范要求关闭它,就改为启动时读环境变量决定写不写详细日志。 - 渲染进程仍可用
–remote-debugging-port=9222附加。 - asar 内的源码路径在断点里可能显示为
app.asar/…,VS Code 需要把 sourcemap 里的路径映射到本地源码目录(sourceMapPathOverrides)。 - 想看 asar 里的实际文件,用
npx asar list app.asar/npx asar extract app.asar out。
五、常见症状速查
| 症状 | 大概率原因 | 处理办法 |
|---|---|---|
主进程 console.log 什么都看不到 | 打包成 GUI 程序后没有终端 | 换 electron-log 写文件;开发期用 –enable-logging |
| 断点是灰的 / 打不上 | 代码被压缩,sourcemap 缺失或路径不匹配 | 构建时开 sourcemap,加 resolveSourceMapLocations |
| 页面白屏但没报错 | loadFile 路径错、preload 抛错 | 监听 did-fail-load 与 preload-error |
window.api 为 undefined | preload 未加载或 contextBridge 没写好 | 检查 webPreferences.preload 路径与 preload 报错 |
| 改了主进程代码没生效 | Electron 主进程不热重载 | 重启调试会话,或用 electronmon |
| 整个界面卡死 | 主进程同步阻塞 | –inspect 后 Pause 看调用栈 |
| DevTools 里只看到压缩代码 | 未生成 sourcemap | 开发构建 + 开启 JS source maps |
–inspect 无反应 | 端口被占用 / fuses 关闭 | 换端口 –inspect=9230,检查 fuses 配置 |
六、推荐的日常工作流
npm start走 VS Code 的「调试主进程」配置,主进程可打断点、日志进集成终端。- 窗口自动打开 DevTools(
mode: 'detach'),渲染进程断点在 Sources 面板打。 - 关键路径(启动、IPC、网络、文件操作)用
log.info打结构化日志,统一进electron-log文件。 - 收到用户问题时,让对方发
app.getPath('logs')目录下的日志文件,而不是让他复述现象。 - 线上疑难问题,用带 sourcemap 的开发构建 + 打包版
–inspect复现。
速查思维导图
# Electron 调试
## 先分清进程
### 主进程
- main.js / app.whenReady
- Node 环境,DevTools 看不到
### 渲染进程
- 页面 Vue/React/DOM
- 等于调 Chromium 网页
### preload
- contextBridge
- 报错只在 preload-error 里
## 断点调试
### 渲染进程
- Ctrl+Shift+I 开 DevTools
- Sources 面板打红点
- debugger; 临时断点
- 需 sourcemap 才能命中源码
### 主进程
- electron --inspect=5858 .
- --inspect-brk 首行停住
- chrome://inspect 加 localhost:5858
- VS Code launch.json 最省事
- Windows 用 electron.cmd
### 远程/外部调试
- --remote-debugging-port=9222
- webContents.debugger + CDP
### 卡死排查
- --inspect 后按 Pause 看栈
- 查 readFileSync / execSync
- process._getActiveHandles()
## 日志调试
### 坑
- 主进程 log 只进启动终端
- 打包后 GUI 无终端=日志全丢
- 渲染进程 log 只在 DevTools
### 原生
- --enable-logging 输出到 stderr
- ELECTRON_ENABLE_LOGGING=1
### electron-log
- log.initialize() 一次
- transports.file.level
- 文件在 app.getPath('logs')
- preload 暴露给渲染进程
### 事件汇总
- web-contents-created
- console-message 转发
- did-fail-load 白屏
- preload-error 必加
- render-process-gone 崩溃
### 兜底
- uncaughtException
- unhandledRejection
- crashReporter 落本地
## 打包后
### 难点
- asar 打包 + 压缩
- sourcemap 缺失
### 对策
- 用带 sourcemap 的开发构建
- exe --inspect=5858 仍可用
- fuses 关掉就不行
- asar list / extract 看内容
## 症状速查
### 看不到 log
- 换 electron-log 写文件
### 断点是灰的
- 开 sourcemap / 配路径映射
### 白屏
- did-fail-load + preload-error
### 改代码不生效
- 主进程无热重载,重启
### 界面卡死
- 主进程被同步阻塞
## 日常工作流
### 开发
- VS Code 调试主进程
- DevTools 调渲染进程
### 留存
- 关键路径结构化日志
### 排障
- 让用户发日志文件