目录

快速开始

Electron 用 HTML + CSS + JavaScript 就能写跨平台桌面应用(Windows / macOS / Linux)。它的本质是:主进程(Node.js)负责窗口和系统能力,渲染进程(Chromium 页面)负责界面,两者通过 IPC 通信。

一、环境准备

npm config set registry https://registry.npmmirror.com
npm config set electron_mirror https://npmmirror.com/mirrors/electron/

二、方式 A:一条命令起项目(推荐新手)

官方脚手架 Electron Forge 会生成完整工程,自带运行和打包脚本。

# 创建项目(默认模板)
npm init electron-app@latest my-app
 
cd my-app
npm start

想要前端框架 / Vite 热更新模板,加一个 template 参数:

npx create-electron-app@latest my-app --template=vite
npm start

生成的目录大致是这样:

my-app/
├── package.json      # main 指向主进程入口,scripts.start 启动应用
├── forge.config.js   # 打包配置(maker)
└── src/
    ├── main.js       # 主进程:创建窗口、生命周期
    ├── preload.js    # 预加载脚本:桥接安全 API
    └── index.html    # 渲染进程页面(界面)

三、方式 B:手写最小项目(想理解原理必看)

新建目录后三步:

mkdir my-app && cd my-app
npm init -y
npm install --save-dev electron

1. package.json —— 关键是 main 指向主进程、start 用 electron 启动:

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

2. main.js —— 主进程入口,只负责开窗口:

const { app, BrowserWindow } = require('electron')
const path = require('node:path')
 
function createWindow () {
  const win = new BrowserWindow({
    width: 1024,
    height: 768,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,   // 默认值,务必保持 true
      nodeIntegration: false    // 页面里不直接用 Node
    }
  })
  win.loadFile('index.html')
  // 调试时可打开开发者工具
  // win.webContents.openDevTools()
}
 
app.whenReady().then(() => {
  createWindow()
  // macOS:点击 Dock 图标且没有窗口时重新创建
  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})
 
// 除 macOS 外,关闭所有窗口即退出
app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') app.quit()
})

3. preload.js —— 把需要的能力安全地暴露给页面:

const { contextBridge } = require('electron')
 
contextBridge.exposeInMainWorld('versions', {
  node: () => process.versions.node,
  chrome: () => process.versions.chrome,
  electron: () => process.versions.electron
})

4. renderer.js —— 页面脚本,只能用上面暴露的 window.versions:

document.getElementById('ver').textContent =
  `Electron ${versions.electron()} / Chromium ${versions.chrome()} / Node ${versions.node()}`

3. index.html —— 就是一个普通网页:一个标题、一个用来显示版本号的段落。示例核心内容:

<h1>你好,Electron</h1>
<p id="ver"></p>

再在页面末尾用 script 标签引入 ./renderer.js,并在 head 中加一条 CSP meta(例如 default-src 'self')。

最后启动:

npm start

四、主进程与渲染进程通信(IPC)

页面里不能直接调 Node,要请主进程代劳,推荐 invoke / handle 这一对。

主进程注册处理函数:

const { ipcMain, dialog } = require('electron')
 
ipcMain.handle('pick-file', async () => {
  const r = await dialog.showOpenDialog({ properties: ['openFile'] })
  return r.canceled ? null : r.filePaths[0]
})

preload 里包一层,暴露给页面:

const { contextBridge, ipcRenderer } = require('electron')
 
contextBridge.exposeInMainWorld('api', {
  pickFile: () => ipcRenderer.invoke('pick-file')
})

页面里调用:

const file = await window.api.pickFile()
console.log('选中文件:', file)

五、调试与打包

npm run make      # 生成安装包,产物在 out/
npm run package   # 只打包成可执行目录,不做安装程序

六、安全清单(别踩坑)

七、常见问题

现象 原因 / 解决
npm start 报找不到 electron 依赖没装好,重装一次:npm install --save-dev electron
启动后白屏 检查 loadFile 路径和 package.json 的 main 是否指对入口,打开 DevTools 看报错
require is not defined 页面里本来就不该用 Node,改用 preload + IPC 的方式
下载 Electron 卡住或超时 配置 electron_mirror 镜像,或删掉 node_modules 后重装
改了页面不自动刷新 手动 Ctrl+R 刷新,或用 Vite 模板获得热更新
安装包几百 MB 正常,Electron 内置整个 Chromium;可用 asar 打包、裁剪资源来瘦身

八、下一步

一图概览

# Electron 快速开始

## 环境准备

- Node.js LTS
- npm registry 与 electron 镜像

## 方式 A:脚手架

- npm init electron-app
- src/main.js 主进程
- src/preload.js 桥接
- src/index.html 界面
- npm start 运行

## 方式 B:手写最小项目

- package.json:main 与 start
- main.js:BrowserWindow 开窗口
- preload.js:contextBridge 暴露 API
- index.html:普通网页
- renderer.js:页面脚本

## 主进程与渲染进程

- 主进程:窗口、系统能力
- 渲染进程:Chromium 页面
- IPC:ipcMain.handle / ipcRenderer.invoke

## 调试与打包

- DevTools 调试页面
- --inspect 调试主进程
- npm run make 出安装包
- electron-builder 也可

## 安全要点

- contextIsolation 开启
- nodeIntegration 关闭
- 只暴露最小 API
- 加 CSP、校验 IPC 参数