Electron 起步与三个执行位置

本页整合 Electron 归档分稿中的机制、接口和接线。归档使用 Electron 44 系列作为其版本讨论背景；本文接口依据官方文档及 breaking changes 核查，实际采用时仍需固定项目版本。包版本、维护状态和原稿实测均是对应日期的历史信息。本次未启动 Electron、构建安装包、签名、公证或验证更新。代码块按各自标注区分片段与组合示例。

版本基准:本章所有命令与代码基于 Electron 44.5.1(当前最新稳定版,2026-09-29 发布,内置 Chromium 152.0.7977.130 与 Node.js 24.21.0,版本数据来自官方 releases.electronjs.org 的 releases.json)。撰写日期 2026-10-04;本章所有标着「实测」的输出,均为当日在一台 Apple Silicon macOS(Node.js v24.12.0 / npm 11.6.2)上真实运行的结果。官方当前支持最近三个稳定大版本(44/43/42),如果你的项目还在 41 及以下,建议先升级(参见第七章)。

11.1 开始之前:你需要会到什么程度复制锚点链接

Electron 官方教程的前言说得很直白:它假设你「generally familiar with Node and front-end web development basics」——大体熟悉 Node 和前端 Web 开发基础即可(官方 Prerequisites 教程)。换句话说,你不需要精通前端,只需要一个「最小知识集合」。下表按三门功课列出第一天真正会用到的部分,对着自查即可:

三条「不需要」先说清楚,免得被劝退:

1. 不需要会 React / Vue 等框架。Electron 的窗口里跑的就是普通网页,本章全程零框架。
2. 不需要会 webpack / Vite 等构建工具。本章的应用不打包、不转译,写什么就跑什么。
3. 不需要系统学完 Node.js。你在网页开发里用不到的那一半 Node(服务器、数据库)在 Electron 里同样用得很少。

如果 HTML/JS 有缺口,官方推荐的两份免费材料是 MDN 的 Getting started with the Web 和 Introduction to Node.js;缺什么查什么,不必通读。

还有一个今天就要建立的关键认知(官方教程原文强调):Electron 应用不使用你系统里安装的 Node.js 来运行代码,它自带一份编译进去的 Node 运行时(44.5.1 内置的是 Node 24.21.0)。你装的 Node 只是「开发工具链」——npm、脚手架、打包工具靠它跑。所以最终用户不需要装 Node 也能运行你发布的应用。想知道应用内部实际用的 Node 版本,可在主进程或 preload 里打印 process.versions(下文代码会用到)。

11.2 安装 Node.js 与验证环境复制锚点链接

11.2.1 安装哪个版本复制锚点链接

官方建议:使用最新的 LTS 版本(Long-Term Support,长期支持版,指官方承诺维护约 30 个月的稳定分支)。截至 2026-10-04,nodejs.org 显示最新 LTS 为 v24.21.0(代号 Krypton)。同时请注意各工具的最低版本门槛(以下均为 npm registry 中各包 engines 字段的实际值,2026-10-04 查询):

结论:装 Node 24 LTS 一律满足。一个版本差异提醒:Forge 官网文档的 Prerequisites 页目前仍写着「Node.js ≥ v16.4.0」,这是滞后的旧文档;以 npm 包实际的 engines 字段(≥ 22.13.0)为准——Node 过旧时 npm 会直接报错。

11.2.2 怎么装复制锚点链接

官方推荐使用平台对应的预编译安装器(nodejs.org 首页下载 LTS 安装包,一路下一步);macOS 用户官方还推荐用 Homebrew(brew install node@24)或 nvm(nvm install 24)来避免目录权限问题。Windows 用户请务必装原生版 Node,不要在 WSL(Windows Subsystem for Linux,Windows 的 Linux 子系统)里学 Electron——官方教程明确警告在 WSL 中执行应用会出问题。

装完验证(官方教程原文的检查方式):

node -v   # 应输出 v24.x.x,例如 v24.21.0
npm -v    # 应输出 11.x 左右,例如 11.6.2

原调研记录:本章撰写机器为 node -v → v24.12.0,npm -v → 11.6.2,满足全部门槛。

11.2.3 国内网络注意点:两个镜像复制锚点链接

Electron 安装分两层,国内网络要分别照顾:

第一层:npm 包本身(一个很小的 JS 壳,几秒装完)。如果 npm 官方源慢,可切换到 npmmirror(原淘宝 npm 镜像)的 registry:

npm config set registry https://registry.npmmirror.com

第二层:Electron 预编译二进制(约 100MB 的 zip,包含完整 Chromium + Node)。从 Electron 42 起,npm 包不再在 npm install 时用 postinstall 钩子下载二进制,而是第一次运行 electron . 时才按需下载(原调研记录 npm install 秒完成、首次 npm start 时终端打印 Downloading Electron binary...;此变化可对比 npm 上 38.x 有 postinstall、42.x 起没有)。默认从 GitHub Releases 下载,国内常超时。官方文档(Advanced Installation)直接给出了国内镜像的配置:

# 临时用(只对当次命令生效):macOS/Linux
ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/" npm start
# Windows(PowerShell)
$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"; npm start

一劳永逸的写法是放进项目的 .npmrc 文件(npm 与 @electron/get 都会读,npm 会把 npm_config_ 前缀的配置注入环境变量):

# .npmrc(放在项目根目录,与 package.json 同级)
registry=https://registry.npmmirror.com
electron_mirror=https://npmmirror.com/mirrors/electron/

原调研记录:2026-10-04 用 curl 访问 https://npmmirror.com/mirrors/electron/v44.5.1/SHASUMS256.txt,返回 302 跳转到 cdn.npmmirror.com 后 200,镜像当前有效。下载成功的二进制会缓存在本地(macOS 在 ~/Library/Caches/electron/,Linux 在 ~/.cache/electron/,Windows 在 %LOCALAPPDATA%\electron\Cache),之后即使换项目也不会重复下载。

11.3 三种起步方式对比与推荐复制锚点链接

「第一个 Electron 项目怎么开」在 2026 年有三条主流路径:

本章从方式 A 展开。 手动组织三个入口文件，能够直接对应主进程、渲染进程与 preload 的责任及通信关系。已有工程经验或需要框架集成时，可以使用脚手架，并核对它生成的进程入口、构建目标和权限配置。官方教程先说明最小应用，再接入 Forge 打包分发。

方式 B 一句话预览(第八章会展开):Forge 是 Electron 官方维护的「脚手架 + 打包 + 发布」一体化工具,npx create-electron-app@latest my-app 之后 cd my-app && npm start 即可运行,npm run make 一键产出各平台安装包;注意它打包时要求 node_modules 真实落盘——用 pnpm 需在 .npmrc 加 node-linker=hoisted,用 Yarn ≥ 2 需设 nodeLinker: node-modules(Forge 官网 Getting Started 明确说明)。

方式 C 一句话预览:electron-vite(当前 v5.0.0)是社区事实标准的构建工具,为 main / preload / renderer 三段代码分别建立 Vite 构建,渲染进程获得完整的 HMR(Hot Module Replacement,热模块替换,改代码浏览器即时刷新不用手动重载),脚手架的 npm run dev、npm run build、npm run preview 分别对应开发、生产构建、预览产物;构建后入口在 out/main/index.js,所以其 package.json 的 main 字段指向 ./out/main/index.js(electron-vite 官方指南)。

11.4 方式 A 实操:十分钟跑起第一个应用复制锚点链接

下面每一步都可直接照抄。目标目录结构(最终):

my-electron-app/
├── package.json      # 项目清单,Electron 靠它找到入口
├── main.js           # 主进程入口
├── preload.js        # 预加载脚本(渲染进程与主进程之间的桥)
├── index.html        # 界面(渲染进程加载的页面)
├── renderer.js       # 页面行为脚本(index.html 引入)
├── .gitignore        # 告诉 Git 忽略哪些文件
└── node_modules/     # 依赖(自动生成,勿手改、勿提交)

步骤 1:建目录并初始化 npm 项目复制锚点链接

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

npm init 会逐项询问并生成 package.json。唯一要留意的是 entry point(入口)一项,填 main.js——这就是将来告诉 Electron「从哪个文件启动」的字段。其余如 author、license、description 随意填,但别留空:后面用 Forge 打包时它们是必需元数据(官方教程原话)。一路回车到底也行,回头改文件即可。

步骤 2:把 Electron 装为开发依赖复制锚点链接

npm install electron --save-dev

--save-dev 把它写进 package.json 的 devDependencies(开发依赖,即只在开发阶段需要的包)。Electron 明明是「运行时」,为什么放开发依赖?官方教程专门解释过:你的代码调用的 Electron API 背后绑定在一个巨大的预编译二进制里,打包工具会在构建应用时把这个二进制一起打进去,所以运行期不需要(也不应该)通过 npm 再装一份。

步骤 3:加 .gitignore复制锚点链接

就算你暂时不用 Git,也建议放一个(GitHub 官方 Node 模板的精简版):

# .gitignore
node_modules/
npm-debug.log

核心是别把上百 MB 的 node_modules 提交进版本库。

步骤 4:先用一行代码确认「能跑」复制锚点链接

在项目根目录新建 main.js,只写一行(先跑通再写复杂代码,出问题时好定位):

console.log('Hello from Electron 👋')

然后打开 package.json,在 scripts 里加一行 start 脚本(下一步解释它):

{
  "name": "my-electron-app",
  "version": "1.0.0",
  "description": "Hello World!",
  "main": "main.js",
  "scripts": {
    "start": "electron ."
  },
  "author": "你的名字",
  "license": "MIT",
  "devDependencies": {
    "electron": "^44.5.1"
  }
}

运行:

npm start

实测(2026-10-04,macOS arm64):首次运行终端先打印 Downloading Electron binary...(Electron 42+ 的按需下载行为),随后输出 Hello from Electron 👋。看到这行,说明主进程这条 Node.js 通道已经通了。

步骤 5:写三个核心文件(完整代码)复制锚点链接

现在解释三个名词,然后给全量代码:

• 主进程(main process):由 main.js 启动的那个 Node.js 进程,掌管应用生命周期、创建窗口、调用操作系统能力。整个应用只有一个。
• 渲染进程(renderer process):每个窗口里跑网页的进程,用的是 Chromium 的网页能力,默认没有 Node 权限(出于安全)。
• Preload 脚本(preload script,预加载脚本):在网页加载之前注入渲染进程的特殊脚本,像一座桥:既能摸到一部分 Electron API,又能通过 contextBridge(上下文桥,Electron 提供的安全暴露 API)把少量能力安全地交給网页用。Electron 20 起 preload 默认运行在沙箱中,只能 require('electron'),不能加载 Node 内置模块(官方 Process Sandboxing 文档)。

main.js(主进程入口,完整):

// main.js —— 主进程入口:运行在内置 Node.js 环境,负责窗口与应用生命周期
const { app, BrowserWindow, ipcMain } = require('electron')
// Electron 28+ 也支持 ESM(import 语法),本教程沿用官方教程的 CommonJS 写法
const path = require('node:path') // Node 内置模块,建议带 node: 前缀

const createWindow = () => {
  const win = new BrowserWindow({
    width: 800,                  // 初始窗口宽 800 像素
    height: 600,                 // 初始窗口高 600 像素
    webPreferences: {
      preload: path.join(__dirname, 'preload.js') // 把 preload.js 注入该窗口
    }
  })
  win.loadFile('index.html')     // 加载本地页面(相对项目根目录)
}

app.whenReady().then(() => {     // app 就绪后才能创建窗口(ready 事件的 Promise 封装)
  ipcMain.handle('ping', () => 'pong')  // 注册 IPC 处理器:收到 'ping' 就回 'pong'
  createWindow()
  app.on('activate', () => {     // macOS 特性:点 Dock 图标而无一窗口时,新开一个
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', () => {      // 所有窗口关闭时触发
  if (process.platform !== 'darwin') app.quit() // Windows/Linux 惯例:随之退出;macOS 留驻
})

preload.js(预加载脚本,完整):

// preload.js —— 页面加载前运行;渲染进程接触特权能力的唯一安全通道
const { contextBridge, ipcRenderer } = require('electron')

contextBridge.exposeInMainWorld('versions', { // 在页面里挂一个全局对象 window.versions
  node: () => process.versions.node,          // 应用内置的 Node 版本
  chrome: () => process.versions.chrome,      // 内置 Chromium 版本
  electron: () => process.versions.electron,  // Electron 版本
  ping: () => ipcRenderer.invoke('ping')      // 包装成函数再暴露,绝不直接暴露 ipcRenderer
})

最后一句注释是官方教程反复强调的安全红线:把整个 ipcRenderer 直接暴露给网页,等于允许网页向主进程发任意消息,是典型攻击面。永远像这样用函数包一层,只开放你设计的通道。

index.html(界面,完整):

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <!-- CSP(Content-Security-Policy,内容安全策略):只允许加载本应用自身的资源。
         这是官方教程模板自带的行,能显著缩小 XSS 攻击面,请保留 -->
    <meta
      http-equiv="Content-Security-Policy"
      content="default-src 'self'; script-src 'self'"
    />
    <title>你好,Electron!</title>
  </head>
  <body>
    <h1>你好,Electron!</h1>
    <p>👋</p>
    <p id="info"></p>
    <script src="./renderer.js"></script>
  </body>
</html>

注意:页面逻辑写在外部文件 renderer.js 里,不是内联 <script>——上面的 CSP(script-src 'self')会直接拦截内联脚本(原调研记录:在 Electron 44.5.1 中内联脚本静默不执行,页面停在旧内容,DevTools 控制台才有报错)。

renderer.js(页面脚本,完整):

// renderer.js —— 运行在渲染进程,和普通网页 JS 一样
const information = document.getElementById('info')
// versions 是 preload.js 通过 contextBridge 暴露出来的全局对象
information.innerText = `This app is using Chrome (v${versions.chrome()}), ` +
  `Node.js (v${versions.node()}), and Electron (v${versions.electron()})`

const func = async () => {
  const response = await window.versions.ping() // 经 IPC 跨进程调用主进程
  console.log(response)                         // 在 DevTools 控制台打印 'pong'
}
func()

步骤 6:运行并核对结果复制锚点链接

npm start

你应该看到一个 800×600 的原生窗口,标题「你好,Electron!」,正文里一行字列出当前 Chromium / Node / Electron 版本。

实测(2026-10-04,Electron 44.5.1):页面显示 This app is using Chrome (v152.0.7977.130), Node.js (v24.21.0), and Electron (v44.5.1),且通过 IPC 调用 ping() 返回 'pong'——主进程、preload、渲染进程、IPC 四条链路全部验证通过。关掉窗口(Windows/Linux)应用随之退出;macOS 下窗口全关后应用仍在 Dock 驻留,再点图标会重开窗口——这正是 main.js 里两段生命周期代码的功劳。

11.5 读懂 package.json:每个字段在干什么复制锚点链接

把步骤 4 里的 package.json 逐字段注释一遍(name 等字段含义以 npm 官方文档为准):

{
  "name": "my-electron-app",     // 包名:小写、无空格;将来发布/被打包时的标识
  "version": "1.0.0",            // 语义化版本号:主版本.次版本.修订号
  "description": "Hello World!", // 一句话描述;Forge 打包时会用
  "main": "main.js",             // 入口:Electron 启动后执行的主进程脚本
                                 // (npm 规范:省略时默认为 index.js)
  "scripts": {
    "start": "electron ."        // npm start → 执行 electron .(点号=当前目录)
  },
  "author": "你的名字",           // 作者;Forge 打包时会用
  "license": "MIT",              // 开源许可证;Forge 打包时会用
  "devDependencies": {
    "electron": "^44.5.1"        // 开发依赖:箭头 ^ 表示允许 44.x.x 内的兼容升级
  }
}

三个值得展开的点:

1. main 字段是 Electron 的「点火钥匙」。electron . 命令的意思是「把当前目录当一个 Electron 应用启动」,它读取这里的 main 找到主进程脚本。文件名不必叫 main.js,但字段值必须与真实文件名一致;npm init 时一路回车会得到默认值 index.js,如果你忘了改、文件又叫 main.js,就会报找不到模块(见 11.7)。

2. scripts 与 npm 的 PATH 魔法。npm start(等价于 npm run start)执行 electron . 时,你会发现直接在终端敲 electron 会提示 command not found——因为 npm 运行脚本时会把项目的 node_modules/.bin 目录临时加入 PATH,这正是本地安装的 electron 命令所在(npm 官方 scripts 文档)。这就是为什么教程从不让你全局安装 Electron。

3. start 是特殊脚本名。test、start、stop、restart 是 npm 的保留脚本,可以用 npm start 这种简写;自定义脚本(如将来 Forge 生成的 "make": "electron-forge make")则要写全 npm run make。

11.6 怎么调试:渲染进程与主进程是两个世界复制锚点链接

调试 Electron 的第一课:先想清楚你要调的代码在哪个进程,因为两者的工具完全不同。

11.6.1 渲染进程:Chromium DevTools复制锚点链接

渲染进程就是网页,用 Chromium 的开发者工具(DevTools)调试,和调试 Chrome 页面一模一样。程序化打开方式(官方 Application Debugging 文档):

// 在 main.js 的 createWindow() 里,win 创建之后加一行:
win.webContents.openDevTools() // 启动即自动打开 DevTools;调试完删掉或加条件

不加这行也没关系:Electron 自带的默认菜单里 View → Toggle Developer Tools 就能随时开关(原调研记录 macOS 44.5.1 中快捷键为 Alt+Command+I,Windows/Linux 一般是 Ctrl+Shift+I,以菜单项右侧显示为准)。renderer.js 里 console.log 的输出就在 DevTools 的 Console 面板。

11.6.2 主进程:--inspect 开调试端口复制锚点链接

主进程不是网页,DevTools 管不到它。官方方案(Debugging the Main Process 文档):给 Electron 加 --inspect 开关,让它监听 V8 inspector 协议端口,再用外部调试器连上去:

npx electron --inspect=9229 .      # 端口可省略,默认就是 9229
npx electron --inspect-brk=9229 .  # 同上,但在第一行代码前暂停(调启动期 bug 用)

实测(2026-10-04):带 --inspect=9229 启动后,终端打印 Debugger listening on ws://127.0.0.1:9229/<uuid>,curl http://127.0.0.1:9229/json/version 返回 {"Browser": "node.js/v24.21.0", ...}。此时在 Chrome 打开 chrome://inspect,点 Configure 添加 localhost:9229,列表里就会出现你的 Electron 应用,点 inspect 即得一个可断点的主进程调试器。

11.6.3 VS Code 一键调试:官方 launch.json复制锚点链接

VS Code 是官方推荐编辑器,官方教程直接给了一份 .vscode/launch.json(主进程 + 渲染进程组合调试,逐字段注释如下):

// .vscode/launch.json —— 在 VS Code 左侧「运行和调试」中选择 "Main + renderer"
{
  "version": "0.2.0",
  "compounds": [
    {
      "name": "Main + renderer",              // 组合:同时启动下面两个配置
      "configurations": ["Main", "Renderer"],
      "stopAll": true                         // 停一个全停
    }
  ],
  "configurations": [
    {
      "name": "Renderer",                     // 渲染进程:attach 到 9222 调试端口
      "port": 9222,
      "request": "attach",                    // 窗口由主进程创建,所以只能"挂上去"
      "type": "chrome",                       // 渲染进程是网页,用 chrome 调试器
      "webRoot": "${workspaceFolder}"
    },
    {
      "name": "Main",                         // 主进程:由 VS Code 直接"启动"
      "type": "node",                         // 主进程是 Node,用 node 调试器
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron", // 用项目内的 electron
      "windows": {
        "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd" // Windows 批处理入口
      },
      "args": [".", "--remote-debugging-port=9222"], // 顺带为渲染进程开 9222 端口
      "outputCapture": "std",
      "console": "integratedTerminal"
    }
  ]
}

在 main.js 里点一行左侧留白设断点,选 Main + renderer 启动,断点命中时能看到所有变量——这套配置来自官方教程 tutorial-2,可直接复制。官方还提醒:渲染进程是后挂载的,页面最开头几行可能在调试器接上之前就执行了,遇到「开头断点不命中」刷新页面即可。

11.7 第一天最常见的报错与解决复制锚点链接

以下是按出现频率排列的「新手第一天」清单,全部有官方文档或实测依据:

万能重置招(改了配置/切换镜像后怀疑状态脏了时):删 node_modules 与 package-lock.json 后重新 npm install。Electron 二进制有本地缓存(macOS 在 ~/Library/Caches/electron/),重装通常不用重新下载。

11.8 小结与下一步复制锚点链接

这一章你完成了零基础的第一天闭环:确认了前置知识的最小集合 → 装好 Node 并处理了国内镜像 → 对比了三种起步方式 → 手动写出并跑通了由 main.js / preload.js / index.html(+renderer.js)组成的完整应用 → 读懂了 package.json 的每个字段 → 掌握了渲染进程 DevTools 与主进程 --inspect 两套调试法 → 预演了第一天最可能撞上的 8 个坑。

你已经亲手用到了三个最重要的进程概念(主进程、渲染进程、preload)和一次完整的 IPC 往返(ping → pong),这三样正是后续所有章节的地基。下一步建议:① 把 ping 改成别的字符串、把窗口尺寸改小,再跑一次,巩固「改哪里→哪里变」的手感;② 进入第二章,系统学习 IPC 通信的模式与安全边界;③ 想先看看「正经项目」长什么样,用 npx create-electron-app@latest forge-demo 生成一个 Forge 项目对照本章的手工版本。

参考来源复制锚点链接

1. Electron 官方教程 · Prerequisites(前置知识与工具): https://www.electronjs.org/docs/latest/tutorial/tutorial-1-prerequisites
2. Electron 官方教程 · Building your First App(初始化、运行、生命周期、VS Code 调试;本章代码与 launch.json 的直接依据,源文件 docs/tutorial/tutorial-2-first-app.md): https://www.electronjs.org/docs/latest/tutorial/tutorial-2-first-app
3. Electron 官方教程 · Using Preload Scripts(preload.js、contextBridge、ping/pong IPC;源文件 docs/tutorial/tutorial-3-preload.md): https://www.electronjs.org/docs/latest/tutorial/tutorial-3-preload
4. Electron 官方文档 · Advanced Installation(镜像 ELECTRON_MIRROR、缓存目录、安装报错排查): https://www.electronjs.org/docs/latest/tutorial/installation
5. Electron 官方文档 · Application Debugging(openDevTools): https://www.electronjs.org/docs/latest/tutorial/application-debugging
6. Electron 官方文档 · Debugging the Main Process(--inspect / --inspect-brk,默认端口 9229): https://www.electronjs.org/docs/latest/tutorial/debugging-main-process
7. Electron 官方文档 · Debugging in VSCode(launch.json 主进程配置): https://www.electronjs.org/docs/latest/tutorial/debugging-vscode
8. Electron 官方文档 · Menu(默认菜单包含 View 菜单): https://www.electronjs.org/docs/latest/api/menu
9. Electron 官方发布数据 releases.json(44.5.1 = Chromium 152.0.7977.130 / Node 24.21.0,2026-09-29): https://releases.electronjs.org/releases.json
10. Node.js 官方 dist index(最新 LTS v24.21.0 "Krypton"): https://nodejs.org/dist/index.json
11. Electron Forge 官网 · Getting Started(create-electron-app、模板、node_modules 落盘要求): https://www.electronforge.io/
12. electron-vite 官方指南(脚手架、dev/build/preview、main 指向 out/main/index.js、Node 20.19+/22.12+): https://electron-vite.org/guide/
13. npm 官方文档 · package.json(main 字段默认 index.js): https://docs.npmjs.com/cli/v10/configuring-npm/package-json
14. npm 官方文档 · scripts(node_modules/.bin 加入 PATH): https://docs.npmjs.com/cli/v10/using-npm/scripts
15. npmmirror Electron 二进制镜像(官方 installation.md 引用的国内 CDN,2026-10-04 实测可用): https://npmmirror.com/mirrors/electron/