环境搭建与第一个应用

本章目标

  • 搭建可用的 Electron 开发环境(macOS / Windows)。
  • 理解 main、preload、renderer 三层结构,而不是把所有代码写进一个文件。
  • 从零手写并运行一个最小应用,再用脚手架体验工程化项目。
  • 完成第一次打包,知道产物在哪里、为什么需要打包。

环境准备

Node.js 与包管理器

Electron 官方推荐使用 Node.js LTS。选择哪个 LTS 版本,取决于你使用的 Electron 版本内置的 Node 版本:

Electron内置 Node建议本地 Node
v45(当前文档基准)Node 22.xNode 22 LTS
v40 左右Node 20.xNode 20 / 22 LTS

本地 Node 主要用于运行构建脚本,应用运行时使用的是 Electron 内置的 Node。但原生模块编译时会受本地 Node 与 Electron ABI 差异影响,这部分在第 8 章展开。

1node -v
2npm -v
3# 或者使用 pnpm / yarn
4pnpm -v

平台构建工具链

平台需要安装用途
macOSXcode Command Line Tools编译原生依赖、签名
WindowsVisual Studio Build Tools(C++ 工作负载)编译原生依赖
Linuxbuild-essential、python3编译原生依赖

macOS 安装命令行工具:

1xcode-select --install

Windows 建议安装 Visual Studio Build Tools,并勾选「使用 C++ 的桌面开发」。即使暂时不写原生模块,很多 npm 包也依赖它。

网络与镜像

Electron 的二进制文件较大,国内网络常见问题是安装卡住或下载失败。可以配置镜像:

1# .npmrc
2electron_mirror=https://npmmirror.com/mirrors/electron/
3electron_builder_binaries_mirror=https://npmmirror.com/mirrors/electron-builder-binaries/

或者通过环境变量临时指定:

1ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ pnpm install

两条上手路径

路径 A:官方脚手架(推荐先体验)

Electron Forge 是官方维护的一体化工具,集开发、打包、分发于一体。

1npm init electron-app@latest my-app -- --template=vite-typescript
2cd my-app
3npm start

生成的目录结构大致如下:

1my-app/
2├── src/
3│   ├── main.ts        # 主进程入口
4│   ├── preload.ts     # 预加载脚本
5│   └── renderer.ts    # 渲染进程入口
6├── index.html
7├── forge.config.ts    # Forge 配置:打包、maker、插件
8├── vite.main.config.ts
9├── vite.preload.config.ts
10├── vite.renderer.config.ts
11└── package.json

Forge + Vite 的优点是:主进程、preload、渲染进程分别构建,开发时渲染层有 HMR,打包配置开箱即用。缺点是配置层级较多,初学时不便于理解「到底发生了什么」。

路径 B:手写最小工程(推荐理解原理)

先不用脚手架,手写一个只有四个文件的应用。

1mini-electron/
2├── package.json
3├── tsconfig.json
4├── src/
5│   ├── main.ts
6│   └── preload.ts
7└── renderer/
8    ├── index.html
9    └── renderer.js

1. 初始化

1mkdir mini-electron && cd mini-electron
2npm init -y
3npm install --save-dev electron typescript

2.package.json

1{
2  "name": "mini-electron",
3  "version": "1.0.0",
4  "private": true,
5  "main": "dist/main.js",
6  "scripts": {
7    "build": "tsc",
8    "start": "npm run build && electron ."
9  },
10  "devDependencies": {
11    "electron": "^45.0.0",
12    "typescript": "^5.9.0"
13  }
14}

关键字段只有一个:main。Electron 启动时读取它,作为主进程入口。

3.tsconfig.json

1{
2  "compilerOptions": {
3    "target": "ES2022",
4    "module": "CommonJS",
5    "moduleResolution": "Node",
6    "outDir": "dist",
7    "rootDir": "src",
8    "strict": true,
9    "esModuleInterop": true,
10    "skipLibCheck": true,
11    "sourceMap": true
12  },
13  "include": ["src/**/*.ts"]
14}

这里刻意使用 CommonJS。预加载脚本在沙箱模式下对 ESM 支持有限,先用 CJS 减少变量。

4. 主进程src/main.ts

1import { app, BrowserWindow, ipcMain } from 'electron';
2import path from 'node:path';
3
4function createWindow(): void {
5  const win = new BrowserWindow({
6    width: 1200,
7    height: 800,
8    show: false,
9    backgroundColor: '#ffffff',
10    webPreferences: {
11      preload: path.join(__dirname, 'preload.js'),
12      contextIsolation: true,
13      sandbox: true,
14      nodeIntegration: false,
15    },
16  });
17
18  // 等首帧准备好再显示,避免白屏闪烁
19  win.once('ready-to-show', () => {
20    win.show();
21  });
22
23  win.loadFile(path.join(__dirname, '../renderer/index.html'));
24}
25
26app.whenReady().then(() => {
27  ipcMain.handle('app:ping', () => 'pong');
28
29  createWindow();
30
31  app.on('activate', () => {
32    if (BrowserWindow.getAllWindows().length === 0) {
33      createWindow();
34    }
35  });
36});
37
38app.on('window-all-closed', () => {
39  if (process.platform !== 'darwin') {
40    app.quit();
41  }
42});

这段代码包含三个必须理解的点:

  1. app.whenReady() 之前不能创建窗口,Chromium 还没初始化完成。
  2. macOS 上关闭所有窗口通常不退出应用,activate 时重新创建窗口;Windows/Linux 则直接退出。
  3. webPreferences 的安全三件套:contextIsolation: true、sandbox: true、nodeIntegration: false。

5. 预加载脚本src/preload.ts

1import { contextBridge, ipcRenderer } from 'electron';
2
3contextBridge.exposeInMainWorld('electronAPI', {
4  getVersions: () => ({
5    node: process.versions.node,
6    chrome: process.versions.chrome,
7    electron: process.versions.electron,
8  }),
9  ping: (): Promise<string> => ipcRenderer.invoke('app:ping'),
10});

预加载脚本运行在渲染进程的隔离上下文中,是唯一推荐的桥接位置。它既能访问一部分 Electron API,又能把受控能力暴露给页面。

6. 渲染层renderer/index.html

1<!doctype html>
2<html lang="zh-CN">
3  <head>
4    <meta charset="UTF-8" />
5    <meta
6      http-equiv="Content-Security-Policy"
7      content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'"
8    />
9    <title>Mini Electron</title>
10  </head>
11  <body>
12    <h1>Hello Electron</h1>
13    <p id="versions">加载中...</p>
14    <button id="ping">Ping 主进程</button>
15    <p id="result"></p>
16    <script src="./renderer.js"></script>
17  </body>
18</html>

7. 渲染层脚本renderer/renderer.js

1const versions = window.electronAPI.getVersions();
2document.getElementById('versions').textContent =
3  `Electron ${versions.electron} / Chromium ${versions.chrome} / Node ${versions.node}`;
4
5document.getElementById('ping').addEventListener('click', async () => {
6  const result = await window.electronAPI.ping();
7  document.getElementById('result').textContent = `主进程返回:${result}`;
8});

8. 运行

1npm start

你会看到一个窗口,显示版本号,点击按钮会通过 IPC 从主进程拿到 pong。

三层结构为什么要分开

  • 主进程:唯一能创建窗口、访问完整 Node.js 与系统 API 的进程。
  • 预加载脚本:在页面加载前执行,向页面暴露少量受控 API。
  • 渲染进程:普通的 Web 页面,默认被沙箱限制。

把三层混在一起(例如开启 nodeIntegration 后在页面里直接 require('fs'))开发最快,但会让任何 XSS 都升级为任意文件读写,属于事故级设计。后续第 5 章会讲完整的安全加固。

应用生命周期

事件触发时机常见用途
will-finish-launching应用开始初始化注册协议、早期初始化
ready / whenReady()Chromium 初始化完成创建窗口、注册 IPC
activatemacOS 点击 Dock 图标重建窗口
window-all-closed所有窗口关闭决定是否退出
before-quit开始退出保存状态、清理资源
will-quit即将退出注销全局快捷键
quit进程退出最后清理

开发调试

主进程调试

1# 方式一:直接向 Electron 传 Node 调试参数
2npx electron --inspect=9229 .
3
4# 方式二:在 package.json 脚本中固定
5"dev:debug": "electron --inspect=9229 ."

然后在 VS Code 中附加到 9229 端口,或在 Chrome 打开 chrome://inspect。

渲染进程调试

开发时通过代码打开 DevTools:

1win.webContents.openDevTools({ mode: 'detach' });

生产环境不要默认打开。更常见的做法是注册一个快捷键或隐藏入口,便于线上排障。

远程调试端口

1npx electron --remote-debugging-port=9222 .

随后可以在 Chrome 的 chrome://inspect 中调试渲染进程,这对排查用户环境问题非常有用,但生产环境应通过 Fuses 关闭(见第 5 章)。

第一次打包

手写工程可以直接安装 electron-builder 体验:

1npm install --save-dev electron-builder

在 package.json 中补充:

1{
2  "scripts": {
3    "dist": "npm run build && electron-builder"
4  },
5  "build": {
6    "appId": "com.example.mini",
7    "productName": "Mini Electron",
8    "files": ["dist/**/*", "renderer/**/*", "package.json"],
9    "directories": {
10      "output": "release"
11    },
12    "mac": { "target": ["dmg"] },
13    "win": { "target": ["nsis"] }
14  }
15}
1npm run dist

产物位于 release/。打包细节(asar、签名、体积优化、增量更新)在第 7 章。

常见问题

安装 Electron 很慢或失败

优先检查镜像配置与代理;删除 node_modules 后重装。公司网络环境下,ELECTRON_MIRROR 与 ELECTRON_BUILDER_BINARIES_MIRROR 都要配置。

require is not defined

渲染进程默认没有 Node 环境。不要通过打开 nodeIntegration 解决,应该把能力放进 preload,通过 contextBridge 暴露。

window.electronAPI is undefined

通常有三个原因:

  1. preload 路径不对。打包后路径会变化,建议用 path.join(__dirname, 'preload.js')。
  2. preload 编译失败,dist/preload.js 不存在。
  3. 页面在 preload 执行完成前访问了 API,检查脚本加载顺序。

macOS 提示「无法验证开发者」

本地开发产物未签名会触发 Gatekeeper。开发阶段可在「系统设置 → 隐私与安全性」中允许;正式分发必须签名与公证,见第 7 章。

窗口打开后白屏

先看 DevTools Console 与 Network。常见原因是 loadFile 路径错误、CSP 阻止脚本、渲染入口构建失败。第 13 章有系统化的白屏排查路径。

本章小结

  • Electron 应用由主进程、预加载脚本、渲染进程三层组成,职责边界决定了安全性与可维护性。
  • app.whenReady() 之后才能创建窗口;跨平台退出行为要分别处理。
  • 安全默认值应该是 contextIsolation: true、sandbox: true、nodeIntegration: false。
  • 预加载脚本通过 contextBridge 暴露白名单能力,是主进程与页面之间唯一的推荐桥梁。
  • 先用手写工程理解原理,再用 Forge/Vite 提升工程效率。

参考资料