差别
这里会显示出您选择的修订版和当前版本之间的差别。
| 后一修订版 | 前一修订版 | ||
| electron:调试 [2026/11/03 23:58] – 创建 张叶安 | electron:调试 [2026/11/03 23:59] (当前版本) – 追加 Electron 调试速查思维导图 张叶安 | ||
|---|---|---|---|
| 行 1: | 行 1: | ||
| - | 1 | + | ====== Electron 调试指南 ====== |
| + | |||
| + | Electron 里有**多个独立的 JS 运行环境**,这是调试的第一道坎:报错出现在哪里,决定了你该用哪套工具。 | ||
| + | |||
| + | ^ 运行环境 ^ 典型代码 ^ 用什么调试 ^ | ||
| + | | 主进程(Main) | '' | ||
| + | | 渲染进程(Renderer) | 页面里的 Vue/ | ||
| + | | preload 脚本 | '' | ||
| + | |||
| + | 排查顺序建议:**先看日志定位是哪个进程出错 → 再在该进程上打断点 → 用 CDP / Inspector 看运行时状态**。 | ||
| + | |||
| + | ===== 一、渲染进程:Chrome DevTools 断点调试 ===== | ||
| + | |||
| + | 渲染进程本质就是一个 Chromium 页面,调试方式和调网页完全一样。 | ||
| + | |||
| + | ==== 1.1 打开 DevTools ==== | ||
| + | |||
| + | 开发期最省事的做法是在创建窗口时直接打开: | ||
| + | |||
| + | ```js | ||
| + | const win = new BrowserWindow({ width: 1200, height: 800 }); | ||
| + | win.loadFile(' | ||
| + | // 分离窗口模式,避免和页面布局互相挤压 | ||
| + | win.webContents.openDevTools({ mode: ' | ||
| + | ``` | ||
| + | |||
| + | 或者保留默认菜单后按 '' | ||
| + | |||
| + | ```js | ||
| + | const { Menu } = require(' | ||
| + | Menu.setApplicationMenu(Menu.buildFromTemplate([ | ||
| + | { label: ' | ||
| + | ])); | ||
| + | ``` | ||
| + | |||
| + | 也可以在代码里用快捷键兜底: | ||
| + | |||
| + | ```js | ||
| + | const { globalShortcut } = require(' | ||
| + | globalShortcut.register(' | ||
| + | BrowserWindow.getFocusedWindow()? | ||
| + | }); | ||
| + | ``` | ||
| + | |||
| + | ==== 1.2 在 Sources 面板打断点 ==== | ||
| + | |||
| + | 1. 打开 DevTools → **Sources** 面板。 | ||
| + | 2. 左侧 '' | ||
| + | 3. 点行号打红点 → 触发对应操作 → 命中断点后可看作用域变量、调用栈、'' | ||
| + | 4. 也可以直接在代码里写 '' | ||
| + | |||
| + | **断点不生效的常见原因**:打包工具压缩了代码、sourcemap 没生成或路径不对。检查构建配置里 '' | ||
| + | |||
| + | ==== 1.3 远程调试端口 ==== | ||
| + | |||
| + | 想在**外部 Chrome** 里调渲染进程(比如内嵌页面不好操作、或在容器/ | ||
| + | |||
| + | ```bash | ||
| + | electron --remote-debugging-port=9222 . | ||
| + | ``` | ||
| + | |||
| + | 然后在本机 Chrome 打开 '' | ||
| + | |||
| + | ==== 1.4 用 CDP 在代码里主动抓信息 ==== | ||
| + | |||
| + | '' | ||
| + | |||
| + | ```js | ||
| + | win.webContents.debugger.attach(' | ||
| + | win.webContents.debugger.on(' | ||
| + | if (method === ' | ||
| + | console.log(' | ||
| + | } | ||
| + | }); | ||
| + | win.webContents.debugger.sendCommand(' | ||
| + | ``` | ||
| + | |||
| + | ===== 二、主进程:断点调试 ===== | ||
| + | |||
| + | 主进程是 Node.js 环境,**DevTools 的 Console 看不到它**,必须用 Node Inspector。 | ||
| + | |||
| + | ==== 2.1 命令行 '' | ||
| + | |||
| + | ```bash | ||
| + | # 启动并开启 Inspector,端口 5858 | ||
| + | electron --inspect=5858 . | ||
| + | |||
| + | # 在第一行代码前就停下(适合调试启动阶段的逻辑) | ||
| + | electron --inspect-brk=5858 . | ||
| + | ``` | ||
| + | |||
| + | 然后用 Chrome 打开 '' | ||
| + | |||
| + | > 提示:'' | ||
| + | |||
| + | ==== 2.2 VS Code:最推荐的方式 ==== | ||
| + | |||
| + | 在项目根目录建 '' | ||
| + | |||
| + | ```json | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | ] | ||
| + | }, | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | ] | ||
| + | } | ||
| + | ``` | ||
| + | |||
| + | 要点: | ||
| + | * '' | ||
| + | * Windows 必须用 '' | ||
| + | * '' | ||
| + | * 修改主进程代码后**必须重启**调试会话(Electron 主进程不支持热重载)。想省事可以装 '' | ||
| + | |||
| + | ```bash | ||
| + | nodemon --watch main.js --exec " | ||
| + | ``` | ||
| + | |||
| + | ==== 2.3 Electron Forge / electron-builder 项目 ==== | ||
| + | |||
| + | * **Electron Forge**:'' | ||
| + | * **electron-builder + vite / webpack 模板**:多数模板已内置 '' | ||
| + | * 使用 TypeScript 时,'' | ||
| + | |||
| + | ==== 2.4 主进程卡死怎么查 ==== | ||
| + | |||
| + | 界面无响应、日志突然断掉,通常是主进程被同步代码阻塞。处理办法: | ||
| + | |||
| + | 1. 用 '' | ||
| + | 2. 排查常见元凶:'' | ||
| + | 3. 打印活跃句柄,看有没有未释放的 timer / socket: | ||
| + | |||
| + | ```js | ||
| + | console.log(process._getActiveHandles()); | ||
| + | console.log(process._getActiveRequests()); | ||
| + | ``` | ||
| + | |||
| + | ===== 三、日志调试 ===== | ||
| + | |||
| + | 断点适合" | ||
| + | * 主进程的 '' | ||
| + | * 渲染进程的 '' | ||
| + | |||
| + | 所以正经项目建议直接上 '' | ||
| + | |||
| + | ==== 3.1 原生方式:先确认日志去哪了 ==== | ||
| + | |||
| + | ```bash | ||
| + | # 让 Chromium / Electron 内部日志(含渲染进程 console)输出到 stderr | ||
| + | electron --enable-logging . | ||
| + | # 等价的环境变量写法 | ||
| + | ELECTRON_ENABLE_LOGGING=1 electron . | ||
| + | ``` | ||
| + | |||
| + | '' | ||
| + | |||
| + | ==== 3.2 推荐:electron-log ==== | ||
| + | |||
| + | ```bash | ||
| + | npm i electron-log | ||
| + | ``` | ||
| + | |||
| + | 主进程里初始化一次: | ||
| + | |||
| + | ```js | ||
| + | // electron-log v5 | ||
| + | const log = require(' | ||
| + | log.initialize(); | ||
| + | |||
| + | // electron-log v4 的写法 | ||
| + | // const log = require(' | ||
| + | |||
| + | log.transports.file.level = ' | ||
| + | log.transports.console.level = ' | ||
| + | |||
| + | log.info(' | ||
| + | log.warn(' | ||
| + | log.error(' | ||
| + | ``` | ||
| + | |||
| + | 日志文件默认落在平台标准目录('' | ||
| + | |||
| + | ```js | ||
| + | const { shell } = require(' | ||
| + | shell.openPath(app.getPath(' | ||
| + | ``` | ||
| + | |||
| + | 在 preload 里暴露给渲染进程,页面日志就能和主进程日志写进同一个文件: | ||
| + | |||
| + | ```js | ||
| + | // preload.js | ||
| + | const log = require(' | ||
| + | contextBridge.exposeInMainWorld(' | ||
| + | ``` | ||
| + | |||
| + | ```js | ||
| + | // 渲染进程 | ||
| + | window.log.info(' | ||
| + | ``` | ||
| + | |||
| + | ==== 3.3 不用库:手动汇总渲染进程日志 ==== | ||
| + | |||
| + | 不想引依赖时,用 '' | ||
| + | |||
| + | ```js | ||
| + | app.on(' | ||
| + | wc.on(' | ||
| + | console.log(`[renderer: | ||
| + | }); | ||
| + | |||
| + | wc.on(' | ||
| + | console.error(`[renderer] 加载失败 ${code} ${desc} ${url}`); | ||
| + | }); | ||
| + | |||
| + | wc.on(' | ||
| + | console.error(' | ||
| + | }); | ||
| + | |||
| + | wc.on(' | ||
| + | console.error(' | ||
| + | }); | ||
| + | }); | ||
| + | ``` | ||
| + | |||
| + | '' | ||
| + | |||
| + | ==== 3.4 兜住未捕获异常与崩溃 ==== | ||
| + | |||
| + | ```js | ||
| + | process.on(' | ||
| + | log.error(' | ||
| + | }); | ||
| + | process.on(' | ||
| + | log.error(' | ||
| + | }); | ||
| + | |||
| + | const { crashReporter } = require(' | ||
| + | crashReporter.start({ | ||
| + | productName: | ||
| + | companyName: | ||
| + | submitURL: ' | ||
| + | uploadToServer: | ||
| + | compress: true | ||
| + | }); | ||
| + | ``` | ||
| + | |||
| + | ===== 四、打包之后的调试 ===== | ||
| + | |||
| + | 打包后调试变难,主要是**源码被 asar 包起来、被压缩、没有 sourcemap**。对策: | ||
| + | |||
| + | * 提供一个**开发构建**('' | ||
| + | * 保留 Inspector:'' | ||
| + | * 渲染进程仍可用 '' | ||
| + | * asar 内的源码路径在断点里可能显示为 '' | ||
| + | * 想看 asar 里的实际文件,用 '' | ||
| + | |||
| + | ===== 五、常见症状速查 ===== | ||
| + | |||
| + | ^ 症状 ^ 大概率原因 ^ 处理办法 ^ | ||
| + | | 主进程 '' | ||
| + | | 断点是灰的 / 打不上 | 代码被压缩,sourcemap 缺失或路径不匹配 | 构建时开 sourcemap,加 '' | ||
| + | | 页面白屏但没报错 | '' | ||
| + | | '' | ||
| + | | 改了主进程代码没生效 | Electron 主进程不热重载 | 重启调试会话,或用 '' | ||
| + | | 整个界面卡死 | 主进程同步阻塞 | '' | ||
| + | | DevTools 里只看到压缩代码 | 未生成 sourcemap | 开发构建 + 开启 JS source maps | | ||
| + | | '' | ||
| + | |||
| + | ===== 六、推荐的日常工作流 ===== | ||
| + | |||
| + | 1. '' | ||
| + | 2. 窗口自动打开 DevTools('' | ||
| + | 3. 关键路径(启动、IPC、网络、文件操作)用 '' | ||
| + | 4. 收到用户问题时,让对方发 '' | ||
| + | 5. 线上疑难问题,用带 sourcemap 的开发构建 + 打包版 '' | ||
| + | |||
| + | ===== 速查思维导图 ===== | ||
| + | |||
| + | ```mdk height=520 color=# | ||
| + | # Electron 调试 | ||
| + | |||
| + | ## 先分清进程 | ||
| + | ### 主进程 | ||
| + | - main.js / app.whenReady | ||
| + | - Node 环境,DevTools 看不到 | ||
| + | ### 渲染进程 | ||
| + | - 页面 Vue/ | ||
| + | - 等于调 Chromium 网页 | ||
| + | ### preload | ||
| + | - contextBridge | ||
| + | - 报错只在 preload-error 里 | ||
| + | |||
| + | ## 断点调试 | ||
| + | ### 渲染进程 | ||
| + | - Ctrl+Shift+I 开 DevTools | ||
| + | - Sources 面板打红点 | ||
| + | - debugger; 临时断点 | ||
| + | - 需 sourcemap 才能命中源码 | ||
| + | ### 主进程 | ||
| + | - electron --inspect=5858 . | ||
| + | - --inspect-brk 首行停住 | ||
| + | - chrome:// | ||
| + | - 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(' | ||
| + | - 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 调渲染进程 | ||
| + | ### 留存 | ||
| + | - 关键路径结构化日志 | ||
| + | ### 排障 | ||
| + | - 让用户发日志文件 | ||
| + | ``` | ||