electron:调试

差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

后一修订版
前一修订版
electron:调试 [2026/11/03 23:58] – 创建 张叶安electron:调试 [2026/11/03 23:59] (当前版本) – 追加 Electron 调试速查思维导图 张叶安
行 1: 行 1:
-1+====== 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 ==== 
 + 
 +开发期最省事的做法是在创建窗口时直接打开: 
 + 
 +```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'' 角色去掉了,可以手动加一个: 
 + 
 +```js 
 +const { Menu } = require('electron'); 
 +Menu.setApplicationMenu(Menu.buildFromTemplate([ 
 +  { label: '开发', submenu: [{ role: 'toggleDevTools' }, { role: 'reload' }] } 
 +])); 
 +``` 
 + 
 +也可以在代码里用快捷键兜底: 
 + 
 +```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** 里调渲染进程(比如内嵌页面不好操作、或在容器/远程机器上跑),启动时加: 
 + 
 +```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'': 
 + 
 +```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'': 
 + 
 +```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 主进程卡死怎么查 ==== 
 + 
 +界面无响应、日志突然断掉,通常是主进程被同步代码阻塞。处理办法: 
 + 
 +1. 用 ''--inspect'' 启动,在 DevTools 里点 **Pause**(或 F8),看当前停在哪个调用栈——卡死时通常能直接抓到阻塞点。 
 +2. 排查常见元凶:''fs.readFileSync'' 大文件、''execSync''、超长循环、重复的 ''dialog.showMessageBoxSync''。 
 +3. 打印活跃句柄,看有没有未释放的 timer / socket: 
 + 
 +```js 
 +console.log(process._getActiveHandles()); 
 +console.log(process._getActiveRequests()); 
 +``` 
 + 
 +===== 三、日志调试 ===== 
 + 
 +断点适合"知道大概在哪",日志适合"线上/打包后不知道在哪"。Electron 的日志有两个坑: 
 +  * 主进程的 ''console.log'' 输出到**启动它的终端**,Windows 上打包成 GUI 程序后没有终端,等于全部丢失。 
 +  * 渲染进程的 ''console.log'' 只进 DevTools 的 Console,不进终端,也不好留存。 
 + 
 +所以正经项目建议直接上 ''electron-log'',把三个进程的日志汇总到一个文件。 
 + 
 +==== 3.1 原生方式:先确认日志去哪了 ==== 
 + 
 +```bash 
 +# 让 Chromium / Electron 内部日志(含渲染进程 console)输出到 stderr 
 +electron --enable-logging . 
 +# 等价的环境变量写法 
 +ELECTRON_ENABLE_LOGGING=1 electron . 
 +``` 
 + 
 +''--enable-logging'' 之后,渲染进程的 console 也会打到终端,这在排查"页面白屏但 DevTools 打不开"时非常有用。 
 + 
 +==== 3.2 推荐:electron-log ==== 
 + 
 +```bash 
 +npm i electron-log 
 +``` 
 + 
 +主进程里初始化一次: 
 + 
 +```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')''),可以直接在界面上加一个"打开日志目录"按钮方便用户反馈: 
 + 
 +```js 
 +const { shell } = require('electron'); 
 +shell.openPath(app.getPath('logs')); 
 +``` 
 + 
 +在 preload 里暴露给渲染进程,页面日志就能和主进程日志写进同一个文件: 
 + 
 +```js 
 +// preload.js 
 +const log = require('electron-log/renderer'); 
 +contextBridge.exposeInMainWorld('log', log); 
 +``` 
 + 
 +```js 
 +// 渲染进程 
 +window.log.info('用户点击了导出按钮'); 
 +``` 
 + 
 +==== 3.3 不用库:手动汇总渲染进程日志 ==== 
 + 
 +不想引依赖时,用 ''web-contents-created'' 把所有窗口的 console、加载失败、崩溃事件统一接管: 
 + 
 +```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 兜住未捕获异常与崩溃 ==== 
 + 
 +```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 配置 | 
 + 
 +===== 六、推荐的日常工作流 ===== 
 + 
 +1. ''npm start'' 走 VS Code 的「调试主进程」配置,主进程可打断点、日志进集成终端。 
 +2. 窗口自动打开 DevTools(''mode: 'detach'''),渲染进程断点在 Sources 面板打。 
 +3. 关键路径(启动、IPC、网络、文件操作)用 ''log.info'' 打结构化日志,统一进 ''electron-log'' 文件。 
 +4. 收到用户问题时,让对方发 ''app.getPath('logs')'' 目录下的日志文件,而不是让他复述现象。 
 +5. 线上疑难问题,用带 sourcemap 的开发构建 + 打包版 ''--inspect'' 复现。 
 + 
 +===== 速查思维导图 ===== 
 + 
 +```mdk height=520 color=#4f46e5 
 +# 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 调渲染进程 
 +### 留存 
 +- 关键路径结构化日志 
 +### 排障 
 +- 让用户发日志文件 
 +``` 

该主题尚不存在

您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。

  • electron/调试.1793721505.txt.gz
  • 最后更改: 2026/11/03 23:58
  • 由 张叶安