2. 开发环境准备

本节目标

• 安装并验证 Node.js 与 npm 的版本，满足 Electron 脚手架要求。
• 了解 Windows、macOS、Linux 三端的系统要求与差异。
• 选择一款顺手的代码编辑器（推荐 VS Code）。
• 学会查看当前 Electron 的版本号。
• 理清 npm 初始化项目与安装 Electron 的基本思路。

动手之前，先把工具链装好。Electron 项目本质上是一个 Node.js 项目，所以环境准备和前端开发几乎一样。本章带你装 Node.js、确认系统要求、挑一款编辑器，并学会查看 Electron 版本。

2-1 先装 Node.js 和 npm

Node.js 是 Electron 脚手架的运行基础，npm 是它的包管理器，装 Node.js 时会自动带上。请到 Node.js 官网下载对应平台的安装包，推荐使用最新的 LTS 长期支持版。

装好以后，在终端敲下面两条命令确认版本：

node -v
npm -v

如果顺利打印出类似 v24.x.x 和 11.x.x 的版本号，说明环境就绪。Node.js 版本过低会导致脚手架工具报错，升级到 LTS 即可。Electron v43 内嵌的是 Node.js 24，系统装一份较新的 LTS 即可满足工具链要求。

2-2 一个容易误会的地方

你本地装的 Node.js，只用来跑 npm、运行打包脚本这类开发工具。Electron 应用真正运行时，用的是它自己内嵌的 Node.js 运行时，跟系统装的那份无关。

// 在应用里查看 Electron 内嵌的 Node 版本
const { versions } = require('node:process')
console.log('内嵌 Node 版本：', versions.node)
console.log('Chromium 版本：', versions.chrome)

所以最终用户拿到安装包后，不需要自己装 Node.js 也能运行你的程序。这也是 Electron 分发简单的原因之一。

2-3 系统要求对照

Electron 支持三大桌面系统，但具体工具链略有差异。下面这张表覆盖主流情况。

系统	位数	备注
Windows	64 位	10 及以上，避免使用 WSL 跑应用
macOS	64 位	建议用 Homebrew 或 nvm 装 Node
Linux	64 位	需基础编译依赖，如 build-essential

提示：在 Windows 上跟着教程走时，请直接用命令提示符或 PowerShell，不要用 WSL（Windows 子系统）。在 WSL 里 Electron 常常无法启动图形界面，会白忙一场。

macOS 用户建议用 Homebrew 或 nvm 管理 Node.js，能避开系统目录的权限问题。Linux 用户若遇到编译报错，先装好 gcc、make、python 这几样基础工具。

2-4 选一款顺手的编辑器

写代码需要文本编辑器。官方推荐 Visual Studio Code，它对 JavaScript、调试、终端集成都做得很好，而且它本身就是 Electron 写的。

你当然可以用任何编辑器。只要能编辑文本、带个集成终端，体验差别不大。VS Code 的额外好处是能直接调试主进程和渲染进程，后续章节会用到。

2-5 查看 Electron 本身的版本

当你在项目中装好 Electron 后，可以用命令查看它的版本：

npx electron --version

这条命令会打印出当前项目依赖里的 Electron 版本。如果你还没装依赖，它会临时下载运行，速度较慢，建议先完成项目初始化。

也可以在代码里读取版本号，适合在关于面板展示。渲染进程碰不到 process，得由 preload 读好再递出去：

// preload.js —— 预加载脚本：把版本号暴露给页面
const { contextBridge } = require('electron')

contextBridge.exposeInMainWorld('appInfo', {
  electron: process.versions.electron
})

// renderer.js —— 渲染进程：读取 preload 暴露的值
console.log('当前 Electron 版本：', window.appInfo.electron)

这套”preload 取值、页面读值”的写法贯穿全书，第 9 章会把它讲透。

2-6 项目初始化思路

Electron 项目以 package.json 为起点。标准流程分三步：先建文件夹并用 npm 初始化，再把 Electron 装进开发依赖，最后补上入口文件和启动脚本。

# 1. 新建并进入项目目录
mkdir my-electron-app && cd my-electron-app

# 2. 初始化 package.json（按提示填写，入口设为 main.js）
npm init

# 3. 把 Electron 装进 devDependencies
npm install electron --save-dev

为什么 Electron 是开发依赖而不是生产依赖？因为它的 JavaScript 接口最终会绑定到一个二进制文件，而打包步骤会把这个二进制一起打进安装包。运行时不靠 npm 去拉取它，所以放在 devDependencies 即可。

提示：用 yarn 或 pnpm 的读者，安装策略要额外调一下，否则打包工具链可能找不到依赖，具体设置见本章 2-11。

2-7 推荐的一键起步方式

如果你想跳过手工初始化，官方主推 Electron Forge 的脚手架命令：

npm create electron-app@latest my-app

这条命令会生成一个带完整配置的可运行项目，省去手写 package.json 和打包配置。它和本章手工流程本质一致，只是帮你把样板代码写好。后续打包章节会进一步展开 Forge。

2-8 验证 Electron 已正确安装

装完依赖后，确认 Electron 二进制在本地可用，能避免后续启动时报”找不到模块”。最简单的检查是看 node_modules 里是否真有 electron 目录，以及 package-lock.json 是否记录了锁定版本：

# 确认依赖已落地
ls node_modules/electron > /dev/null && echo "electron 已安装"
npm ls electron

npm ls electron 会打印项目里 Electron 的实际安装版本，排查”别人能跑我不能跑”时很有用。若提示命令报错，多半是 npm install 中途失败，重新跑一次安装即可。

2-9 学习前提与建议路径

Electron 架在网页技术和 Node.js 之上，所以上手前最好有些前端基础：能写 HTML、CSS，懂一点 JavaScript。不需要精通，能看懂基本语法就够。

Node.js 方面，知道 require、模块、文件系统这些概念会有帮助，但主进程相关 API 我们会在用到的地方逐一讲解，不必提前深究。跟着章节顺序走，从环境到窗口、再到通信与打包，是最顺的路径。

2-10 常见环境问题排查

环境出问题时，按固定顺序查能省很多时间。先看 Node 版本，过低会直接导致脚手架报错，升级到 LTS 通常就好。

再看网络。Electron 的二进制需要从镜像下载，公司内网或国内网络偶尔会卡住。这时可配置 ELECTRON_MIRROR 环境变量指向国内镜像，再重装依赖。

最后看权限。macOS 或 Linux 上用系统目录装全局包常报权限错，推荐用 nvm 或加 --prefix 到用户目录，避免反复 sudo。Windows 上则尽量用官方安装包，少用包管理器以免路径错乱。

2-11 关于包管理器的选择

npm 不是唯一选择，yarn 和 pnpm 也很流行。它们的命令略有不同，但初始化和装包思路一致。需要注意一点：Electron 的打包工具链依赖真实的 node_modules 目录。

因此若你用 yarn berry 或 pnpm，要把安装策略调成标准 node_modules 方式。yarn 设 nodeLinker: node-modules，pnpm 设 nodeLinker: hoisted，否则打包时可能找不到 Electron 二进制。

新手建议先用 npm，少踩配置坑。等熟悉了整个流程，再按团队习惯迁移到其他包管理器也不迟。工具是手段，先把应用跑起来更重要。

2-12 本章小结

环境准备就三件事：装好 Node.js LTS、选好编辑器、用 npm 初始化项目并安装 Electron。记住系统 Node 只服务于开发，运行时靠 Electron 内嵌的那份。

下一章我们就真正写出第一个能跑起来的窗口应用。