====== 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 调渲染进程 ### 留存 - 关键路径结构化日志 ### 排障 - 让用户发日志文件 ```