Electron 入门指南：基于 Chromium 与 Node.js 的跨平台桌面应用开发

Electron 是一个用 JavaScript、HTML 与 CSS 构建跨平台桌面应用的框架：它把 Chromium 和 Node.js 一起嵌入可执行程序，让开发者用同一份 JS 代码库同时交付 Windows、macOS、Linux 三个平台的应用，全程无需编写原生代码。这篇导读承接本仓库 docs/tutorial/introduction.md 的内容，帮助你理解 Electron 的核心定位、官方文档体系，并掌握从零起步的推荐学习路径与快速验证工具（Electron Fiddle），读完即可上手"第一个 Electron 应用"的最小骨架。

什么是 Electron？

Electron 是一个用于桌面应用开发的框架。它的核心设计是将 Chromium（负责渲染 Web 内容）与 Node.js（负责提供系统级能力）一并嵌入到同一个二进制产物中，再以进程模型把它们组织起来。带来的直接结果是：

• 你只需维护一份 JavaScript 代码库，即可运行于 Windows、macOS、Linux；
• UI 完全用 Web 技术（HTML/CSS/JS）编写，前端工程师无需学习 Qt、Swift 或 Win32 等原生 GUI 技术栈；
• 代码运行在带 Node.js 能力的环境中，因此可以直接使用文件系统、网络、子进程等 Node API。

从本仓库的结构可以直观印证这一设计：shell/ 目录存放了基于 Chromium 的 C++ 层实现，default_app/ 则是安装后双击启动的默认应用；本仓库根目录的 package.json 中把项目自身描述为 "Build cross platform desktop apps with JavaScript, HTML, and CSS"，与官方定位一致。

值得注意的是，虽然开发时需要本地安装 Node.js 来执行脚手架命令，但 Electron 运行应用用的是自身内置的 Node.js 运行时，而不是你系统的 Node.js。因此最终用户无需预先安装 Node.js 就能运行你的应用。这一点在入门教程的前提准备章节 docs/tutorial/tutorial-1-prerequisites.md 中有明确提醒。

两个核心进程：主进程与渲染进程

要真正理解 Electron 的"能做什么"，需要先建立最基本的进程模型认知（详细展开见 docs/tutorial/process-model.md）：

• 主进程（Main Process）：每个 Electron 应用有且只有一个主进程，它是应用的入口，运行在 Node.js 环境中，负责创建窗口（BrowserWindow）、控制应用生命周期，并调用菜单、对话框、托盘等原生 API。
• 渲染进程（Renderer Process）：每个 BrowserWindow 会开启一个独立的渲染进程来加载网页，行为遵循 Web 标准；出于安全考虑，默认情况下它无法直接 require Node.js 模块。

主进程与渲染进程之间并没有直接的全局互通通道，这正是引入 preload 脚本的原因——preload 脚本在渲染进程加载网页内容之前执行，既能访问 Node.js API，又能借助 contextBridge 安全地向页面暴露受限 API，从而支撑后续的 IPC 通信。

以仓库内置的快速上手示例 docs/fiddles/quick-start/main.js 为例，可以看到典型的主进程代码结构：

const { app, BrowserWindow } = require('electron/main')
const path = require('node:path')

function createWindow () {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js')
    }
  })

  win.loadFile('index.html')
}

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

  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) {
      createWindow()
    }
  })
})

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit()
  }
})

注意这里用 require('electron/main') 显式从主进程子路径导入模块——这是当前 Electron 推荐的进程化导入方式。与之对应，渲染进程侧可通过 preload 脚本在 DOM 就绪后读取运行环境版本信息，例如 docs/fiddles/quick-start/preload.js：

window.addEventListener('DOMContentLoaded', () => {
  const replaceText = (selector, text) => {
    const element = document.getElementById(selector)
    if (element) element.innerText = text
  }

  for (const type of ['chrome', 'node', 'electron']) {
    replaceText(`${type}-version`, process.versions[type])
  }
})

而 docs/fiddles/quick-start/index.html 中则预留了 #node-version、#chrome-version、#electron-version 三个占位元素，用来向用户展示当前运行环境所捆绑的 Node.js、Chromium 与 Electron 版本——这正是"Electron 自带运行时"的最直观证明。

运行机制的另一面：默认应用入口

如果你直接运行 electron（不带任何参数），它会落到仓库 default_app/ 所实现的默认应用逻辑上。从 default_app/main.ts 的源码可以看出，CLI 支持传入 index.js 文件、含 package.json 的目录、.html/.htm 文件或 http(s):// URL，也支持 --version、--interactive（打开主进程 REPL）等参数。这说明 Electron 本身就具备"开箱即用"的演示能力，新手甚至可以先不加任何代码体验框架。

起步建议：先看官方入门教程

Electron 官方推荐的学习路径非常明确，按顺序展开为一条完整的六步路线，全部文档都收录在本仓库 docs/tutorial 目录下：

1. 前置准备（Prerequisites）：搭建开发环境，安装 Node.js LTS、代码编辑器与 Git；
2. 构建第一个应用：从零拼接一个最小 Electron 应用；
3. 使用 Preload 脚本：理解 preload 与上下文隔离；
4. 添加功能：通知、托盘、快捷键、离线检测等常用能力；
5. 打包应用：使用 Electron Forge 产出可分发的安装包；
6. 发布与更新：利用 GitHub Releases 实现自动更新。

如果希望"一条命令"直接获得可用脚手架，官方推荐用 Electron Forge 的 create-electron-app 命令生成工程模板，具体对比与选型可以参考 Boilerplates and CLIs 一节。

除了顺序学习之外，Examples（示例目录） 与 API 文档 也是两个很适合随手翻阅的入口。Examples 目录（入口见 docs/tutorial/examples.md）收集了消息端口、设备访问、全局快捷键、多线程、离屏渲染、拼写检查、Web 嵌入等一系列常见特性的最小自包含示例；API 文档（如 app 模块、BrowserWindow）则以模块为单位给出方法、事件、属性的权威说明。浏览 docs/README.md 可以快速纵览整个文档体系的分类。

用 Electron Fiddle 即时运行官方示例

官方强烈建议把 Electron Fiddle 当作学习与原型验证工具安装。它是一个由 Electron 团队维护、用 Electron 自身编写的"沙盒应用"，适合用来实验各类 API 或快速搭建原型。

Fiddle 与本仓库文档的集成方式是：当你在文档（例如本仓库的 Examples 与各教程）中浏览代码块时，常常能看到代码块上方的 "Open in Fiddle" 按钮。只要本机安装了 Fiddle，点击按钮就会打开一个 fiddle.electronjs.org 链接，把示例自动载入 Fiddle 运行——无需手动复制粘贴，即可看到真实的窗口行为。

对应的 fiddle 目录在仓库内是真实存在且可运行的最小项目。以 docs/fiddles/quick-start 为例，它包含三个文件：

• main.js：主进程入口，创建 800×600 的 BrowserWindow，配置 preload 并加载 index.html，同时处理了 macOS 下的 activate 事件与跨平台的 window-all-closed 退出逻辑；
• preload.js：在页面加载前把 Node/Chromium/Electron 版本写入对应 DOM 节点；
• index.html：声明了严格的内容安全策略（CSP），并展示 "Hello World!" 与三项运行时版本信息。

这套组合与入门教程第 2 步 构建第一个应用 中搭建的最小应用结构完全一致，可以作为手写首个应用的对照蓝本。

官方文档目录里都有什么？

Electron 的所有官方文档都聚合在 docs/ 目录下并可按分类浏览。各分类定位如下：

• Tutorial（教程）：从创建到发布第一个 Electron 应用的端到端指南，即本仓库 docs/tutorial 目录；本导读文档即属于该分类。
• Processes in Electron（进程）：深入讲解 Electron 进程模型与各进程的协作方式，见 docs/tutorial/process-model.md 等文档。
• Best Practices（最佳实践）：开发 Electron 应用时应牢记的重要清单（安全性、性能等）。
• Examples（示例）：为应用添加特性的速查集合，以 fiddle 形式内嵌于文档。
• Development（开发指南）：各类零散的开发指引，汇总入口见 docs/development/README.md。
• Distribution（分发）：学习如何把应用分发给最终用户。
• Testing And Debugging（测试与调试）：如何调试 JavaScript、编写测试以及相关工具链。
• References（参考资料）：帮助你理解 Electron 项目如何组织与运作的有用链接。
• Contributing（贡献）：编译 Electron、参与贡献的说明。

此外，官方 README（docs 根目录 docs/README.md）还提醒用户：务必使用与当前 Electron 版本匹配的文档。页面 URL 中应包含版本号；如果你看到的是开发分支（main）的文档，其中可能含有与当前稳定版本不兼容的 API 变更。如需查看旧版本文档，可在版本分支/标签列表中切换。

从工程角度，这套文档并不是静态孤岛，而是与代码强绑定、可被自动校验的资产。仓库根目录 package.json 的 lint:docs 脚本串联了多项检查（如 lint-roller-markdown-links 校验文档相对链接、markdownlint 格式检查、markdown 内嵌代码的 lint 与 TS 检查），并且 docs/fiddles/**/*.js 会走 standard 规范检查。这意味着你在文档里看到的每个 fiddle 示例都实际通过 lint，相对路径链接也是被自动验证过的——这为读者"照着文档抄代码"提供了额外的可信度。

遇到问题去哪里求助？

如果开发过程中卡住，官方给出了两个首选求助渠道：

• 功能与用法问题：社区 Discord 服务器聚集了大量 Electron 应用开发者，适合寻求写法建议与经验交流；
• 疑似框架 Bug：先在官方 GitHub 的 issue 跟踪器中检索是否已有匹配的既有 issue；若无，则按官方 bug report 模板提交新 issue。

在等待社区回复之前，也可以先翻阅仓库中的 FAQ、Glossary（术语表） 与 为什么选择 Electron 等参考资料，很多困惑往往在阅读术语与设计动机后便能自行消解。

小结

Electron 的价值在于用 Web 技术栈换取跨平台桌面交付效率：Chromium 负责渲染、Node.js 负责系统能力、主进程与渲染进程的分工负责应用架构与安全边界。无论你是首次接触，还是想系统梳理，官方推荐的路径都是"导读 → 六步入门教程 → Fiddle 实践 → Examples 与 API 按需查阅"。

行动清单如下：

1. 阅读入门教程第 1 步：前置准备，安装 Node.js LTS 与代码编辑器；
2. 安装 Electron Fiddle，体验文档内嵌的 "Open in Fiddle" 快速运行；
3. 对照 docs/fiddles/quick-start 的三文件结构，用第 2 步教程亲手搭建第一个 Hello World 窗口；
4. 需要具体能力时，从 Examples 总览 或 API 文档 检索，并始终确认所用文档版本与你的 Electron 版本一致。