跳至主要內容

安装Electron

刘春龙原创2026/3/5...大约 6 分钟WEB前端Electron教程文档

安装 Electron 📦

环境要求 💎

在开始安装 Electron 之前，请确保本机已具备以下环境：

前提条件

  • Node.js：建议使用 20.x 或更高版本（electron-vite 官方推荐 20+）
  • 包管理器：pnpm（强烈推荐，速度快、磁盘占用小，且与 electron-vite 配合最佳）
  • 开发工具：建议使用 VSCode，配合 ESLint + Prettier 获得最佳开发体验

查看 Node.js 与 pnpm 版本

node -v
pnpm -v

如果没有安装 pnpm：

# 使用 npm 全局安装 pnpm
npm install -g pnpm

推荐方式：electron-vite 脚手架 💎

electron-vite 是目前最受欢迎的 Electron 工程化脚手架之一，它结合了 Vite 的极速开发体验 与 Electron 的跨平台能力，是现代化 Electron 开发的首选方案。

一键创建项目

pnpm create electron-vite@latest my-electron-app

执行命令后，脚手架会引导你选择模板与功能：

? Project name: › my-electron-app
? Project template: › - Use arrow-keys. Return to submit.
>   Vue
    React
    Vanilla（原生 JS）
? Add TypeScript? › Yes / No
? Add Electron updater plugin? › Yes / No
? Enable Electron download mirror proxy? › Yes / No

常用回答推荐

  • 模板：按你熟悉的技术栈选择（Vue/React/Vanilla）
  • TypeScript：建议选择 Yes，类型提示对工程化项目帮助极大
  • Electron updater：需要做应用自动更新就选 Yes，否则 No
  • 下载镜像：国内网络建议选 Yes，会使用 npmmirror 镜像下载 Electron 二进制包

如果想跳过交互式选择，可以直接传参：

# 创建 Vue + TS 模板
pnpm create electron-vite@latest my-electron-app -- --template vue-ts

# 创建 React + TS 模板
pnpm create electron-vite@latest my-electron-app -- --template react-ts

# 创建原生 JS 模板
pnpm create electron-vite@latest my-electron-app -- --template vanilla

安装依赖并启动

# 进入项目目录
cd my-electron-app

# 安装依赖
pnpm install

# 启动开发服务器（同时启动主进程、预加载脚本、渲染进程）
pnpm dev

启动成功后，会同时弹出桌面窗口，并自动打开 http://localhost:5173（渲染进程调试地址）。

打包构建

# 仅打包（不安装）
pnpm build

# 打包并生成安装包（Windows: .exe，macOS: .dmg，Linux: .AppImage）
pnpm build:win    # Windows
pnpm build:mac    # macOS
pnpm build:linux  # Linux
pnpm build:unpack # 打包但不制作安装包（仅生成解压目录）

启动后，Electron 会自动打开一个桌面窗口，窗口标题为「my-electron-app」，页面中央会显示当前模板（Vue/React）的欢迎页面，背景为深色卡片样式。

脚手架生成的项目结构 💎

electron-vite 脚手架默认生成的目录结构非常清晰：

└─ my-electron-app
   ├─  resources              --- 应用图标、安装包资源
   │  └─  icon.png
   ├─  src
   │  ├─  main                --- 主进程源码
   │  │  ├─  index.ts        --- 主进程入口
   │  │  └─  ipc.ts          --- IPC 通信模块（可选）
   │  ├─  preload             --- 预加载脚本
   │  │  └─  index.ts        --- 预加载脚本入口
   │  └─  renderer            --- 渲染进程源码（前端项目）
   │     ├─  src
   │     │  ├─  assets       --- 静态资源
   │     │  ├─  components   --- 组件
   │     │  ├─  App.vue      --- 根组件（Vue 模板）
   │     │  ├─  main.ts      --- 入口文件
   │     │  └─  env.d.ts     --- 类型声明
   │     └─  index.html      --- 渲染进程入口 HTML
   ├─  electron.vite.config.ts --- electron-vite 配置
   ├─  electron-builder.yml    --- 打包配置
   ├─  package.json
   ├─  tsconfig.json
   └─  tsconfig.node.json

三个进程目录

  • src/main：主进程，运行在 Node.js 环境，独占一个进程
  • src/preload：预加载脚本，在渲染进程加载前运行，充当主进程与渲染进程的桥梁
  • src/renderer：渲染进程，即我们熟悉的前端项目（Vue/React/原生）

主进程入口代码 💎

electron-vite 脚手架默认生成的主进程代码已经非常完善，我们可以基于此进行扩展：

// src/main/index.ts
import { app, BrowserWindow, shell } from 'electron'
import { join } from 'path'
import { electronApp, optimizer, is } from '@electron-toolkit/utils'

function createWindow(): void {
  // 创建浏览器窗口
  const mainWindow = new BrowserWindow({
    width: 1024,
    height: 768,
    show: false,                // 先隐藏，等 ready-to-show 时再显示，避免白屏闪烁
    autoHideMenuBar: true,      // 自动隐藏菜单栏（Windows/Linux）
    titleBarStyle: 'hiddenInset', // macOS 沉浸式标题栏
    backgroundColor: '#1e1e1e',  // 窗口背景色，避免白屏
    webPreferences: {
      preload: join(__dirname, '../preload/index.js'),
      sandbox: false,           // 是否启用沙箱
      contextIsolation: true,   // 启用上下文隔离（推荐）
      nodeIntegration: false,   // 关闭 Node 集成（推荐）
    },
  })

  mainWindow.on('ready-to-show', () => {
    mainWindow.show()
  })

  mainWindow.webContents.setWindowOpenHandler((details) => {
    // 默认在系统浏览器中打开新窗口的链接
    shell.openExternal(details.url)
    return { action: 'deny' }
  })

  // 开发环境加载远程地址，生产环境加载本地文件
  if (is.dev && process.env['ELECTRON_RENDERER_URL']) {
    mainWindow.loadURL(process.env['ELECTRON_RENDERER_URL'])
  } else {
    mainWindow.loadFile(join(__dirname, '../renderer/index.html'))
  }
}

app.whenReady().then(() => {
  // 设置应用名称（Windows 上的快捷方式名称）
  electronApp.setAppUserModelId('com.electron.my-app')

  // 开发环境按 F12 打开 / 关闭开发者工具
  app.on('browser-window-created', (_, window) => {
    optimizer.watchWindowShortcuts(window)
  })

  createWindow()

  app.on('activate', () => {
    // macOS：点击 dock 图标时重新创建窗口
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

// 所有窗口关闭时退出应用（Windows/Linux）
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') app.quit()
})

关键配置项

  • show: false：先隐藏窗口，等 ready-to-show 时再显示，避免白屏闪烁
  • contextIsolation: true：启用上下文隔离，是 Electron 12+ 的安全最佳实践
  • nodeIntegration: false：关闭渲染进程的 Node 集成，所有 Node 能力通过 preload 暴露
  • setWindowOpenHandler：拦截 window.open()，让外链在系统浏览器中打开

预加载脚本代码 💎

// src/preload/index.ts
import { contextBridge, ipcRenderer } from 'electron'
import { electronAPI } from '@electron-toolkit/preload'

// 通过 contextBridge 安全地暴露 API 给渲染进程
if (process.contextIsolated) {
  try {
    contextBridge.exposeInMainWorld('electron', {
      ...electronAPI,
      // 自定义 API
      sendMessage: (msg: string) => ipcRenderer.send('message', msg),
      onMessage: (callback: (msg: string) => void) =>
        ipcRenderer.on('message', (_, msg) => callback(msg)),
    })
  } catch (error) {
    console.error(error)
  }
} else {
  // @ts-ignore (define in dts)
  window.electron = {
    ...electronAPI,
    sendMessage: (msg: string) => ipcRenderer.send('message', msg),
    onMessage: (callback: (msg: string) => void) =>
      ipcRenderer.on('message', (_, msg) => callback(msg)),
  }
}

contextIsolation 的作用

开启 contextIsolation 后，渲染进程的 window 对象与预加载脚本的全局对象是隔离的，渲染进程无法直接访问 ipcRenderer 等 Node API。只能通过 contextBridge.exposeInMainWorld 显式暴露的 API 进行通信，这是 Electron 推荐的安全做法。

渲染进程调用主进程 API 💎

通过上面预加载脚本暴露的 window.electron.sendMessage，渲染进程可以直接调用：

// src/renderer/src/main.ts
// 全局可访问 window.electron.sendMessage / onMessage
;(window as any).electron.sendMessage('Hello from Renderer')

;(window as any).electron.onMessage((msg: string) => {
  console.log('收到主进程消息：', msg)
})

如果想让 TypeScript 给出更好的类型提示，可以在 env.d.ts 中声明全局类型：

// src/renderer/src/env.d.ts
export {}

declare global {
  interface Window {
    electron: {
      sendMessage: (msg: string) => void
      onMessage: (callback: (msg: string) => void) => void
      // ... 其他 API
    }
  }
}

常见问题 💎

安装依赖时卡在 Electron 二进制包下载 👻

国内网络环境下经常遇到，可使用以下任一方案解决：

# 方案一：临时设置环境变量
set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/    # Windows CMD
export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/  # macOS/Linux
pnpm install

# 方案二：npm 全局配置
npm config set ELECTRON_MIRROR https://npmmirror.com/mirrors/electron/

# 方案三：脚手架交互时直接选择"启用下载镜像代理"

启动后白屏 👻

通常是渲染进程加载失败导致，可以：

  1. 打开 http://localhost:5173 单独确认渲染进程是否正常
  2. 在主进程代码中检查 loadURL / loadFile 路径是否正确
  3. 打开开发者工具（默认按 Ctrl+Shift+I / Cmd+Option+I）查看报错

端口被占用 👻

Vite 默认使用 5173 端口，可修改 electron.vite.config.ts：

import { defineConfig, externalizeDepsPlugin } from 'electron-vite'

export default defineConfig({
  main: { /* ... */ },
  preload: { /* ... */ },
  renderer: {
    server: {
      port: 5174, // 修改端口
    },
  },
})

pnpm 安装时提示缺少依赖 👻

可以删除 node_modules 与 lock 文件后重装：

rm -rf node_modules pnpm-lock.yaml
pnpm install

小结

本章我们学习了 Electron 的现代化安装方式：

  1. electron-vite 脚手架：pnpm create electron-vite@latest 一键创建企业级项目
  2. 三大进程目录：主进程、预加载脚本、渲染进程
  3. 安全最佳实践：开启 contextIsolation、关闭 nodeIntegration
  4. 常见问题解决：镜像源、白屏、端口冲突等

下一章我们将深入学习 主进程与渲染进程 的关系。

至此，本章节的学习就到此结束了，如有疑惑，可对接技术客服进行相关咨询。

最近更新:
贡献者: 刘春龙
嘉美开发社区 https://jiameisq.top
Copyright © 2026 刘春龙