企业官网建设流程全解析

• 知识管理
• 桌面应用

导读

Boostnote 是一款基于 Electron 构建的开源 Markdown 笔记应用，其界面渲染层运行在 Chromium 之上。本文以仓库内 docs/pt_BR/debug.md 官方调试文档为主体，结合仓库源码（package.json、lib/main-menu.js、browser/main/DevTools 等）展开，系统讲解两条主流的调试路径：一是直接使用 Chrome Developer Tools 在应用内排查运行时错误与设置断点；二是借助 VS Code 的 Debugger for Chrome 插件，对 Boostnote 的主进程（Main）与渲染进程（Renderer）分别下断点。读完本文，你将掌握 Boostnote 源码调试的完整工作流，并能将其迁移到任意 Electron 项目的调试实践中。

该文档另有 日文版、韩文版、俄文版、简体中文版、法文版 与 德文版 可对照阅读。

调试前先理解 Boostnote 的双进程模型

Boostnote 与所有 Electron 应用一样，运行时会拉起两类进程：

• 主进程（Main Process）：负责应用生命周期、原生菜单、窗口管理等系统级能力，对应仓库中的 lib/main-app.js、lib/main-window.js、lib/main-menu.js 等文件；
• 渲染进程（Renderer Process）：负责界面与业务逻辑，对应 browser/main/Main.js 及其下的大量 React 组件与 browser/main/store.js 状态管理代码。

从调试视角看，这意味着「渲染层报错」（如某个 React 组件抛异常）和「主进程报错」（如菜单点击无响应）分别发生在不同的执行环境中，本文后续两种调试方案都会围绕这两个进程展开。

使用 Chrome Developer Tools 调试

由于 Boostnote 基于 Chromium，其渲染进程完全可以使用与 Google Chrome 相同的 Developer Tools（开发者工具）进行调试。

开启与关闭 Developer Tools

在应用窗口内即可切换 Developer Tools 的开关，开启后的界面与 Chrome 浏览器中的开发者工具一致，包含 Elements、Console、Sources、Network 等面板。

除了交互式开关，仓库的菜单实现也提供了对应的内置入口。查看 lib/main-menu.js 的源码可以看到：

{ label: 'Toggle Developer Tools', accelerator: 'CommandOrControl+Alt+I', click() { BrowserWindow.getFocusedWindow().toggleDevTools() } }

也就是说，你可以通过以下任意一种方式开关 DevTools：

• 点击菜单栏View（视图）→ Toggle Developer Tools；
• 使用快捷键Ctrl+Alt+I（macOS 上为Cmd+Alt+I）。

菜单项背后调用的是 Electron 的BrowserWindow.getFocusedWindow().toggleDevTools()API，这是 Electron 提供的原生能力，与普通网页开发相比无需任何额外配置。

在 Console 面板查看运行时错误

当应用运行时发生异常（例如某个笔记渲染失败、某个回调函数抛错），错误信息会显示在 Developer Tools 的Console（控制台）面板中。你可以借此快速定位报错堆栈、定位到对应的源码文件，并配合 Sources 面板查看变量状态。

值得注意的是，为了便于调试，开发构建的 webpack 配置开启了源码映射（source map）。查看 webpack.config.js 可以看到devtool: 'cheap-module-eval-source-map'的配置，这意味着 Console 中的堆栈信息能够映射回原始的 ES6/JSX 源码，而不是压缩混淆后的产物，极大提升了定位效率。

使用 debugger 语句设置断点

在需要断点停顿的代码位置直接写入debugger语句，是调试中最直观的方式之一。例如在某个事件处理函数中加入：

function handleSave(note) { debugger // 代码执行到此处时，DevTools 会自动暂停 saveNote(note) }

当应用运行到该语句时，Developer Tools 会像浏览器调试一样自动进入暂停状态，此时可以在 Scope 面板中查看局部变量、在 Call Stack 面板中回溯调用链。上面的写法只是一个示意性示例，实际调试时完全可以根据自己的习惯，选择使用debugger语句、Sources 面板的断点行号、条件断点或者console.log日志输出等多种方式。

使用 Visual Studio Code 调试

对于习惯在 IDE 内完成「改代码 → 断点 → 复现 → 观察」闭环的开发者，官方文档提供了基于 VS Code 的调试方案，具体步骤如下。

第 1 步：安装 Debugger for Chrome 插件

在 Visual Studio Code 中安装Debugger for Chrome插件，安装完成后重启 VS Code 使插件生效。

第 2 步：启动 Boostnote 的构建任务

在 VS Code 中按下Shift+Command+B（Windows/Linux 上为Ctrl+Shift+B），或从顶部Terminal菜单选择Run Build Task，然后选择名为Build Boostnote的任务；也可以在终端中直接执行：

yarn run watch

该命令在 package.json 中定义为webpack-dev-server --hot，即启动带热更新（HMR）的 webpack dev server。查看 dev-scripts/dev.js 的源码可以看到完整的开发启动流程：

• 启动webpack-dev-server，监听localhost:8080端口；
• 等待首次打包成功后，通过spawn(electron, ['--hot', './index.js'])拉起 Electron 应用；
• 打包出错时会在终端打印编译错误并退出。

也就是说，yarn run watch或Build Boostnote任务会同时完成「编译前端资源」与「启动应用」两件事，是进行源码级调试的前提。只有构建任务处于运行状态，VS Code 才能将源码中的断点与运行中的进程对应起来。

第 3 步：打开 Debug 视图

当上述构建任务正常运行后，点击 VS Code 左侧Activity Bar（活动栏）中的Debug（调试）图标，或使用快捷键Shift+Command+D（Windows/Linux 上为Ctrl+Shift+D）打开调试视图。

第 4 步：选择 Boostnote All 配置并启动调试

在调试视图顶部的Debug configuration（调试配置）下拉框中，选择名为Boostnote All的配置，然后点击绿色箭头按钮或直接按下F5开始调试。

第 5 步：在 Main 与 Renderer 两个进程间切换断点

调试启动后，你应该能看到 Boostnote 正常运行。此时 VS Code 的调试器列表中会出现两个进程：

• Boostnote Main：对应 Electron 主进程；
• Boostnote Renderer：对应渲染进程。

现在你可以在 VS Code 的源码中任意设置调试断点。需要注意：如果某个断点显示为「未验证」（unverified，即灰色空心圆点），说明当前调试器连接的是错误的进程——此时需要切换到Boostnote Renderer与Boostnote Main中与断点所在文件相对应的那个进程。这是 Electron 双进程架构下最常见的调试陷阱。

调试参考要点

• 主进程相关代码（窗口、菜单、IPC 等）的断点应落在Boostnote Main上，可关注 lib/main-app.js、lib/main-menu.js；
• 渲染层代码（React 组件、编辑器、状态管理）的断点应落在Boostnote Renderer上，可关注 browser/main 目录；
• Electron 官方对应用调试有专门的教程（application-debugging），Debugger for Chrome 插件的使用方式可参考其官方文档，本文不再赘述。

开发模式下的额外调试利器

除了上述两种通用方案，Boostnote 仓库还在开发模式下内置了几项针对性调试工具，可大幅提升调试效率。

Redux DevTools（状态管理调试）

仓库在开发模式（NODE_ENV === 'development'）下会启用 redux-devtools。查看 browser/main/DevTools/index.dev.js 的源码：

const DevTools = createDevTools( <DockMonitor toggleVisibilityKey='ctrl-h' changePositionKey='ctrl-q' defaultIsVisible={false} > <LogMonitor theme='tomorrow' /> </DockMonitor> )

同时 browser/main/store.js 中仅在开发环境下通过DevTools.instrument()包装 createStore，而生产环境走 browser/main/DevTools/index.prod.js 的空实现（渲染为一个空<div />）。因此：

• 在开发模式下，可以通过Ctrl+H切换 Redux 调试面板的显示/隐藏，用Ctrl+Q调整面板停靠位置；
• 借助 LogMonitor 可以逐条回放每一个 Redux action 的派发与状态变更，对排查笔记数据流、存储切换等问题非常有帮助；
• 生产构建完全不会携带这部分调试逻辑，不会影响最终用户体验。

electron-debug 与 devtron

从 package.json 的 devDependencies 可以看到，仓库还依赖了electron-debug与devtron两个调试相关库：

• electron-debug用于在开发环境中自动开启一些调试便利功能（如快捷开关 DevTools）；
• devtron是 Electron 官方出品的 DevTools 扩展，提供对 IPC 通信、事件监听、进程信息等的可视化检查能力。

这些工具与上文两种调试方案配合使用，可以覆盖从「界面渲染」到「主进程通信」再到「状态管理」的完整调试链路。

调试要点速查

最后再强调两点：其一，无论是 DevTools 还是 VS Code 断点，本质都是依赖 Electron 基于 Chromium 的调试协议，掌握进程归属（Main 还是 Renderer）是成败关键；其二，本文所有命令与配置均以当前仓库（Boostnote 0.16.1，Electron 4）为准，若使用其他版本，请以对应版本的源码与文档为准。

• 知识管理
• 桌面应用