跳到主要内容

环境搭建

本节介绍如何搭建 Electron 开发环境，包括 Node.js 安装、项目初始化、开发工具配置等内容。

安装 Node.js​

Electron 基于 Node.js 构建，首先需要安装 Node.js 运行环境。

下载安装​

访问 Node.js 官网，下载并安装 LTS 版本。LTS 版本更加稳定，适合生产环境使用。

验证安装​

安装完成后，打开终端验证：

node -v
# 输出示例: v20.10.0

npm -v
# 输出示例: 10.2.3

版本管理工具​

如果你需要在多个项目间切换 Node.js 版本，推荐使用版本管理工具：

Windows：nvm-windows

# 安装 nvm-windows 后
nvm install 20
nvm use 20

macOS/Linux：nvm

# 安装 nvm 后
nvm install 20
nvm use 20

创建项目​

初始化项目​

创建项目目录并初始化：

mkdir my-electron-app
cd my-electron-app
npm init -y

npm init -y 会生成一个默认的 package.json 文件。

安装 Electron​

将 Electron 安装为开发依赖：

npm install electron --save-dev

安装完成后，package.json 会更新：

{
  "name": "my-electron-app",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "devDependencies": {
    "electron": "^28.0.0"
  }
}

配置 package.json​

修改 package.json 以适配 Electron 项目：

{
  "name": "my-electron-app",
  "version": "1.0.0",
  "description": "我的第一个 Electron 应用",
  "main": "main.js",
  "scripts": {
    "start": "electron .",
    "build": "electron-builder"
  },
  "author": "Your Name",
  "license": "MIT",
  "devDependencies": {
    "electron": "^28.0.0",
    "electron-builder": "^24.9.1"
  }
}

关键配置说明：

  • main：指定主进程入口文件，默认是 index.js，通常改为 main.js
  • scripts.start：定义启动命令，运行 npm start 即可启动应用

项目结构​

基本结构​

一个最小化的 Electron 项目结构：

my-electron-app/
├── package.json        # 项目配置文件
├── main.js             # 主进程入口
├── preload.js          # 预加载脚本
├── index.html          # 主窗口页面
├── renderer.js         # 渲染进程脚本
└── styles/
    └── main.css        # 样式文件

创建主进程文件​

创建 main.js：

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

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

  mainWindow.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()
  }
})

创建预加载脚本​

创建 preload.js：

const { contextBridge } = require('electron')

contextBridge.exposeInMainWorld('electronAPI', {
  platform: process.platform,
  versions: process.versions
})

创建页面文件​

创建 index.html：

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
  <title>我的 Electron 应用</title>
  <link rel="stylesheet" href="styles/main.css">
</head>
<body>
  <h1>Hello Electron!</h1>
  <p>当前平台: <span id="platform"></span></p>
  <p>Node 版本: <span id="node-version"></span></p>
  <p>Electron 版本: <span id="electron-version"></span></p>
  
  <script src="renderer.js"></script>
</body>
</html>

创建渲染进程脚本​

创建 renderer.js：

document.getElementById('platform').textContent = window.electronAPI.platform
document.getElementById('node-version').textContent = window.electronAPI.versions.node
document.getElementById('electron-version').textContent = window.electronAPI.versions.electron

运行项目​

在项目根目录执行：

npm start

如果一切正常，会弹出一个窗口显示 "Hello Electron!" 以及系统信息。

开发工具​

VS Code 配置​

VS Code 是开发 Electron 应用的推荐编辑器。推荐安装以下扩展：

  • ESLint：JavaScript 代码检查
  • Prettier：代码格式化

创建 .vscode/launch.json 配置调试：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Main Process",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
      "windows": {
        "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd"
      },
      "args": ["."],
      "outputCapture": "std"
    }
  ]
}

Electron Fiddle​

Electron Fiddle 是官方提供的在线实验工具，可以快速测试 Electron 代码片段，无需本地安装环境。

特点：

  • 在线编写和运行 Electron 代码
  • 支持不同版本的 Electron
  • 可以导出完整项目
  • 可以直接打开官方文档中的示例

开发者工具​

Electron 窗口默认支持 Chrome DevTools。在主进程中可以控制开发者工具：

const mainWindow = new BrowserWindow({
  width: 800,
  height: 600
})

// 打开开发者工具
mainWindow.webContents.openDevTools()

也可以通过快捷键打开：

  • Windows/Linux：Ctrl + Shift + I 或 F12
  • macOS：Cmd + Option + I

热重载配置​

开发过程中，每次修改代码都需要重启应用比较麻烦。可以使用 electron-reload 实现热重载。

安装依赖​

npm install electron-reload --save-dev

配置热重载​

在 main.js 开头添加：

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

// 开发环境下启用热重载
if (process.env.NODE_ENV !== 'production') {
  require('electron-reload')(__dirname, {
    electron: path.join(__dirname, 'node_modules', '.bin', 'electron')
  })
}

// ... 其余代码

使用 electronmon​

另一种选择是使用 electronmon：

npm install electronmon --save-dev

修改 package.json：

{
  "scripts": {
    "start": "electronmon ."
  }
}

electronmon 会监听文件变化并自动重启应用。

TypeScript 支持​

如果你使用 TypeScript 开发，需要进行额外配置。

安装依赖​

npm install typescript @types/node @types/electron --save-dev

配置 tsconfig.json​

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020", "DOM"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

项目结构调整​

my-electron-app/
├── src/
│   ├── main.ts         # 主进程源码
│   ├── preload.ts      # 预加载脚本源码
│   └── renderer.ts     # 渲染进程源码
├── dist/               # 编译输出目录
├── package.json
└── tsconfig.json

编译脚本​

{
  "scripts": {
    "build": "tsc",
    "start": "npm run build && electron dist/main.js",
    "watch": "tsc -w"
  }
}

常见问题​

安装 Electron 慢​

Electron 包体积较大，国内下载可能较慢。可以设置镜像源：

# 设置 Electron 镜像
npm config set electron_mirror https://npmmirror.com/mirrors/electron/

# 或者使用环境变量
export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/

权限问题​

在 macOS 上首次运行可能需要授权：

# 允许运行来自身份不明开发者的应用
xattr -cr my-electron-app/

版本兼容​

不同版本的 Electron 捆绑了不同版本的 Node.js 和 Chromium。查看版本对应关系：

console.log(process.versions)

输出示例：

{
  node: '18.17.1',
  chrome: '120.0.6099.56',
  electron: '28.0.0',
  v8: '12.0.267.8-electron.0'
}

下一步​

环境搭建完成后，你可以继续学习：