从零搭建最简 Electron 项目 - 人人都会AI编程

在了解了 Electron 的核心概念之后，最好的学习方式就是亲手搭建一个可以运行的最小化桌面应用。这个过程不需要任何构建工具或前端框架，只需要一个空目录、一个文本编辑器、一份 Node.js 环境，和大约 10 分钟的时间。最终你得到的会是一个带有系统窗口、标题栏、菜单关闭按钮的标准桌面程序。

2.1.1 准备工作：安装 Node.js

Electron 依赖 Node.js 运行时和 npm 包管理器。在开始之前，请确保你的开发机器上已经安装了 Node.js 16 或更高版本。可以在终端中运行以下命令来检查版本：

node -v
npm -v

如果尚未安装，建议从 nodejs.org 下载长期支持版（LTS）安装包，Windows/macOS/Linux 都有对应的图形化安装程序。安装成功后 npm 会自动就绪，不需要额外配置。

2.1.2 初始化项目并安装 Electron

新建一个空目录作为项目根文件夹，例如 my-first-electron-app，用终端进入该目录：

mkdir my-first-electron-app
cd my-first-electron-app

首先生成一个标准的 package.json 文件，这是 Node.js 项目的“身份证”，里面会记录项目名称、入口文件和依赖包等信息。使用 npm init 命令可以快速创建它：

npm init -y

-y 参数会跳过交互式提问，直接生成一份默认配置。如果你想自定义项目名、描述等字段，可以不使用 -y，按照提示手动填写。

接下来安装 Electron。这一步会将 Electron 的可执行文件与库作为项目的开发依赖下载到本地：

npm install --save-dev electron

--save-dev 表明 Electron 是开发阶段需要的工具，不会随应用最终打包给用户。下载过程可能需要几分钟，因为它会根据你的操作系统拉取对应的 Chromium 和 Node.js 二进制预编译包。如果下载速度较慢，可以设置国内的 Electron 镜像（例如使用 ELECTRON_MIRROR 环境变量指向淘宝镜像），但不设置也不影响最终结果。

2.1.3 编写最小应用代码

一个最简 Electron 应用只需要三个文件：主进程脚本、HTML 页面、以及一个可选的预加载脚本以保证安全性。我们先从基础版开始，只创建主进程和页面。

1. 创建主进程文件 main.js

在项目根目录下新建 main.js，粘贴以下代码：

const { app, BrowserWindow } = require('electron');
const path = require('path');

function createWindow() {
  const win = new BrowserWindow({
    width: 900,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,  // 启用上下文隔离，保证安全
      nodeIntegration: false,   // 禁止渲染进程直接使用 Node.js
    },
  });

  win.loadFile('index.html');
}

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

  // macOS 常见行为：点击程序坞图标时如果没有窗口则新建一个
  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) {
      createWindow();
    }
  });
});

// 所有窗口关闭时退出应用（macOS 除外，通常保留在后台）
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

这段代码做了几件关键的事：

从 Electron 导入 app（应用生命周期）和 BrowserWindow（窗口构造器）。
定义 createWindow 函数来创建一个 900×600 的普通窗口，并通过 webPreferences 设置了安全实践：启用上下文隔离，关闭 nodeIntegration，并指定了预加载脚本（稍后会创建）。
在 app.whenReady() 回调中创建窗口，并监听 activate 事件以处理 macOS 的典型行为。
监听 window-all-closed，在用户关闭全部窗口时退出应用（macOS 系统习惯保留程序运行，所以这里做了平台判断）。

2. 创建 HTML 页面 index.html

在项目根目录下新建 index.html：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>我的第一个 Electron 应用</title>
</head>
<body>
  <h1>🎉 Electron 跑起来了！</h1>
  <p>这是一个由 Chromium 渲染的桌面窗口。</p>
</body>
</html>

这个页面就是最终会在窗口中显示的内容，和传统的网页没有任何区别。

3. 创建预加载脚本 preload.js（安全必备）

即便在最简项目中，也强烈建议从一开始就加入预加载脚本，而不是直接开放 Node.js API 给渲染进程。新建 preload.js：

const { contextBridge } = require('electron');

// 通过 contextBridge 向渲染进程暴露安全的 API
contextBridge.exposeInMainWorld('myAPI', {
  // 后续可以在这里添加与主进程通信的方法
  versions: {
    node: process.versions.node,
    chrome: process.versions.chrome,
    electron: process.versions.electron,
  },
});

这里我们预先暴露了一个 versions 对象，用来在界面上展示运行时的版本信息。该对象会被安全地注入到渲染进程的 window.myAPI 上，而不会让渲染进程直接触及完整的 Node.js 环境。在 index.html 中，你可以添加如下脚本验证效果：

<script>
  const info = document.createElement('p');
  info.innerHTML = `Node.js ${myAPI.versions.node} / Chrome ${myAPI.versions.chrome} / Electron ${myAPI.versions.electron}`;
  document.body.appendChild(info);
</script>

2.1.4 配置启动脚本并运行

为了让 npm start 命令能够启动 Electron，需要修改 package.json 文件。打开 package.json，确认或添加以下字段：

{
  "name": "my-first-electron-app",
  "version": "1.0.0",
  "main": "main.js",
  "scripts": {
    "start": "electron ."
  },
  "devDependencies": {
    "electron": "^28.0.0"
  }
}

"main": "main.js" 告诉 Electron 主进程的入口文件是哪个。
"scripts" 中的 "start": "electron ." 让我们可以通过 npm start 一键启动应用。

此时整个项目的文件结构如下：

my-first-electron-app/
├── main.js
├── index.html
├── preload.js
└── package.json

在终端中执行启动命令：

npm start

如果一切正常，桌面上就会弹出一个独立的窗口，显示标题栏、内容页和你在 HTML 中写入的文字，底部还会展示 Node.js、Chrome 和 Electron 的版本号。这个窗口拥有可以拖动的大小调节手柄、最小化/最大化/关闭按钮，在任务栏（Windows）或程序坞（macOS）上也会出现对应图标。

2.1.5 真实开发中的附加提醒

上述过程就是一个 Electron 项目的最小完整骨架。在此基础上，你可以不断扩展功能：在 main.js 中添加菜单、系统托盘、快捷键；在 index.html 中引入 CSS 框架或 React 组件；在 preload.js 中暴露更多由主进程 IPC 桥接的安全 API。

还需要注意的一点是，默认的 Electron 窗口图标是框架自带的，更换图标需要在打包分发阶段配置（例如在 Windows 上设置 .ico 文件，在 macOS 上设置 .icns 文件），单纯运行阶段不需要图标调整。

如果你在安装 Electron 时遇到网络问题导致二进制包下载失败，可以尝试设置环境变量：

# 使用国内淘宝镜像（仅本次安装有效）
ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/" npm install --save-dev electron

现在，你已经拥有了一个完全属于你自己的桌面程序——尽管它还很简陋，但它的确是一个独立于浏览器的原生级窗口应用。接下来，我们将深入 Electron 的进程模型和主进程 API，逐步为这个空白的画布添加真正实用的桌面功能。