36. 调试技巧

Electron 应用跑在两个进程里，调试方式因此分成两套。渲染进程能用熟悉的浏览器开发者工具；主进程藏在 Node 环境里，需要额外手段。本章给出最常用的调试组合拳，帮你从「瞎猜」变成「可定位」。

本节目标

• 用 DevTools 调试渲染进程。
• 通过 --inspect 与 chrome://inspect 调试主进程。
• 配置 VSCode 的 launch.json 一键断点调试。
• 用环境变量与命令行开关输出日志。
• 理解崩溃的常见信号与定位方向。

1-1 渲染进程：DevTools

渲染进程本质是 Chromium 页面，调试它就是用浏览器开发者工具。最方便的做法是在代码里主动打开：

// main.js（主进程）：为窗口打开 DevTools
const { BrowserWindow } = require('electron');

const win = new BrowserWindow({ width: 800, height: 600 });
win.loadFile('index.html');
win.webContents.openDevTools(); // 打开开发者工具

更常见的是手动操作：应用运行时按 F12（Windows/Linux）或 Cmd+Option+I（macOS）即可唤出。DevTools 的 Elements、Console、Network、Performance 面板与网页开发完全一致，是排查渲染层问题的首选。

1-2 主进程：—inspect

DevTools 只能调试窗口里的页面，无法触及主进程。要调试主进程，需让 Electron 暴露 V8 调试端口，再用外部调试器连接。

启动应用时加 --inspect 开关：

electron --inspect=9229 ./main.js

默认端口是 9229。想在第一行就暂停，用 --inspect-brk：

electron --inspect-brk=9229 ./main.js

随后打开 Chrome 浏览器，访问 chrome://inspect，在「Remote Target」里找到你的 Electron 应用并点击 inspect，就会弹出专为主进程准备的 DevTools。这里能打断点、看调用栈、单步执行。注意控制台里 require 可能不像网页里那样随手可用，这是正常现象。

1-3 VSCode 一键调试

每次手敲 --inspect 再切到浏览器太麻烦。VSCode 可以把这套流程固化成「按下 F5 即断点」。在工程根目录建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Main Process",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
      "windows": {
        "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd"
      },
      "args": ["."],
      "outputCapture": "std"
    }
  ]
}

在 main.js 里设好断点，按 F5 启动。VSCode 会用 --inspect 拉起 Electron 并自动连接调试器。这是日常开发主进程最高效的方式。Forge 工程同样适用，因为底层仍是同一个 electron 可执行文件。

1-4 日志输出

当断点不便使用时，老实的日志最可靠。主进程里用 console.log 会把内容打印到启动它的终端。配合环境变量可让 Electron 自身也吐出底层日志：

ELECTRON_ENABLE_LOGGING=true electron .

或在命令行加开关：

electron . --enable-logging

这两个方法都能把 Chromium 的内部日志输出到终端或文件，对排查渲染进程崩溃、GPU、网络问题很有用。可在 package.json 的 start 脚本里默认带上 ELECTRON_ENABLE_LOGGING，方便团队统一排错。

1-5 崩溃定位

渲染进程崩溃时，DevTools 会显示一句话：DevTools was disconnected from the page. 这说明 V8 上下文已挂掉。常见原因有无穷递归、内存暴涨、访问已销毁对象。先用 DevTools 的 Memory 面板看内存，再用 Performance 面板抓卡顿。

主进程崩溃往往让整个应用直接退出，终端留下堆栈或无声消失。定位思路：先用 --inspect-brk 缩小到出问题的函数，再用 ELECTRON_ENABLE_STACK_DUMPING 拿堆栈。若涉及原生模块，崩溃多发生在 .node 加载或调用时，需回到该模块源码排查。

对于发布后的应用，可借助 crashReporter 模块收集崩溃日志并上报，便于在用户环境复现问题。它需在 app 模块就绪早期初始化。

1-6 调试 checklist

遇到诡异 bug 时，建议按此顺序走：先在主进程加 console.log 确认流程走到哪；渲染问题直接开 DevTools；主进程逻辑错误用 VSCode 断点；底层崩溃开 ELECTRON_ENABLE_LOGGING；跨进程问题回顾 IPC 通道是否匹配（见第 11–14 章）。

1-7 渲染与主进程联合调试

复杂 bug 往往跨进程：渲染点击触发 IPC，主进程处理后回传。定位时两手并用：渲染侧开 DevTools 看请求是否发出、参数是否正确；主进程侧用 VSCode 断点看 ipcMain.handle 是否收到、返回值是否符合预期。两侧日志对上时差，问题通常就在 IPC 通道的某一端——常见的是 preload 里 contextBridge 暴露的方法名与渲染调用不一致。

常见误区

• 只在渲染进程找主进程的问题。DevTools 看不到主进程，需换 --inspect 或 VSCode。
• 忘记 --inspect-brk 的断点会卡住启动。调试完记得去掉该开关，否则应用一直停在第一行。
• 把 console.log 留在发布版。调试语句应随开发结束清理，或用环境变量控制开关。
• 崩溃后不看终端堆栈。主进程段错误常留下关键堆栈，开 ELECTRON_ENABLE_STACK_DUMPING 更易捕获。

1-8 远程调试多窗口与崩溃上报

当应用有多个 BrowserWindow 时，每个窗口的 DevTools 独立。主进程调试只需一套 --inspect，因为它对应的是唯一的 Node 环境。若某个窗口的渲染问题只在特定交互后出现，可在出问题的代码前用 debugger; 语句插入硬断点，配合 DevTools 的断点面板精准停住。注意 debugger; 在生产构建里也应移除，避免用户端意外暂停。

日志之外，Electron 还支持把崩溃上报到服务端。通过 crashReporter 模块在 app 就绪早期初始化，并配置上传地址，就能在用户环境自动收集 .dmp 文件，回到本地用符号表还原堆栈，这是定位偶发崩溃的有效手段。

1-9 控制台与终端的分工

渲染进程的 console.log 出现在 DevTools 的 Console 面板；主进程的 console.log 出现在启动它的终端。两者互不连通，排查跨进程问题时容易看错地方。养成习惯：渲染日志去 DevTools，主进程日志去终端，必要时在两侧都打同一标识，便于对照时间线。若终端看不到主进程输出，检查是否用了 electron-forge start 而非直接 electron，前者通常会转发日志。

小结

本章给出渲染进程 DevTools、主进程 --inspect、VSCode 启动配置、日志与崩溃定位的组合方案。调试是开发期的日常，而保证质量还需要自动化测试。下一章我们讲如何为 Electron 应用写测试。