Electron 调试指南

徐建国

发布于 2025-11-29 15:10:57

3330

文章被收录于专栏：个人路线个人路线

Electron 调试指南

本文档详细介绍 Electron 应用的调试方法，包括渲染进程调试、主进程调试、以及各种调试技巧和最佳实践。

适用版本： Electron 20+ 难度等级： ⭐⭐ 中级

一、渲染进程调试

渲染进程（Renderer Process）负责显示应用界面，调试方法与普通网页开发类似，可以使用 Chrome DevTools。

1.1 方案一：手动打开 DevTools（推荐）

适用场景： 日常开发调试

操作步骤：

运行 Electron 应用
在应用窗口的置顶工具栏中找到调试按钮
点击打开开发者工具

优点：

✅ 简单易操作，无需修改代码
✅ 可以随时打开/关闭，不影响代码
✅ 适合快速调试

操作示例：

手动打开 DevTools

1.2 方案二：代码自动打开 DevTools

适用场景： 需要每次启动时自动打开调试工具

实现方法：

在 main.js 文件的 createWindow() 函数中，添加 openDevTools() 调用：

const { app, BrowserWindow } = require('electron');
const path = require('path');

let mainWindow;

function createWindow() {
    mainWindow = new BrowserWindow({
        width: 800,
        height: 600,
        webPreferences: {
            nodeIntegration: false,
            contextIsolation: true,
            preload: path.join(__dirname, 'preload.js')
        }
    });

    mainWindow.loadFile('index.html');

    // 自动打开开发者工具
    mainWindow.webContents.openDevTools();
}

app.whenReady().then(() => {
    createWindow();
});

代码说明：

mainWindow.webContents.openDevTools() - 打开开发者工具

可以添加参数控制 DevTools 的位置和模式：

// 在右侧打开（默认）
mainWindow.webContents.openDevTools();

// 在底部打开
mainWindow.webContents.openDevTools({ mode: 'bottom' });

// 分离窗口
mainWindow.webContents.openDevTools({ mode: 'detach' });

运行效果：

自动打开 DevTools

优点：

✅ 启动即打开，无需手动操作
✅ 适合持续开发阶段

缺点：

⚠️ 需要修改代码
⚠️ 生产环境需要移除或条件判断

生产环境优化：

// 只在开发环境打开 DevTools
if (process.env.NODE_ENV === 'development') {
    mainWindow.webContents.openDevTools();
}

1.3 快捷键打开 DevTools

HarmonyOS PC：

Ctrl + Shift + I - 打开/关闭 DevTools

Windows/Linux：

Ctrl + Shift + I - 打开/关闭 DevTools
F12 - 打开/关闭 DevTools

macOS：

Cmd + Option + I - 打开/关闭 DevTools
Cmd + Option + J - 打开控制台

注意： 快捷键需要在窗口获得焦点时才能使用。

1.4 DevTools 功能使用

打开 DevTools 后，可以使用以下功能：

Elements - 查看和编辑 DOM 结构
Console - 查看日志、执行 JavaScript 代码
Sources - 调试 JavaScript 代码，设置断点
Network - 监控网络请求
Application - 查看存储、缓存等信息
Performance - 性能分析
Memory - 内存分析

二、主进程调试

主进程（Main Process）负责管理应用生命周期和创建窗口，调试相对复杂一些。

2.1 使用 VS Code 调试主进程

推荐方案： 使用 VS Code 的调试功能

2.1.1 配置 launch.json

在项目根目录创建 .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",
            "console": "integratedTerminal"
        },
        {
            "name": "Debug Main Process (with DevTools)",
            "type": "node",
            "request": "launch",
            "cwd": "${workspaceFolder}",
            "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
            "windows": {
                "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd"
            },
            "args": [
                ".",
                "--remote-debugging-port=9222"
            ],
            "outputCapture": "std",
            "console": "integratedTerminal"
        }
    ]
}

2.1.2 开始调试

在 main.js 中设置断点（点击行号左侧）
按 F5 或点击"运行和调试"
选择 "Debug Main Process"
程序会在断点处暂停，可以查看变量、调用栈等

调试功能：

✅ 设置断点
✅ 单步执行（F10）
✅ 单步进入（F11）
✅ 查看变量值
✅ 查看调用栈
✅ 监视表达式

2.2 使用 Chrome DevTools 调试主进程

2.2.1 启动调试模式

在启动 Electron 时添加 --inspect 参数：

# 方式一：命令行启动
electron --inspect=9222 .

# 方式二：修改 package.json
{
  "scripts": {
    "start": "electron .",
    "debug": "electron --inspect=9222 ."
  }
}

2.2.2 连接 Chrome DevTools

打开 Chrome 浏览器
访问 chrome://inspect
在 "Remote Target" 下找到您的 Electron 应用
点击 "inspect" 链接

注意： 需要 Chrome 浏览器版本 55+。

2.3 使用 console.log 调试

最简单的方法，在主进程中添加日志：

const { app, BrowserWindow } = require('electron');

console.log('应用启动中...');
console.log('Node 版本:', process.versions.node);
console.log('Electron 版本:', process.versions.electron);

function createWindow() {
    console.log('创建窗口...');
    const mainWindow = new BrowserWindow({
        width: 800,
        height: 600
    });
    console.log('窗口创建完成');
    mainWindow.loadFile('index.html');
}

查看日志：

终端窗口（命令行启动时）
VS Code 集成终端
系统控制台

三、调试技巧与最佳实践

3.1 条件调试

只在特定条件下打开 DevTools：

function createWindow() {
    const mainWindow = new BrowserWindow({
        width: 800,
        height: 600,
        webPreferences: {
            nodeIntegration: false,
            contextIsolation: true,
            preload: path.join(__dirname, 'preload.js')
        }
    });

    mainWindow.loadFile('index.html');

    // 开发环境自动打开 DevTools
    if (process.env.NODE_ENV === 'development' ||
        process.argv.includes('--dev')) {
        mainWindow.webContents.openDevTools();
    }
}

启动时指定环境变量：

# Windows
set NODE_ENV=development && npm start

# macOS/Linux
NODE_ENV=development npm start

# 或使用命令行参数
npm start -- --dev

3.2 多窗口调试

如果有多个窗口，可以为每个窗口单独控制 DevTools：

function createWindow() {
    const mainWindow = new BrowserWindow({
        width: 800,
        height: 600
    });

    const secondWindow = new BrowserWindow({
        width: 600,
        height: 400
    });

    mainWindow.loadFile('index.html');
    secondWindow.loadFile('second.html');

    // 只为主窗口打开 DevTools
    if (process.env.NODE_ENV === 'development') {
        mainWindow.webContents.openDevTools();
    }
}

3.3 远程调试

允许从外部连接调试：

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

// 启动时添加远程调试端口
app.commandLine.appendSwitch('remote-debugging-port', '9222');

function createWindow() {
    const mainWindow = new BrowserWindow({
        width: 800,
        height: 600
    });
    mainWindow.loadFile('index.html');
}

app.whenReady().then(() => {
    createWindow();
});

然后可以在 Chrome 中访问 http://localhost:9222 进行调试。

3.4 性能调试

使用 Chrome DevTools 的性能分析工具：

// 在代码中标记性能点
console.time('窗口创建');
const mainWindow = new BrowserWindow({...});
console.timeEnd('窗口创建');

在 DevTools 的 Performance 面板中：

点击录制按钮
执行操作
停止录制
查看性能分析报告

3.5 内存调试

检查内存泄漏：

// 定期输出内存使用情况
setInterval(() => {
    const memUsage = process.memoryUsage();
    console.log('内存使用:', {
        rss: `${Math.round(memUsage.rss / 1024 / 1024)} MB`,
        heapTotal: `${Math.round(memUsage.heapTotal / 1024 / 1024)} MB`,
        heapUsed: `${Math.round(memUsage.heapUsed / 1024 / 1024)} MB`
    });
}, 5000);

使用 DevTools 的 Memory 面板：

拍摄堆快照
对比不同时间点的内存使用
查找内存泄漏

3.6 网络调试

监控网络请求：

// 监听所有网络请求
mainWindow.webContents.on('did-finish-load', () => {
    mainWindow.webContents.debugger.attach('1.1');

    mainWindow.webContents.debugger.on('message', (event, method, params) => {
        if (method === 'Network.responseReceived') {
            console.log('网络请求:', params.response.url);
        }
    });
});

或在 DevTools 的 Network 面板中直接查看。

四、常见问题排查

4.1 DevTools 无法打开

问题： 点击按钮或快捷键无法打开 DevTools

解决方案：

检查窗口焦点

// 确保窗口获得焦点
mainWindow.focus();

检查 webPreferences 配置

webPreferences: {
    devTools: true  // 确保未禁用 DevTools
}

手动调用 API

mainWindow.webContents.openDevTools();

4.2 断点不生效

问题： VS Code 中设置断点但程序不暂停

解决方案：

确认使用的是 "Debug Main Process" 配置
检查 launch.json 配置是否正确
确认代码已保存
尝试重新启动调试会话

4.3 控制台输出乱码

问题： 终端输出中文乱码

解决方案：

// 设置输出编码
process.stdout.setEncoding('utf8');
process.stderr.setEncoding('utf8');

或在启动时设置环境变量：

# Windows
chcp 65001 && npm start

# macOS/Linux
export LANG=zh_CN.UTF-8 && npm start

4.4 调试时应用卡死

问题： 调试时应用无响应

解决方案：

检查是否有无限循环
使用 console.log 定位卡死位置
检查是否有阻塞操作（同步文件操作等）
使用异步操作替代同步操作

五、调试工具推荐

5.1 VS Code 扩展

Electron - Electron 开发支持
Debugger for Chrome - Chrome 调试支持
JavaScript Debugger - JavaScript 调试增强

5.2 Chrome 扩展

React Developer Tools - 如果使用 React
Vue.js devtools - 如果使用 Vue
Redux DevTools - 如果使用 Redux

5.3 命令行工具

electron-debug - Electron 调试工具包

npm install --save-dev electron-debug

使用：

require('electron-debug')({ showDevTools: true });

六、调试最佳实践总结

✅ 推荐做法

开发环境自动打开 DevTools

if (process.env.NODE_ENV === 'development') {
    mainWindow.webContents.openDevTools();
}

使用条件断点

只在特定条件下暂停
避免频繁中断

合理使用 console.log

使用不同级别的日志（info, warn, error）
生产环境移除或使用日志库

定期检查性能

使用 Performance 面板
监控内存使用

版本控制忽略调试配置

# .gitignore
.vscode/launch.json  # 个人调试配置

❌ 避免的做法

生产环境保留 DevTools
- 影响性能
- 安全风险
过度使用 console.log
- 影响性能
- 代码混乱
忽略错误处理
- 使用 try-catch
- 监听错误事件

七、参考资料

Electron 官方调试文档[6]
Chrome DevTools 文档[7]
VS Code 调试文档[8]
Electron 调试最佳实践[9]

参考资料

[1]

一、渲染进程调试: #一渲染进程调试

[2]

二、主进程调试: #二主进程调试

[3]

三、调试技巧与最佳实践: #三调试技巧与最佳实践

[4]

四、常见问题排查: #四常见问题排查

[5]

五、调试工具推荐: #五调试工具推荐

[6]

Electron 官方调试文档: https://www.electronjs.org/docs/latest/tutorial/debugging

[7]

Chrome DevTools 文档: https://developer.chrome.com/docs/devtools/

[8]

VS Code 调试文档: https://code.visualstudio.com/docs/editor/debugging

[9]

Electron 调试最佳实践: https://www.electronjs.org/docs/latest/tutorial/debugging-main-process

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2025-11-12，如有侵权请联系 cloudcommunity@tencent.com 删除

electron

本文分享自大前端之旅微信公众号，前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度

Electron 调试指南

Electron 调试指南

Electron 调试指南

一、渲染进程调试

1.1 方案一：手动打开 DevTools（推荐）

1.2 方案二：代码自动打开 DevTools

1.3 快捷键打开 DevTools

1.4 DevTools 功能使用

二、主进程调试

2.1 使用 VS Code 调试主进程

2.1.1 配置 launch.json

2.1.2 开始调试

2.2 使用 Chrome DevTools 调试主进程

2.2.1 启动调试模式

2.2.2 连接 Chrome DevTools

2.3 使用 console.log 调试

三、调试技巧与最佳实践

3.1 条件调试

3.2 多窗口调试

3.3 远程调试

3.4 性能调试

3.5 内存调试

3.6 网络调试

四、常见问题排查

4.1 DevTools 无法打开

4.2 断点不生效

4.3 控制台输出乱码

4.4 调试时应用卡死

五、调试工具推荐

5.1 VS Code 扩展

5.2 Chrome 扩展

5.3 命令行工具

六、调试最佳实践总结

✅ 推荐做法

❌ 避免的做法

七、参考资料

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐