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 看运行时状态。
渲染进程本质就是一个 Chromium 页面,调试方式和调网页完全一样。
开发期最省事的做法是在创建窗口时直接打开:
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 角色去掉了,可以手动加一个:
const { Menu } = require('electron');
Menu.setApplicationMenu(Menu.buildFromTemplate([
{ label: '开发', submenu: [{ role: 'toggleDevTools' }, { role: 'reload' }] }
]));
也可以在代码里用快捷键兜底:
const { globalShortcut } = require('electron');
globalShortcut.register('CommandOrControl+Shift+I', () => {
BrowserWindow.getFocusedWindow()?.webContents.toggleDevTools();
});
Page 树里找到你的源码文件(webpack: 或 vite: 下通常是原始 TS/Vue 文件)。Watch 表达式。debugger;,等价于一个硬断点,适合临时定位。
断点不生效的常见原因:打包工具压缩了代码、sourcemap 没生成或路径不对。检查构建配置里 devtool: 'source-map'(webpack)或 build.sourcemap: true'(Vite),并确认 DevTools → Settings → Preferences 里启用了 Enable JavaScript source maps。
想在外部 Chrome 里调渲染进程(比如内嵌页面不好操作、或在容器/远程机器上跑),启动时加:
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'' 会**暂停在第一行**,让你有机会在初始化逻辑前下断点。
在项目根目录建 .vscode/launch.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,不要指向全局。electron.cmd,否则拉起的是 electron.exe 的 shell 脚本而无法附加。outputCapture: “std” 让主进程的 console.log 显示在 VS Code 的调试终端里,日志和断点一起看。electronmon 或 nodemon:nodemon --watch main.js --exec "electron --inspect=5858 ."
forge start 已经带 Inspector 支持,直接跑 npm start – –inspect=5858,或按官方 VS Code 插件模板生成 launch.json。调试主进程 配置,直接用;没有的话按 2.2 的 launch.json 手写。outDir 产物和源码靠 sourcemap 关联,确保 tsconfig.json 里 sourceMap: true。界面无响应、日志突然断掉,通常是主进程被同步代码阻塞。处理办法:
–inspect 启动,在 DevTools 里点 Pause(或 F8),看当前停在哪个调用栈——卡死时通常能直接抓到阻塞点。fs.readFileSync 大文件、execSync、超长循环、重复的 dialog.showMessageBoxSync。console.log(process._getActiveHandles()); console.log(process._getActiveRequests());
断点适合“知道大概在哪”,日志适合“线上/打包后不知道在哪”。Electron 的日志有两个坑:
console.log 输出到启动它的终端,Windows 上打包成 GUI 程序后没有终端,等于全部丢失。console.log 只进 DevTools 的 Console,不进终端,也不好留存。
所以正经项目建议直接上 electron-log,把三个进程的日志汇总到一个文件。
# 让 Chromium / Electron 内部日志(含渲染进程 console)输出到 stderr electron --enable-logging . # 等价的环境变量写法 ELECTRON_ENABLE_LOGGING=1 electron .
–enable-logging 之后,渲染进程的 console 也会打到终端,这在排查“页面白屏但 DevTools 打不开”时非常有用。
npm i electron-log
主进程里初始化一次:
// 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')),可以直接在界面上加一个“打开日志目录”按钮方便用户反馈:
const { shell } = require('electron');
shell.openPath(app.getPath('logs'));
在 preload 里暴露给渲染进程,页面日志就能和主进程日志写进同一个文件:
// preload.js
const log = require('electron-log/renderer');
contextBridge.exposeInMainWorld('log', log);
// 渲染进程
window.log.info('用户点击了导出按钮');
不想引依赖时,用 web-contents-created 把所有窗口的 console、加载失败、崩溃事件统一接管:
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”,非常难猜。
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)用于排查,不要直接调生产包。MyApp.exe –inspect=5858 在打包版上同样有效,前提是 Electron Fuses 里的 EnableNodeCliInspectArguments 没被关闭。如果公司安全规范要求关闭它,就改为启动时读环境变量决定写不写详细日志。–remote-debugging-port=9222 附加。app.asar/…,VS Code 需要把 sourcemap 里的路径映射到本地源码目录(sourceMapPathOverrides)。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 的「调试主进程」配置,主进程可打断点、日志进集成终端。mode: 'detach'),渲染进程断点在 Sources 面板打。log.info 打结构化日志,统一进 electron-log 文件。app.getPath('logs') 目录下的日志文件,而不是让他复述现象。–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 调渲染进程
### 留存
- 关键路径结构化日志
### 排障
- 让用户发日志文件