目录

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 面板打断点

  1. 打开 DevTools → Sources 面板。
  2. 左侧 Page 树里找到你的源码文件(webpack: 或 vite: 下通常是原始 TS/Vue 文件)。
  3. 点行号打红点 → 触发对应操作 → 命中断点后可看作用域变量、调用栈、Watch 表达式。
  4. 也可以直接在代码里写 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 直接下命令,适合自动化排查网络、性能问题: js 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 命令行 –inspect ==== bash # 启动并开启 Inspector,端口 5858 electron --inspect=5858 . # 在第一行代码前就停下(适合调试启动阶段的逻辑) electron --inspect-brk=5858 . 然后用 Chrome 打开 chrome:inspect,点击 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}"
    }
  ]
}

要点:

snippet.bash
nodemon --watch main.js --exec "electron --inspect=5858 ."

2.3 Electron Forge / electron-builder 项目

2.4 主进程卡死怎么查

界面无响应、日志突然断掉,通常是主进程被同步代码阻塞。处理办法:

  1. 用 –inspect 启动,在 DevTools 里点 Pause(或 F8),看当前停在哪个调用栈——卡死时通常能直接抓到阻塞点。
  2. 排查常见元凶:fs.readFileSync 大文件、execSync、超长循环、重复的 dialog.showMessageBoxSync。
  3. 打印活跃句柄,看有没有未释放的 timer / socket:
snippet.js
console.log(process._getActiveHandles());
console.log(process._getActiveRequests());

三、日志调试

断点适合“知道大概在哪”,日志适合“线上/打包后不知道在哪”。Electron 的日志有两个坑:

所以正经项目建议直接上 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。对策:

五、常见症状速查

症状 大概率原因 处理办法
主进程 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 配置

六、推荐的日常工作流

  1. npm start 走 VS Code 的「调试主进程」配置,主进程可打断点、日志进集成终端。
  2. 窗口自动打开 DevTools(mode: 'detach'),渲染进程断点在 Sources 面板打。
  3. 关键路径(启动、IPC、网络、文件操作)用 log.info 打结构化日志,统一进 electron-log 文件。
  4. 收到用户问题时,让对方发 app.getPath('logs') 目录下的日志文件,而不是让他复述现象。
  5. 线上疑难问题,用带 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 调渲染进程
### 留存
- 关键路径结构化日志
### 排障
- 让用户发日志文件