差别
这里会显示出您选择的修订版和当前版本之间的差别。
| 后一修订版 | 前一修订版 | ||
| electron:快速开始 [2026/11/03 23:52] – 创建 张叶安 | electron:快速开始 [2026/11/03 23:54] (当前版本) – 为快速开始页添加思维导图概览 张叶安 | ||
|---|---|---|---|
| 行 1: | 行 1: | ||
| - | 1 | + | ====== 快速开始 ====== |
| + | |||
| + | Electron 用 **HTML + CSS + JavaScript** 就能写跨平台桌面应用(Windows / macOS / Linux)。它的本质是:**主进程**(Node.js)负责窗口和系统能力,**渲染进程**(Chromium 页面)负责界面,两者通过 IPC 通信。 | ||
| + | |||
| + | ===== 一、环境准备 ===== | ||
| + | |||
| + | * 安装 **Node.js LTS**(建议 18 / 20 及以上),自带 npm;`node -v`、`npm -v` 能输出版本即可。 | ||
| + | * 编辑器推荐 VS Code。 | ||
| + | * 国内下载 Electron 二进制较慢时,先设置镜像: | ||
| + | |||
| + | <code bash> | ||
| + | npm config set registry https:// | ||
| + | npm config set electron_mirror https:// | ||
| + | </ | ||
| + | |||
| + | ===== 二、方式 A:一条命令起项目(推荐新手) ===== | ||
| + | |||
| + | 官方脚手架 Electron Forge 会生成完整工程,自带运行和打包脚本。 | ||
| + | |||
| + | <code bash> | ||
| + | # 创建项目(默认模板) | ||
| + | npm init electron-app@latest my-app | ||
| + | |||
| + | cd my-app | ||
| + | npm start | ||
| + | </ | ||
| + | |||
| + | 想要前端框架 / Vite 热更新模板,加一个 template 参数: | ||
| + | |||
| + | <code bash> | ||
| + | npx create-electron-app@latest my-app --template=vite | ||
| + | npm start | ||
| + | </ | ||
| + | |||
| + | 生成的目录大致是这样: | ||
| + | |||
| + | < | ||
| + | my-app/ | ||
| + | ├── package.json | ||
| + | ├── forge.config.js | ||
| + | └── src/ | ||
| + | ├── main.js | ||
| + | ├── preload.js | ||
| + | └── index.html | ||
| + | </ | ||
| + | |||
| + | ===== 三、方式 B:手写最小项目(想理解原理必看) ===== | ||
| + | |||
| + | 新建目录后三步: | ||
| + | |||
| + | <code bash> | ||
| + | mkdir my-app && cd my-app | ||
| + | npm init -y | ||
| + | npm install --save-dev electron | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | <code js> | ||
| + | const { app, BrowserWindow } = require(' | ||
| + | const path = require(' | ||
| + | |||
| + | function createWindow () { | ||
| + | const win = new BrowserWindow({ | ||
| + | width: 1024, | ||
| + | height: 768, | ||
| + | webPreferences: | ||
| + | preload: path.join(__dirname, | ||
| + | contextIsolation: | ||
| + | nodeIntegration: | ||
| + | } | ||
| + | }) | ||
| + | win.loadFile(' | ||
| + | // 调试时可打开开发者工具 | ||
| + | // win.webContents.openDevTools() | ||
| + | } | ||
| + | |||
| + | app.whenReady().then(() => { | ||
| + | createWindow() | ||
| + | // macOS:点击 Dock 图标且没有窗口时重新创建 | ||
| + | app.on(' | ||
| + | if (BrowserWindow.getAllWindows().length === 0) createWindow() | ||
| + | }) | ||
| + | }) | ||
| + | |||
| + | // 除 macOS 外,关闭所有窗口即退出 | ||
| + | app.on(' | ||
| + | if (process.platform !== ' | ||
| + | }) | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | <code js> | ||
| + | const { contextBridge } = require(' | ||
| + | |||
| + | contextBridge.exposeInMainWorld(' | ||
| + | node: () => process.versions.node, | ||
| + | chrome: () => process.versions.chrome, | ||
| + | electron: () => process.versions.electron | ||
| + | }) | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | <code js> | ||
| + | document.getElementById(' | ||
| + | `Electron ${versions.electron()} / Chromium ${versions.chrome()} / Node ${versions.node()}` | ||
| + | </ | ||
| + | |||
| + | '' | ||
| + | |||
| + | <code html> | ||
| + | < | ||
| + | <p id=" | ||
| + | </ | ||
| + | |||
| + | 再在页面末尾用 `script` 标签引入 `./ | ||
| + | |||
| + | 最后启动: | ||
| + | |||
| + | <code bash> | ||
| + | npm start | ||
| + | </ | ||
| + | |||
| + | ===== 四、主进程与渲染进程通信(IPC) ===== | ||
| + | |||
| + | 页面里不能直接调 Node,要请主进程代劳,推荐 `invoke` / `handle` 这一对。 | ||
| + | |||
| + | 主进程注册处理函数: | ||
| + | |||
| + | <code js> | ||
| + | const { ipcMain, dialog } = require(' | ||
| + | |||
| + | ipcMain.handle(' | ||
| + | const r = await dialog.showOpenDialog({ properties: [' | ||
| + | return r.canceled ? null : r.filePaths[0] | ||
| + | }) | ||
| + | </ | ||
| + | |||
| + | preload 里包一层,暴露给页面: | ||
| + | |||
| + | <code js> | ||
| + | const { contextBridge, | ||
| + | |||
| + | contextBridge.exposeInMainWorld(' | ||
| + | pickFile: () => ipcRenderer.invoke(' | ||
| + | }) | ||
| + | </ | ||
| + | |||
| + | 页面里调用: | ||
| + | |||
| + | <code js> | ||
| + | const file = await window.api.pickFile() | ||
| + | console.log(' | ||
| + | </ | ||
| + | |||
| + | ===== 五、调试与打包 ===== | ||
| + | |||
| + | * 调试渲染进程:`win.webContents.openDevTools()`,或快捷键 Ctrl+Shift+I。 | ||
| + | * 调试主进程:启动时加 `--inspect=5858`,再用 VS Code 附加到该端口。 | ||
| + | * 打包(Forge 项目): | ||
| + | |||
| + | <code bash> | ||
| + | npm run make # 生成安装包,产物在 out/ | ||
| + | npm run package | ||
| + | </ | ||
| + | |||
| + | * 常用 maker:Windows 用 Squirrel 或 WiX,macOS 用 DMG,Linux 用 deb / rpm。 | ||
| + | * 若项目用的是 electron-builder:`npx electron-builder --win --x64`,配置写在 package.json 的 `build` 字段。 | ||
| + | |||
| + | ===== 六、安全清单(别踩坑) ===== | ||
| + | |||
| + | * `contextIsolation: | ||
| + | * 只通过 `contextBridge` 暴露**最小、具体**的函数,不要直接把 `ipcRenderer` 或 `require` 丢给页面。 | ||
| + | * 页面里加 CSP,不要加载来路不明的远程脚本。 | ||
| + | * IPC 处理函数要校验参数,尤其是文件路径和要执行的命令。 | ||
| + | |||
| + | ===== 七、常见问题 ===== | ||
| + | |||
| + | ^ 现象 ^ 原因 / 解决 ^ | ||
| + | | `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 打包、裁剪资源来瘦身 | | ||
| + | |||
| + | ===== 八、下一步 ===== | ||
| + | |||
| + | * 需要菜单、托盘、系统通知,看 `Menu`、`Tray`、`Notification` 模块。 | ||
| + | * 需要读写本地文件或 SQLite,放在主进程做,再通过 IPC 暴露。 | ||
| + | * 需要自动更新,用 `autoUpdater`(Forge 有 update 插件)。 | ||
| + | * 想用 React / Vue,直接用 electron-vite 或 Forge 的 vite 模板起步最省事。 | ||
| + | |||
| + | ===== 一图概览 ===== | ||
| + | |||
| + | ```mdk height=480 color=# | ||
| + | # Electron 快速开始 | ||
| + | |||
| + | ## 环境准备 | ||
| + | |||
| + | - Node.js LTS | ||
| + | - npm registry 与 electron 镜像 | ||
| + | |||
| + | ## 方式 A:脚手架 | ||
| + | |||
| + | - npm init electron-app | ||
| + | - src/main.js 主进程 | ||
| + | - src/ | ||
| + | - src/ | ||
| + | - 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 参数 | ||
| + | ``` | ||