Electron 入门教程（一）：前置准备——从工具链安装到运行时原理的完整起步指南

本指南对应 Electron 官方入门教程的 Part 1（Prerequisites，前置准备），是后续「构建首个应用 → Preload 脚本 → 功能扩展 → 打包分发 → 发布更新」六步学习路线的第一步。读完本文，你将完成一套可用于 Electron 桌面应用开发的完整环境（编辑器、终端、Git/GitHub、Node.js 与 npm），并通过命令校验工具链是否就绪；同时会澄清一个最关键的概念——Electron 应用运行时究竟依赖什么，为后续编写与运行首个应用打下正确认知。

教程系列概览：这一步在整个学习路径中的位置

本指南属于 Electron 入门教程的组成部分。整条教程循序渐进，先手工搭建一个最小的 Electron 应用，再逐步为其加入真实桌面应用所需的能力：

1. 前置准备（本文）——安装并验证开发所需的全部工具；
2. 构建你的第一个应用——创建 npm 项目、编写主进程入口并打开一个加载本地 HTML 的原生窗口；
3. 使用 Preload 脚本——让渲染进程在受控的前提下访问受限 API；
4. 添加功能——为应用补充菜单、快捷键、系统通知等桌面能力；
5. 打包你的应用——使用 Electron Forge 产出可分发的安装包；
6. 发布与更新——借助 GitHub Releases 为应用配置自动更新。

读者若希望跳过手工搭建、以单条命令直接获得可运行模板，官方推荐使用 Electron Forge 的 create-electron-app 脚手架命令；该部分同样会在后续打包章节展开。本文作为整个系列的入口，核心价值在于把「能写代码」之前的最后一公里铺平。

Electron 是什么，为什么值得先理解它

Electron 是一个使用 JavaScript、HTML 和 CSS 构建桌面应用的框架。它的实现方式是：把 Chromium（负责渲染 Web 内容）与 Node.js（负责提供后端运行时能力）一起嵌入到单个二进制文件中，从而让你使用一份 JS 代码库，同时构建出可在 Windows、macOS 和 Linux 上运行的跨平台桌面应用。

理解这句话对后续开发至关重要：

• 你的界面代码就是普通的 Web 技术（HTML/CSS/JS），运行在 Chromium 渲染引擎上；
• 你的能力边界由 Electron 桥接的 Node.js 与操作系统原生 API 决定；
• 因为运行时被完整地打进一个二进制，最终用户拿到的是一个自包含的应用，无需在自己的机器上安装 Node.js 或浏览器。

这一「双运行时合一」的架构，正是 进程模型 文档所描述的"主进程 + 渲染进程"多进程模型的根基，也是整条教程后续所有代码之所以成立的前提。

前置知识假设：你需要具备什么基础

Electron 本质上是给 Web 应用套一层原生外壳，并且运行在 Node.js 环境中，因此本教程默认读者已经具备以下基础：

• Node.js 基本知识：会使用 npm、理解 package.json、node_modules、CommonJS/ESM 模块等概念；
• 前端 Web 开发基础：熟悉 HTML、CSS 与 JavaScript 的基础语法和页面结构。

如果你需要补充背景知识，官方建议先系统学习 Web 入门教程（例如 MDN Web Docs 的《Getting started with the Web》）与 Node.js 官方入门文档（例如《Introduction to Node.js》）。这两类基础不需要精通，但至少要能读懂它们，否则在进入主进程、渲染进程与 API 绑定等主题时会产生认知断层。

从仓库中也可以看到这种「Node + Web」双栈假设是贯穿始终的：主进程代码运行在 Node 环境（default_app/main.ts 直接使用 process、node:fs、node:module 等标准库），而窗口内容则是加载本地 HTML（loadFile('index.html')），两者在同一个应用内协同工作。

必要工具清单：逐一安装并确认

官方将起步所需工具归纳为五类，下面逐一说明用途、安装要点与验证方式。

代码编辑器

你需要一个文本编辑器来编写代码。官方推荐 Visual Studio Code，也可以使用任何你习惯的编辑器。关键考量是后续的调试环节（附加调试器、设置断点、查看变量）会大量依赖编辑器的集成能力，选择支持良好调试协议的工具能显著降低学习成本。

命令行终端

教程中大量操作通过命令行接口（CLI）完成，请使用你所在平台的默认终端：

• Windows：Command Prompt 或 PowerShell；
• macOS：Terminal；
• Linux：随发行版而异（如 GNOME Terminal、Konsole）。

多数现代代码编辑器都内置了集成终端，同样可以直接使用。后续创建项目、安装依赖、以开发模式启动 Electron 应用等操作都会在这样的终端中执行。

Git 与 GitHub

Git 是当前最通用的源代码版本控制系统，GitHub 是基于它构建的协作开发平台。严格来说，构建一个 Electron 应用两者都不是必需的——本教程之所以要求它们，是因为发布与更新章节会使用 GitHub Releases 来配置应用的自动更新。因此官方要求你提前完成两件事：

1. 创建一个 GitHub 账号；
2. 安装 Git，并熟悉最基本的提交（commit）、推送（push）操作。

如果你不熟悉 Git 的工作方式，官方建议先阅读 GitHub 官方的 Git 入门指南。偏好可视化操作的话，也可以使用 GitHub Desktop 桌面客户端——它会在未安装 Git 的机器上自动为你装好最新版 Git。

官方给出的工作建议是：在开始教程前，先在本地创建一个 Git 仓库并将其发布到 GitHub，每完成教程的一个步骤就提交一次代码。这种「小步提交」的习惯既能保留每个阶段的完整可回滚状态，也为第 6 步的版本发布准备了干净的版本历史。

Node.js 与 npm

开发 Electron 应用，需要在本机安装 Node.js 运行时以及它自带的 npm 包管理器。官方明确建议：

• 使用 最新的长期支持（LTS）版本——LTS 版本维护周期长、生态兼容性好，是桌面应用这类需要长期迭代的项目的稳妥选择；
• 使用平台提供的预编译安装包进行安装——自行从源码编译或其他非常规方式可能与各种开发工具产生不兼容问题；
• 在 macOS 上，官方额外建议通过包管理器（如 Homebrew 或 nvm）安装，以避免目录权限问题。

值得特别说明的是版本兼容的现实问题：Node 生态更新频繁，Electron 自身的工具链对 Node 版本有明确下限要求。以本仓库为例，仓库根目录的 npm/package.json 通过 "engines": { "node": ">= 22.12.0" } 声明了安装 Electron 预编译产物时对 Node 版本的最低要求。因此选择较新的 LTS 版本既能满足工具链约束，也能避免依赖旧版本遗留的权限与安全坑。

校验安装：node -v 与 npm -v

安装完成后，通过给 node 与 npm 命令加 -v 标志即可打印已安装版本，官方给出的示例输出如下：

$ node -v
v16.14.2
$ npm -v
8.7.0

实际输出会随你所装版本而变化——只要命令能正常打印出版本号，就说明 Node 与 npm 均已正确加入 PATH，可以进入下一步。若命令报「command not found」之类的错误，请先回到安装步骤排查环境变量配置。

最易混淆的关键认知：Electron 不用你的系统 Node.js 运行代码

本教程反复强调一个与直觉相反、却极其重要的原则：

虽然你在本地搭建项目时需要 Node.js，但 Electron 运行你的应用代码时并不会使用系统安装的 Node.js——它自带了一个捆绑进自身二进制的 Node.js 运行时。

这带来三个直接推论：

1. 构建期依赖 ≠ 运行时依赖：你电脑上的 Node 只是脚手架与开发工具，真正执行你主进程代码的是 Electron 内嵌的运行时；
2. 终端用户无需安装 Node.js：发布给用户的应用是自包含的，安装包已经把 Node.js 运行时一并带上了；
3. 同一个 process，版本与系统可能不同：在应用内部查询到的 Node 版本，取决于 Electron 二进制捆绑的运行时版本，而不取决于开发机上的 node 版本。

在应用内确认 Electron 内置的运行时版本

要查看你的应用实际运行在哪个 Node/Electron/Chromium 版本上，可以在主进程或 preload 脚本中访问全局的 process.versions 变量。该对象中的几个关键字段分别是：

• process.versions.electron：当前 Electron 版本号；
• process.versions.node：Electron 内置的 Node.js 运行时版本；
• process.versions.chrome：当前 Chromium 内核版本；
• process.versions.modules：Node ABI（模块接口）版本号，关系到原生模块能否复用。

关于 process.versions 的完整字段说明可参见 process API 文档。

来自源码与测试的印证

这条规则在本仓库中有大量可验证的落点：

• default_app/main.ts 中，Electron CLI 对 --version/-v 打印的是 'v' + process.versions.electron，对 --abi/-a 打印的是 process.versions.modules——也就是说版本查询走的是 Electron 内置运行时上报的数据，而非系统 Node；
• 同样的 startRepl() 启动 REPL 时，欢迎信息中的 "Using Node.js v… and Electron v…" 同样取自 process.versions；
• spec/node-spec.ts（第 174 行起）中有一条专门的测试用例：在 fork 出的子进程中读取 process.versions，并断言其 electron 字段是形如 ^\d+\.\d+\.\d+ 的版本字符串——从测试层面锁定了「process.versions.electron 恒为可用的语义化版本」这一契约。

正因如此，当你在开发中怀疑「某个 Node 特性为什么不可用」时，正确的排查方式是先检查 process.versions.node 对应的内置运行时版本，而不是开发机上的系统 Node 版本。

两个实用命令：快速查看当前 Electron 的版本信息

在没有创建任何项目时，也可以临时借助 npm 包运行器验证 Electron 二进制是否存在并读取其版本：

# 打印 Electron 内置运行时版本（等价于 default_app/main.ts 中 --version 分支的输出）
npx electron --version

# 打印 Node ABI 模块版本
npx electron --abi

注意这类临时调用只是校验性的：如 advanced installation 文档 所述，npx electron . 这类即席运行不会安装你应用自身的依赖，正式开发仍应在项目内执行 npm install 并按标准流程启动。若安装阶段遇到网络问题（错误码如 ELIFECYCLE、EAI_AGAIN、ECONNRESET、ETIMEDOUT 基本都是网络原因而非包本身的问题），可以参考该文档中关于镜像（ELECTRON_MIRROR）、代理与本地缓存（electron_config_cache）的配置方案处理；npm install 底层经由 @electron/get 从 GitHub Releases 下载预编译二进制（这一依赖关系可直接在 npm/package.json 的 dependencies 中看到）。

学习目标与下一步行动

完成本步所有准备工作后，你的学习路线将非常清晰：

1. 开发阶段：从零手工拼接一个最小 Electron 应用（Part 2）——该步骤会创建一个 npm 项目，将 Electron 安装为 devDependencies，把入口设为 main.js，并通过 npm run start（内部执行 electron .）以开发模式运行应用；
2. 能力补齐：学习用 Preload 脚本 桥接主进程与渲染进程，为应用 添加桌面功能；
3. 交付阶段：使用 Electron Forge 完成 打包 与 发布更新，将应用交付给最终用户。

关于 Electron 的版本号规则与如何锁定应用依赖的 Electron 版本，可进一步阅读 electron-versioning 文档。

小结

• Electron 用 JavaScript/HTML/CSS 构建桌面应用，将 Chromium 与 Node.js 内嵌进单一二进制，一份代码覆盖 Windows、macOS、Linux；
• 起步前请备齐四类工具：代码编辑器、系统终端、Git/GitHub（服务于后续自动更新）、Node.js 与 npm（务必使用 LTS 与官方安装包）；
• 用 node -v、npm -v 验证 Node 工具链就绪；
• 牢记最关键的运行时认知：应用运行用的是 Electron 内置 Node，而非系统 Node，终端用户无需安装 Node.js；在应用内用 process.versions 查询真实运行时版本（源码示例 与 测试用例 均可佐证）。

环境就绪后，即可进入下一节，从 mkdir my-electron-app && npm init 开始搭建属于你的第一个 Electron 应用。