Electron 全场景调试实战指南

前端架构师实战：Electron 全场景调试指南（Debug 从入门到精通）

作为前端架构师，在 Electron 项目开发中，调试能力是提升开发效率、快速排查线上问题、保障项目稳定性的核心能力。不同于纯 Web 项目（仅需浏览器 DevTools 即可完成调试），Electron 基于「主进程 + 渲染进程」的双进程架构，融合了 Node.js 与 Chromium 两大运行环境，调试场景更复杂------主进程的 Node.js 代码、渲染进程的 Web 代码、预加载脚本的桥接逻辑、IPC 跨进程通信、打包后崩溃、生产环境日志排查等，每一个场景都需要对应的调试方案。

很多开发者在 Electron 调试中常陷入困境：主进程代码断点不生效、IPC 消息收发丢失、预加载脚本不执行、开发环境正常但打包后崩溃、内存泄漏无法定位、启动慢找不到瓶颈......本文将从前端架构师视角，把 Electron 调试从基础到高级、从开发环境到生产环境，全场景、全流程拆解，包含详细的操作步骤、可直接复制的配置代码、实战案例、避坑指南，图文结合，让你彻底掌握 Electron Debug 技巧，轻松应对企业级项目中的各类调试问题。

bash 复制代码

Electron 调试与 Debug 全体系<br/>前端架构师技术博客
      1. 全覆盖调试场景
        主进程调试
        渲染进程调试
        预加载脚本调试
        IPC 通信调试
        崩溃调试(开发/生产)
        日志调试
        性能调试(启动/卡顿/内存泄漏)
        命令行调试
        VS Code 集成调试
      2. 实操性要求
        原理说明
        详细操作步骤
        可复制配置/命令
        预留图文节点
        常见问题排查
      3. 企业级需求
        调试/生产环境安全隔离
        调试不影响项目运行
        调试规范与最佳实践
      4. 内容与结构规范
        专业易懂｜适配全层级开发者
        博客标准结构
          前言
          核心原理
          分场景调试教程
          常见问题汇总
          架构师总结
          高频面试题
          实用工具推荐
      5. 图文要求
        关键操作步骤配图
        调试界面配图
        配置文件/代码片段配图
    二、Electron 调试核心原理
      双进程架构本质
        主进程：Node.js 环境｜系统原生能力
        渲染进程：Chromium 环境｜UI 渲染
        预加载脚本：双环境安全桥接
      调试协议差异
        主进程：Node.js Inspector 协议
        渲染进程：Chrome DevTools 协议
      IPC 通信调试原理
        跨进程消息链路
        上下文隔离安全约束
    三、分场景调试全教程(实操核心)
      1. VS Code 集成调试(企业首选)
        launch.json 完整配置
        主/渲染双进程联合调试
        断点/变量/调用栈调试
        常见问题：断点不生效排查
        预留图文：调试面板+断点效果图
      2. 渲染进程全量调试
        DevTools 自动开启配置
        Elements：UI/DOM/CSS 调试
        Console：日志/报错/命令执行
        Sources：断点/条件断点/日志断点
        Network：接口/跨域/资源调试
        Performance：卡顿/长任务分析
        Memory：内存泄漏堆快照排查
        预留图文：六大调试面板标注图
      3. 主进程专项调试
        VS Code 断点深度调试
        原生 API 调用报错排查
        应用生命周期监听调试
        窗口创建/销毁异常定位
        全局异常捕获配置
        预留图文：主进程终端日志截图
      4. 预加载脚本调试
        执行时机与运行环境原理
        VS Code 断点调试方案
        DevTools 溯源 preload 文件
        日志兜底调试法
        常见坑：路径/隔离导致不执行
        预留图文：preload 源码溯源示意图
      5. IPC 通信调试
        全局消息收发日志监听代码
        通道名匹配排查
        异步消息时序问题定位
        上下文隔离 API 暴露失败排查
        双向消息链路追踪
        预留图文：IPC 消息流转流程图
      6. 命令行应急调试
        --inspect 启动命令配置
        chrome://inspect 远程连接
        服务端/无头环境调试方案
        端口占用/连接失败排错
      7. 日志体系调试(生产必备)
        electron-log 集成方案
        开发/生产日志分级隔离
        多系统日志存储路径规范
        自定义错误日志落地
      8. 崩溃调试(开发+生产)
        crashReporter 崩溃上报配置
        主/渲染进程崩溃捕获
        打包后闪退黑屏溯源
        原生模块崩溃排查
      9. 性能专项调试
        启动耗时打点统计
        安装包臃肿优化溯源
        内存常驻泄漏定位
        界面卡顿/长任务阻塞优化
    四、企业级安全与规范
      环境隔离规范
        禁止生产开启 DevTools
        调试配置环境变量控制
        敏感日志生产脱敏
      调试代码规范
        禁止硬编码 debugger 上线
        日志分级管理
        IPC 调试监听仅开发生效
      工程化可维护性
        统一日志工具封装
        调试配置纳入工程化管理
    五、博客配套收尾模块
      常见问题 FAQ 汇总
        断点不生效
        IPC 收不到消息
        preload 不执行
        打包后崩溃
        内存泄漏/启动慢
      架构师全局总结
        多场景调试选型标准
        线上问题快速排查流程
        大型项目调试体系搭建
      高频面试题&解析
        双进程调试区别
        Preload 调试难点
        IPC 安全调试原则
        性能崩溃排查思路
      实用工具推荐
        electron-log
        crashReporter
        DevTools 性能插件
        内存分析工具

二、Electron 调试全场景实战博客（前端架构师版）

前言：为什么 Electron 调试比纯 Web 更复杂？

在开始调试之前，我们必须先明确 Electron 的核心架构------这是理解所有调试方式的基础，也是前端架构师必须吃透的核心点。

Electron 的本质是「Node.js + Chromium」的融合体，其双进程架构决定了调试的复杂性：

主进程（Main Process）：运行在 Node.js 环境中，负责应用生命周期管理、窗口创建与管理、系统原生资源调用（如本地文件、系统托盘、桌面通知），遵循 Node.js 调试协议，无法直接用浏览器 DevTools 调试；
渲染进程（Renderer Process）：每个窗口对应一个渲染进程，运行在 Chromium 环境中，负责 UI 渲染、用户交互、前端逻辑执行，调试方式与纯 Web 项目一致，可使用 Chrome DevTools；
预加载脚本（Preload Script）：介于主进程与渲染进程之间，运行在渲染进程中但拥有 Node.js 访问权限，负责安全桥接主进程与渲染进程的 API，调试需兼顾 Node.js 与 Chromium 两种环境；
IPC 通信：主进程与渲染进程之间的跨进程通信，消息丢失、通道写错、权限问题等，都需要专门的调试方式定位。

简单来说：Electron 是「一套应用、两套运行环境、多套调试方案」，只有掌握每种场景的调试技巧，才能高效排查问题。下面我们从基础到高级，逐一拆解所有调试场景。

第一章：核心准备------调试环境搭建（企业级规范）

在开始调试前，需先搭建标准的调试环境，避免因环境配置问题导致调试失败，以下是前端架构师推荐的企业级环境配置，适配 Windows、Mac、Linux 三大系统。

1.1 基础依赖配置

确保本地已安装以下依赖，版本需匹配（避免版本兼容问题）：

Node.js：推荐 LTS 版本（v16+，如 v18.17.0），与 Electron 最新稳定版兼容；
Electron：推荐 v28+（LTS 版本），稳定性更高，调试工具更完善；
VS Code：最新稳定版，集成调试能力最强，推荐作为主力调试工具；
依赖管理工具：npm/yarn/pnpm，推荐 pnpm（速度更快，依赖管理更规范）。

环境验证命令（终端执行）：

bash 复制代码

# 验证 Node.js 版本
node -v # 输出 v16+ 即可
# 验证 Electron 版本（项目内执行）
npx electron -v # 输出 v28+ 即可
# 验证 VS Code 调试功能
打开 VS Code → 左侧「运行和调试」→ 确认无报错

1.2 项目调试基础配置

在 Electron 项目根目录，添加以下基础配置，为后续调试做好准备：

创建环境变量配置文件（.env.development），区分开发/生产环境，避免调试配置污染生产环境：
# .env.development NODE_ENV=development ELECTRON_DEBUG=true
修改 package.json，添加调试启动脚本：
{ "name": "electron-debug-demo", "version": "1.0.0", "main": "./src/main/main.js", "scripts": { "start:dev": "cross-env NODE_ENV=development electron .", // 开发调试启动 "start:debug": "cross-env NODE_ENV=development electron --inspect=5858 .", // 命令行调试启动 "build": "electron-builder" // 打包脚本（后续用于打包后调试） }, "devDependencies": { "electron": "^28.0.0", "cross-env": "^7.0.3", // 跨系统环境变量配置 "electron-builder": "^24.6.4" } }说明：cross-env 用于跨系统统一环境变量，避免 Windows 与 Mac/Linux 环境变量配置差异导致的调试失败。

第二章：最推荐------VS Code 集成调试（企业级首选）

对于企业级 Electron 项目，VS Code 集成调试是首选方案------可一次性调试主进程、渲染进程、预加载脚本，支持断点调试、变量监控、调用栈分析、异常捕获，无需切换多个工具，效率最高。下面详细讲解配置步骤与实操细节。

2.1 配置 VS Code 调试文件（关键步骤）

在项目根目录创建 .vscode 文件夹，新建 launch.json 文件（调试配置文件），复制以下配置（可直接复用，无需修改核心内容，仅需调整路径适配自身项目）：

json 复制代码

{
  "version": "0.2.0",
  "configurations": [
    // 配置 1：调试主进程（Node.js 环境）
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Main Process（主进程）",
      "cwd": "${workspaceFolder}", // 项目根目录
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron", // Electron 可执行文件路径
      "windows": {
        "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd" // Windows 系统适配
      },
      "args": ["."], // 启动参数（指向项目主进程入口）
      "protocol": "inspector", // 调试协议（Node.js 最新调试协议）
      "console": "integratedTerminal", // 调试日志输出到 VS Code 集成终端
      "sourceMaps": true, // 开启 sourceMap，支持 TS 调试（若用 TS 开发）
      "outFiles": ["${workspaceFolder}/dist/**/*.js"], // 若用 TS 编译，指定输出文件路径
      "envFile": "${workspaceFolder}/.env.development" // 加载开发环境变量
    },
    // 配置 2：调试渲染进程（Chromium 环境）
    {
      "type": "chrome",
      "request": "attach",
      "name": "Debug Renderer（渲染进程）",
      "port": 9222, // 固定端口，与渲染进程调试端口一致
      "webRoot": "${workspaceFolder}", // 项目根目录
      "sourceMaps": true,
      "timeout": 30000, // 超时时间，避免调试连接失败
      "skipFiles": ["node_modules/**/*"] // 跳过 node_modules 文件夹，提升调试速度
    },
    // 配置 3：同时调试主进程 + 渲染进程（一键启动，推荐）
    {
      "name": "Debug All（主进程+渲染进程）",
      "configurations": ["Debug Main Process（主进程）", "Debug Renderer（渲染进程）"],
      "preLaunchTask": null
    }
  ]
}

配置说明（前端架构师重点关注）：

runtimeExecutable：需确保路径正确，若启动报错，可手动替换为项目内 electron 可执行文件路径（如 node_modules/.bin/electron）；
port：渲染进程调试端口固定为 9222，不可随意修改，否则无法 attach 到渲染进程；
sourceMaps：若项目使用 TypeScript 开发，必须开启，否则断点无法命中 TS 源码；
envFile：加载开发环境变量，避免调试时使用生产环境配置（如接口地址、权限配置）。

2.2 实操步骤：VS Code 调试全流程

配置完成后，按照以下步骤启动调试，全程可视化操作，新手也能快速上手：

打开 VS Code，加载 Electron 项目，确保 launch.json 配置无误；
点击左侧「运行和调试」按钮（快捷键 Ctrl+Shift+D / Cmd+Shift+D）；
在调试配置下拉框中，选择「Debug All（主进程+渲染进程）」，点击绿色「启动调试」按钮（快捷键 F5）；
启动后，Electron 应用会自动打开，同时 VS Code 进入调试模式，顶部会出现调试控制栏（继续、单步执行、单步跳过、单步进入、重启、停止）；
设置断点：
- 主进程断点：在 src/main/main.js 中，点击代码行号左侧，出现红色圆点（断点），如在 app.whenReady() 回调中设置断点；
- 渲染进程断点：在 src/renderer/js/renderer.js 中设置断点，或在 Chrome DevTools 中设置（后续会讲）；
- 预加载脚本断点：在 src/preload/preload.js 中设置断点，调试时会自动命中。
调试操作（核心技巧）：
- 继续（F5）：从当前断点继续执行，直到下一个断点；
- 单步跳过（F10）：执行当前行代码，不进入函数内部（适合快速排查流程）；
- 单步进入（F11）：进入当前行的函数内部（适合排查函数内的逻辑问题）；
- 单步退出（Shift+F11）：从当前函数退出，回到调用处；
- 变量监控：在 VS Code 右侧「变量」面板，可查看当前作用域下的所有变量值，也可手动添加监控（输入变量名）；
- 调用栈：右侧「调用栈」面板，可查看当前代码的调用链路，快速定位代码执行路径，排查异常出处。

图文节点：此处插入 2 张截图------1. VS Code 调试配置界面（launch.json 配置截图）；2. VS Code 调试中界面（断点命中、变量监控、调用栈展示）。

2.3 VS Code 调试避坑指南（架构师总结）

在实际调试中，很多开发者会遇到断点不生效、调试连接失败等问题，以下是高频坑点及解决方案，企业级项目必看：

坑点 1：主进程断点不生效 → 解决方案：
- 检查 launch.json 中 runtimeExecutable 路径是否正确，可手动替换为绝对路径；
- 确认项目启动脚本是否正确，是否加载了 .env.development 环境变量；
- 若用 TS 开发，检查 sourceMaps 是否开启，outFiles 路径是否正确。
坑点 2：渲染进程无法 attach 调试 → 解决方案：
- 确认 launch.json 中 port 为 9222，且渲染进程未被其他进程占用该端口；
- 在主进程创建窗口时，添加 webPreferences.devTools: true（开发环境开启）；
- 重启调试，先启动主进程调试，再 attach 渲染进程。
坑点 3：预加载脚本断点不命中 → 解决方案：
- 确认预加载脚本路径配置正确（webPreferences.preload）；
- 在预加载脚本开头添加 debugger; 语句，强制触发断点；
- 关闭 contextIsolation 后重试（仅调试时临时关闭，生产环境必须开启）。

第三章：渲染进程调试（和 Web 调试一致，细节拉满）

渲染进程运行在 Chromium 环境中，调试方式与纯 Web 项目（如 Vue、React 项目）基本一致，核心依赖 Chrome DevTools，适合排查 UI 渲染问题、前端逻辑问题、网络请求问题等。下面讲解具体操作的细节的避坑点。

3.1 自动打开 Chrome DevTools（开发环境）

在主进程创建窗口时，添加自动打开 DevTools 的代码，避免每次手动打开，提升开发效率，同时区分开发/生产环境（生产环境禁止打开 DevTools）：

javascript 复制代码

// src/main/main.js
const { app, BrowserWindow } = require('electron');
const path = require('path');
const dotenv = require('dotenv');

// 加载开发环境变量
dotenv.config({ path: '.env.development' });

let mainWindow;

function createWindow() {
  mainWindow = new BrowserWindow({
    width: 1200,
    height: 800,
    webPreferences: {
      preload: path.join(__dirname, '../preload/preload.js'),
      contextIsolation: true, // 生产环境必须开启，调试时可临时关闭
      nodeIntegration: false, // 禁止渲染进程直接访问 Node.js API
      devTools: process.env.NODE_ENV === 'development' // 开发环境开启 DevTools
    }
  });

  // 加载渲染进程页面（本地 HTML 文件）
  mainWindow.loadFile(path.join(__dirname, '../renderer/index.html'));

  // 开发环境：自动打开 DevTools，设置停靠位置（右侧）
  if (process.env.NODE_ENV === 'development') {
    mainWindow.webContents.openDevTools({
      mode: 'right' // 可选：right/left/bottom/undocked（浮动）
    });
  }

  // 监听 DevTools 打开事件（可选，用于调试日志输出）
  mainWindow.webContents.on('devtools-opened', () => {
    console.log('DevTools 已打开');
  });
}

app.whenReady().then(createWindow);
// 其他生命周期代码...

说明：devTools 配置必须区分环境，生产环境开启 DevTools 会带来安全风险（如用户可查看源码、修改前端逻辑），这是前端架构师必须关注的安全点。

3.2 Chrome DevTools 调试全功能详解

打开 DevTools 后（快捷键 Ctrl+Shift+I / Cmd+Opt+I），核心面板及调试功能如下，每个面板都对应具体的调试场景，前端架构师需熟练掌握：

3.2.1 Elements 面板：UI 调试

用于调试 DOM 结构、CSS 样式，与纯 Web 项目一致，核心操作：

查看/修改 DOM 结构：点击元素，可直接在面板中编辑标签、属性，实时生效；
调试 CSS 样式：在右侧「Styles」面板中，修改 CSS 属性（如颜色、尺寸、布局），实时预览效果，还可查看样式优先级、继承关系；
定位元素：点击左上角「选择元素」按钮，点击应用界面中的元素，可快速定位到对应的 DOM 节点；
避坑点：若样式不生效，检查是否被 Electron 原生样式覆盖，可添加 !important 临时测试（生产环境不推荐）。

图文节点：插入 Chrome DevTools Elements 面板截图，标注核心操作区域（DOM 编辑、CSS 调试）。

3.2.2 Console 面板：日志调试与命令执行

用于输出调试日志、执行临时命令、查看报错信息，是最常用的调试面板之一，核心操作：

日志输出：在渲染进程代码中，使用 console.log/info/warn/error 输出日志，在 Console 面板中查看，可添加分类标签（如 [IPC]、[UI]），方便筛选；
临时命令执行：在 Console 面板中，直接输入 JavaScript 代码（如获取 DOM 元素、调用函数），实时执行，快速测试逻辑；
报错定位：若渲染进程出现报错，Console 面板会显示报错信息、报错行号，点击行号可直接跳转到对应的源码位置；
过滤日志：使用面板顶部的过滤框，可按日志级别（Info/Warn/Error）、关键词筛选日志，提升排查效率；
架构师技巧：在开发环境，可封装日志工具，区分调试日志与生产日志，避免调试日志污染生产环境。

示例：渲染进程日志封装（可直接复用）

javascript 复制代码

// src/renderer/js/utils/logger.js
export const logger = {
  log: (...args) => {
    if (process.env.NODE_ENV === 'development') {
      console.log('[DEBUG][RENDERER]', ...args);
    }
  },
  warn: (...args) => {
    if (process.env.NODE_ENV === 'development') {
      console.warn('[WARN][RENDERER]', ...args);
    }
  },
  error: (...args) => {
    // 错误日志无论开发/生产都输出，用于排查线上问题
    console.error('[ERROR][RENDERER]', ...args);
  }
};

// 使用方式
import { logger } from './utils/logger';
logger.log('渲染进程初始化完成');
logger.error('接口请求失败', err);

3.2.3 Sources 面板：断点调试与源码查看

用于设置断点、调试 JavaScript 逻辑，核心操作与 VS Code 调试类似，重点关注：

源码定位：在左侧「Page」面板中，找到对应的 JS 文件（如 renderer.js、preload.js），点击打开，可直接设置断点；
断点类型：
- 普通断点：点击行号左侧，红色圆点，程序执行到该行会暂停；
- 条件断点：右键断点，选择「Edit breakpoint」，输入条件（如 i === 5），只有满足条件时才会暂停；
- 异常断点：点击面板顶部「暂停 on exceptions」按钮（红色停止按钮），程序出现异常时会自动暂停，方便排查异常原因；
- 日志断点：右键断点，选择「Add log point」，输入日志内容，程序执行到该行时会输出日志，不暂停程序（适合不影响流程的调试）。
调试操作：与 VS Code 一致，支持单步执行、单步跳过、单步进入、继续执行，右侧可查看变量、调用栈；
预加载脚本调试：在 Sources 面板中，找到「top → preload.js」，可直接设置断点，调试预加载脚本的逻辑。

图文节点：插入 Chrome DevTools Sources 面板截图，标注断点类型、调试控制栏、变量监控区域。

3.2.4 Network 面板：网络请求调试

用于调试渲染进程中的网络请求（如接口请求、静态资源加载），核心操作：

查看请求列表：所有网络请求会按时间顺序展示，包含请求方法、URL、状态码、响应时间、大小等信息；
筛选请求：可按请求类型（XHR/Fetch/JS/CSS/Img）、状态码、关键词筛选，快速定位目标请求；
查看请求详情：点击某条请求，可查看请求头、请求体、响应头、响应体，排查接口请求参数、响应数据是否正确；
模拟网络环境：点击面板顶部「No throttling」，可模拟慢网络（如 3G、4G），测试网络不佳时的应用表现；
避坑点：若接口请求失败，先检查是否跨域（Electron 开发环境可通过 webPreferences.webSecurity: false 临时关闭跨域限制，生产环境需后端配置 CORS）。

3.2.5 Performance 面板：性能调试（卡顿、启动慢）

用于排查渲染进程的性能问题，如界面卡顿、启动慢、动画不流畅等，核心操作：

点击面板顶部「Record」按钮（红色圆点），开始录制性能数据；
在应用中操作（如点击按钮、切换页面），执行需要排查的操作；
点击「Stop」按钮，停止录制，面板会展示性能分析报告；
重点关注：
- 长任务（Long Tasks）：红色标注的任务，执行时间超过 50ms，会导致界面卡顿，需优化对应的 JS 逻辑；
- 重绘（Repaint）/重排（Reflow）：频繁的重绘重排会导致性能下降，可通过「Paint flashing」功能查看（More tools → Paint flashing）；
- JS 执行时间：查看 JS 代码的执行耗时，定位耗时较长的函数，进行优化。

图文节点：插入 Chrome DevTools Performance 面板截图，标注长任务、重绘重排区域，说明优化方向。

3.2.6 Memory 面板：内存泄漏调试

用于排查渲染进程的内存泄漏问题（如页面切换后内存不释放、长期运行后内存持续上涨），核心操作：

打开 Memory 面板，选择「Heap snapshot」（堆快照）；
点击「Take snapshot」，生成当前内存堆快照；
在快照列表中，选择「Summary」视图，按「Retained Size」（保留大小）排序，查看占用内存较多的对象；
排查内存泄漏：
- 若某个对象在页面切换后仍未被释放（如全局变量、事件监听器未移除），则可能存在内存泄漏；
- 点击对象，可查看其引用链路，定位到未释放的原因（如未移除的事件绑定、未销毁的实例）。

架构师技巧：内存泄漏排查需结合场景，如多次切换页面、执行同一操作，观察内存是否持续上涨，若上涨后不回落，则大概率存在内存泄漏。

第四章：主进程调试（Node.js 环境，重点难点）

主进程运行在 Node.js 环境中，无法直接用 Chrome DevTools 调试，核心调试方式有两种：VS Code 集成调试（首选）、命令行调试（无 VS Code 环境时使用）。下面详细讲解两种方式的实操细节，以及主进程特有的调试场景。

4.1 VS Code 主进程调试（重温重点，补充细节）

前文已讲解 VS Code 集成调试的配置，此处重点补充主进程调试的特有细节，以及常见问题排查：

主进程断点设置：在主进程代码（如 main.js）中，可在以下关键位置设置断点，排查核心逻辑：
- 应用生命周期：app.whenReady()、app.on('window-all-closed')、app.on('activate') 等；
- 窗口创建：new BrowserWindow() 及相关配置；
- IPC 通信：ipcMain.on() 回调函数（排查消息接收问题）；
- 系统原生 API 调用：如 dialog.showOpenDialog()、tray.create() 等（排查原生能力调用失败）。
主进程日志输出：主进程的 console 日志会输出到 VS Code 集成终端（若配置了 console: "integratedTerminal"），也可通过以下方式查看：

`// 主进程日志输出到文件（开发环境可选）

const fs = require('fs');

const path = require('path');

const logPath = path.join(app.getPath('userData'), 'logs/main.log');

// 重写 console.log，输出到文件

const originalLog = console.log;

console.log = (...args) => {

originalLog(...args);

fs.appendFileSync(logPath, [${new Date().toLocaleString()}] [LOG] ${args.join(' ')}\n);

};

主进程异常捕获：主进程的未捕获异常会导致应用崩溃，需添加异常捕获，方便调试：
// 主进程未捕获异常捕获 process.on('uncaughtException', (err) => { console.error('主进程未捕获异常：', err); // 可选：记录异常日志到文件，方便后续排查 fs.appendFileSync(logPath, [ ${new Date().toLocaleString()}\] \[ERROR\]$ {err.stack}\n`);
});

// 主进程未处理的拒绝（Promise 异常）捕获

process.on('unhandledRejection', (reason, promise) => {

console.error('主进程未处理的 Promise 拒绝：', reason, promise);

fs.appendFileSync(logPath, [${new Date().toLocaleString()}] [REJECTION] ${reason}\n);

});

4.2 命令行调试（无 VS Code 环境，应急方案）

当在服务器、无界面环境或无法使用 VS Code 时，可通过命令行调试主进程，核心依赖 Node.js 调试协议，步骤如下：

启动主进程调试，指定调试端口（如 5858）：
`# 方式 1：使用项目启动脚本（推荐）
npm run start:debug

方式 2：直接执行 electron 命令

npx electron --inspect=5858 .

`说明：--inspect=5858 表示开启 Node.js 调试协议，监听 5858 端口，可自定义端口（如 9229），但需确保端口未被占用。

连接调试端口，有两种方式：
- 方式 1：使用 Chrome 调试（推荐）：
  - 打开 Chrome 浏览器，输入地址：chrome://inspect；
  - 点击「Configure」按钮，添加调试地址：localhost:5858；
  - 等待 Chrome 识别到调试目标，点击「inspect」按钮，即可打开调试界面（与 Node.js 调试界面一致）；
  - 在调试界面中，可设置断点、查看变量、执行调试操作，与 VS Code 调试类似。
- 方式 2：使用 Node.js 自带的调试工具（不推荐，体验较差）：
  node inspect localhost:5858 进入调试模式后，可使用命令调试（如 c：继续、n：单步跳过、s：单步进入、repl：执行临时命令）。

图文节点：插入 Chrome 浏览器 chrome://inspect 界面截图，标注配置调试地址、连接调试目标的操作步骤。

4.3 主进程特有调试场景（架构师重点关注）

主进程的调试场景与渲染进程不同，重点关注系统原生能力调用、应用生命周期、IPC 通信接收等场景，以下是高频调试场景及技巧：

4.3.1 窗口创建失败调试

若主进程创建窗口失败（应用启动后无窗口显示），可按以下步骤排查：

在 new BrowserWindow() 前后设置断点，查看配置是否正确；
检查窗口配置：如 width/height 是否为 0、webPreferences.preload 路径是否正确、icon 路径是否存在；
添加窗口创建失败监听：
mainWindow.on('error', (err) => { console.error('窗口创建失败：', err); });
检查是否有其他进程占用窗口资源，重启应用重试。

4.3.2 系统原生 API 调用失败调试

主进程调用系统原生 API（如 dialog、tray、notification）失败时，可按以下步骤排查：

在 API 调用前后设置断点，查看参数是否正确（如 dialog.showOpenDialog() 的 options 配置）；
检查 API 调用时机：部分 API 需在 app.whenReady() 回调中调用（如 tray 创建），否则会失败；
捕获 API 调用异常：try { const result = await dialog.showOpenDialog(mainWindow, { properties: ['openDirectory'] }); console.log('对话框结果：', result); } catch (err) { console.error('对话框调用失败：', err); }
检查系统权限：如 Mac 系统需在「系统设置 → 隐私与安全性」中，授予应用对应的权限（如文件访问权限）。

第五章：预加载脚本调试（最容易踩坑，细节详解）

预加载脚本（Preload Script）是 Electron 调试中最容易踩坑的场景------它运行在「渲染进程的 Node.js 上下文」中，既不是纯主进程，也不是纯渲染进程，调试方式需兼顾两者。下面讲解预加载脚本的调试方法、常见问题及解决方案。

5.1 预加载脚本调试的核心原理

预加载脚本的运行机制：

运行时机：在渲染进程加载页面（HTML）之前执行，先于渲染进程的 JS 代码；
运行环境：拥有 Node.js 访问权限（可调用 fs、path 等 Node 模块），但运行在渲染进程中；
核心作用：通过 contextBridge 模块，将主进程的 API 安全暴露到渲染进程，避免直接开启 nodeIntegration 带来的安全风险；
调试难点：开启 contextIsolation: true 后，预加载脚本与渲染进程的全局作用域隔离，无法直接访问 window 对象（需通过 contextBridge 暴露），断点难以命中。

5.2 预加载脚本调试的 3 种方法（按推荐度排序）

方法 1：VS Code 集成调试（首选）

通过 VS Code 调试主进程时，预加载脚本的断点会自动命中，步骤如下：

确保 VS Code launch.json 配置正确（前文已提供）；
在预加载脚本（preload.js）中设置断点（如在 contextBridge.exposeInMainWorld 前后）；
启动 VS Code 调试（Debug All），当应用启动、预加载脚本执行时，会自动命中断点；
调试操作：与主进程调试一致，可查看变量、调用栈，单步执行代码。

避坑点：若断点不命中，检查以下几点：

webPreferences.preload 路径是否正确（绝对路径/相对路径是否匹配）；
是否开启了 contextIsolation: true，临时关闭后重试（调试完成后需开启）；
预加载脚本是否有语法错误，导致脚本无法执行（可在主进程日志中查看报错）。

方法 2：Chrome DevTools 调试

通过渲染进程的 Chrome DevTools，可直接调试预加载脚本，步骤如下：

启动应用，确保 DevTools 已打开（开发环境自动打开）；
打开 DevTools → Sources 面板 → 左侧「Page」面板 → 找到「top → preload.js」（若未找到，刷新页面重试）；
点击打开 preload.js，设置断点，刷新页面，断点会命中；
调试操作：与渲染进程调试一致，可查看变量、执行代码，但需注意：预加载脚本中无法直接访问渲染进程的 window 对象（需通过 contextBridge 暴露）。

示例：预加载脚本调试代码（含断点位置）

javascript 复制代码

// src/preload/preload.js
const { contextBridge, ipcRenderer } = require('electron');

// 断点位置 1：脚本开头，检查脚本是否执行
console.log('预加载脚本开始执行');

// 断点位置 2：contextBridge 暴露 API 前，检查 API 定义
const exposeAPI = {
  sendMessage: (channel, data) => {
    // 断点位置 3：发送 IPC 消息时，检查参数
    console.log('发送 IPC 消息：', channel, data);
    ipcRenderer.send(channel, data);
  },
  onReply: (channel, callback) => {
    ipcRenderer.on(channel, (event, data) => callback(data));
  }
};

// 暴露 API 到渲染进程
contextBridge.exposeInMainWorld('electronAPI', exposeAPI);

// 断点位置 4：脚本执行完成，检查 API 是否暴露成功
console.log('预加载脚本执行完成，API 已暴露');

方法 3：日志调试（应急方案）

若以上两种方法均无法调试，可通过日志输出的方式，排查预加载脚本的执行逻辑，步骤如下：

在预加载脚本的关键位置，添加 console.log 日志，输出变量值、执行状态；
启动应用，查看日志：
- 若使用 VS Code 调试，日志会输出到 VS Code 集成终端；
- 若使用命令行启动，日志会输出到终端；
- 也可将日志输出到文件，方便后续排查。
根据日志输出，定位脚本执行异常的位置（如某行代码未执行、变量值异常）。

5.3 预加载脚本高频调试问题（避坑指南）

问题 1：预加载脚本不执行 → 解决方案：
- 检查 webPreferences.preload 路径是否正确，推荐使用 path.join 拼接绝对路径；
- 检查预加载脚本是否有语法错误（如拼写错误、缺少分号），可通过 node 命令单独执行脚本，排查语法错误；
- 检查是否开启了 webPreferences.sandbox: true，沙箱模式会限制预加载脚本的执行，调试时可临时关闭。
问题 2：contextBridge 暴露的 API，渲染进程无法访问 → 解决方案：
- 检查暴露 API 的名称是否正确（如 electronAPI 是否拼写一致）；
- 确保 contextBridge.exposeInMainWorld 的第二个参数是对象，且方法定义正确；
- 检查是否开启了 contextIsolation: true，只有开启上下文隔离，contextBridge 才能正常工作；
- 在渲染进程中，通过 console.log(window.electronAPI) 查看 API 是否暴露成功。
问题 3：预加载脚本中无法调用 Node.js 模块 → 解决方案：
- 检查是否开启了 nodeIntegration: false，预加载脚本默认拥有 Node.js 访问权限，与 nodeIntegration 配置无关；
- 检查模块是否安装成功（如 fs 是 Node.js 原生模块，无需安装，其他第三方模块需确保已安装）；
- 检查是否开启了沙箱模式（sandbox: true），沙箱模式会限制 Node.js 模块的调用，调试时可临时关闭。

第六章：IPC 通信调试（跨进程消息，高频场景）

IPC（Inter-Process Communication）是主进程与渲染进程之间的核心通信方式，也是 Electron 项目中最容易出现问题的场景------消息丢失、通道名称写错、权限问题、异步时序问题等，都需要专门的调试方式定位。下面讲解 IPC 通信的全场景调试方法，企业级项目必用。

6.1 IPC 通信调试的核心思路

IPC 通信调试的核心是「监控消息的发送与接收」，明确消息是否发送成功、是否被接收、参数是否正确、时序是否合理，具体思路：

给所有 IPC 消息添加日志，记录发送/接收状态、参数、时间；
使用断点调试，定位消息发送/接收的异常位置；
使用专门的 IPC 调试工具，可视化监控消息流转；
排查常见问题：通道名称不一致、消息发送时机过早（如渲染进程未初始化完成）、权限限制导致消息被拦截。

6.2 基础调试：日志监控（最常用）

在主进程和渲染进程中，分别添加 IPC 消息日志监控，记录所有消息的发送与接收，可直接复用以下代码：

6.2.1 主进程 IPC 日志监控

javascript 复制代码

// src/main/main.js
const { ipcMain } = require('electron');

// 监控所有 IPC 消息接收（主进程）
ipcMain.on('*', (event, ...args) => {
  console.log(`[IPC 主进程接收] 通道：${event.channel}，参数：`, ...args);
  // 记录消息来源（渲染进程 ID）
  console.log(`[IPC 来源] 渲染进程 ID：${event.sender.id}`);
});

// 重写 ipcMain.on 方法，监控所有监听
const originalIpcOn = ipcMain.on;
ipcMain.on = (channel, listener) => {
  console.log(`[IPC 主进程监听] 通道：${channel}`);
  return originalIpcOn.call(ipcMain, channel, (event, ...args) => {
    console.log(`[IPC 主进程接收] 通道：${channel}，参数：`, ...args);
    listener(event, ...args);
  });
};

// 监控 IPC 消息回复
ipcMain.on('message-from-renderer', (event, data) => {
  console.log('[IPC 主进程接收] message-from-renderer：', data);
  // 回复消息
  event.reply('message-from-main', '已收到消息');
  console.log('[IPC 主进程发送] message-from-main：已收到消息');
});

6.2.2 渲染进程 IPC 日志监控

javascript 复制代码

// src/renderer/js/utils/ipcLogger.js
import { ipcRenderer } from 'electron';

// 监控所有 IPC 消息发送（渲染进程）
const originalSend = ipcRenderer.send;
ipcRenderer.send = (channel, ...args) => {
  console.log(`[IPC 渲染进程发送] 通道

（注：文档部分内容可能由 AI 生成）