《Electron 45.2.3 内核解剖》第 1 章 全景:一个被缝合的浏览器
本章目标:在脑子里建立一张 Electron 的结构地图。 读完你应该能回答:Electron 由哪几个来源拼成?缝合线具体在哪些文件里?为什么它既不是"浏览器加个 Node",也不是"Node 加个浏览器"?当一个 API 行为异常时,你应该去哪个目录找答案?
1.1 从一个真实故障说起
先看一段几乎每个 Electron 开发者都遇到过的代码。
// main.js
const { app, BrowserWindow } = require('electron')
app.whenReady().then(() => {
const win = new BrowserWindow({
width: 1000,
height: 700,
webPreferences: {
nodeIntegration: true,
contextIsolation: false
}
})
win.loadFile('index.html')
})
desktop-capturer.md:72-76
<!-- index.html -->
<script>
const fs = require('fs')
console.log(fs.readdirSync('.'))
</script>
这段代码在十年前是官方推荐写法,今天跑起来会在控制台打印一句警告,然后正常工作。但如果你把 nodeIntegration 改成 false、contextIsolation 保持 false,require 就变成了 undefined,页面直接抛 ReferenceError。再换成 contextIsolation: true,同样是 undefined,但错误信息、出现时机、甚至 process 对象是否存在,全都变了。
三个布尔开关,四种组合,四种截然不同的运行时行为。这就是 Electron 的典型特征:它的复杂度不在 API 表面,而在 API 下面那张由进程、上下文、绑定层、隔离世界织成的网。
要理解这张网,必须先知道它是怎么被织出来的。
而这个"织"的过程,留下了大量可以被直接观察的痕迹。你不需要读源码才能看见它们——只要打开一台机器上的 Electron 应用,观察它的进程树、文件布局、加载的脚本,就能反推出架构。
我们先做一次这样的观察,再进入源码。
1.1.1 观察一:进程树
启动一个 Electron 应用,然后在终端里看进程:
# Linux / macOS
ps -ef | grep -i yourapp | grep -v grep
你会看到类似这样的东西(Windows 上用 Process Explorer 或 wmic process get 得到等价结果):
user 1024 1 yourapp ← 主进程(browser)
user 1031 1024 yourapp --type=gpu-process ... ← GPU 进程
user 1032 1024 yourapp --type=utility --utility-sub-type=network.mojom.NetworkService ...
user 1040 1024 yourapp --type=renderer --enable-sandbox ...
user 1041 1024 yourapp --type=renderer ...
五类东西,四个进程,一条从主进程分叉出去的树。
关键在后面的参数。Electron 的进程类型不是靠可执行文件名区分的,而是靠 --type 命令行开关。 这一点非常重要:当主进程 fork 出一个子进程时,它把 --type=renderer 写进子进程的命令行,子进程启动后读这个开关,决定自己该走哪条初始化路径。
这个"一条命令线决定进程身份"的设计,直接来自 Chromium。想验证的话,打开任何一份 Electron 的崩溃日志,第一行就是完整命令行。
1.1.2 观察二:用户目录里的文件
再看数据目录(app.getPath('userData') 指向的地方)。一个跑过一段时间的应用,里面的结构大致是:
~/.config/YourApp/
├── Cache/ ← HTTP 缓存
├── Code Cache/ ← V8 编译缓存(重要)
├── GPUCache/
├── Local Storage/
├── Session Storage/
├── Network/
│ └── Cookies ← SQLite
├── Preferences ← JSON,Chromium 的偏好存储
└── SingletonLock ← 单实例锁
这是一份 Chromium 的用户资料目录。Electron 没有重写它,而是原样继承了 Chromium 的存储模型。所以你会看到 Preferences、Cookies、Network/ 这些名字——它们来自 Chrome。
Code Cache 目录尤其值得注意:Electron 把 lib/ 打包成的 JS bundle 编译成字节码后缓存到这里(构建期还可以预生成,见第 8 章)。理解这一点,你就明白为什么"第一次启动慢、第二次启动快"。
1.1.3 观察三:process.versions
在主进程里打印:
console.log(process.versions)
输出(Electron 45.2.3 环境):
{
node: '24.22.2',
chrome: '156.0.8078.80',
electron: '45.2.3',
v8: '15.6.xxx-electron.0', // 版本号带后缀
...
}
三件事同时出现在一个对象里:Node 的版本、Chromium 的版本、Electron 自己的版本。这个 versions 对象本身就是一份架构声明——这个进程同时是 Node 进程和 Chromium 进程。
v8 那一行的 -electron.0 后缀尤其说明问题。它来自构建参数:
all.gn:17
# build/args/all.gn
v8_embedder_string = "-electron.0"
Electron 修改了 V8 的源码(36 个补丁),所以它必须给 V8 打个标记,避免和上游 V8 混淆。
1.1.4 观察四:require('electron') 找到了什么
console.log(require.resolve('electron'))
// /path/to/app/node_modules/electron/index.js
打开这个文件(这是 npm 包 electron 的入口):
// node_modules/electron/index.js(简化)
const fs = require('fs')
const path = require('path')
const pathFile = path.join(__dirname, 'path.txt')
function getElectronPath () {
let executablePath
if (fs.existsSync(pathFile)) {
executablePath = fs.readFileSync(pathFile, 'utf-8')
}
if (process.env.ELECTRON_OVERRIDE_DIST_PATH) {
return path.join(process.env.ELECTRON_OVERRIDE_DIST_PATH, executablePath || 'electron')
}
if (executablePath) {
return path.join(__dirname, 'dist', executablePath)
} else {
throw new Error('Electron failed to install correctly...')
}
}
module.exports = getElectronPath()
require('electron') 在 Node 里返回的是一个字符串——可执行文件的路径。
但在 Electron 主进程里,同样的 require('electron') 返回的是 { app, BrowserWindow, ipcMain, ... } 这个巨大的 API 对象。
同一个模块名,两种完全不同的解析结果。为什么?
因为 Electron 在启动时劫持了 Module._load。对于 'electron' 这个特殊的模块 ID,它不查 node_modules,而是返回内置的模块表。这个机制在第 8 章详细拆解,这里只需要记住结论:electron 模块是"虚拟"的,它的实际内容编译在可执行文件里。
1.1.5 观察的意义
四个观察,四个结论:
| 观察 | 结论 |
|---|---|
进程树与 --type | Electron 用 Chromium 的多进程模型,进程身份由命令行决定 |
| 用户目录结构 | 存储层完全继承 Chromium,没有另起炉灶 |
process.versions | 一个进程里同时存在两套运行时 |
require('electron') 的双重语义 | JS 模块系统被改写,内置模块不在磁盘上 |
这四个结论合起来,就是本章要展开的全部内容。
1.2 三个仓库,一次缝合
Electron 不是从零写的一个浏览器。它做的事,用一句话概括:
把 Chromium 的 content 层当作一个可嵌入的浏览器内核,把 Node.js 当作一个可嵌入的 JavaScript 运行时,然后写一层胶水,让这两者在同一个进程里共存、在多个进程间通信。
这句话里的每一个词都需要展开,因为"嵌入"和"共存"在 C++ 层面意味着完全不同的工作量。
1.2.1 三个来源
看仓库根目录的 DEPS 文件。这是 Chromium 生态的依赖描述文件,gclient 用它来拉取代码:
DEPS:3-10
DEPS:3-10
DEPS:3-10
DEPS:3-10
# DEPS(节选)
vars = {
'chromium_version':
'156.0.8078.80',
'node_version':
'v24.22.2',
'nan_version':
'675cefebca42410733da8a454c8d9391fcebfbc2',
'squirrel.mac_version':
'fffea30e4a339a7f7d69a3391314b72548d209bd',
...
}
deps = {
'src': Var('chromium_git') + '/chromium/src.git@' + Var('chromium_version'),
'src/third_party/electron_node':
Var('nodejs_git') + '/node.git@' + Var('node_version'),
...
}
这段配置揭示了一个关键事实:在磁盘上,Electron 仓库是 Chromium 仓库的一个子目录。
真实布局是这样的(CLAUDE.md 里也有说明):
src/ ← Chromium 的 src,约 3000 万行
├── base/ Chromium 基础设施(TaskRunner、Callback、FilePath…)
├── content/ ← 浏览器内核的"可嵌入"部分
├── net/ 网络栈
├── ui/ 跨平台 UI 抽象(views、gfx、aura)
├── gpu/ media/ printing/
├── third_party/
│ ├── electron_node/ ← Node.js 源码,被放在这里
│ ├── blink/ 渲染引擎
│ ├── v8/ JS 引擎
│ └── ...
└── electron/ ← 本仓库,你的工作目录
├── shell/ C++ 胶水层
├── lib/ TypeScript 胶水层
├── patches/ 对上面所有东西的修改
├── build/ GN 构建模板
├── spec/ 测试
└── ...
所以"Electron 项目"实际上是三层的叠加:
┌──────────────────────────────────────────────────────────┐
│ electron/shell + electron/lib 约 18 万行(自有) │
├──────────────────────────────────────────────────────────┤
│ src/content + src/base + src/net ... Chromium 内核 │
├──────────────────────────────────────────────────────────┤
│ src/third_party/electron_node Node.js 运行时 │
├──────────────────────────────────────────────────────────┤
│ src/v8 + src/third_party/blink JS 引擎与渲染 │
└──────────────────────────────────────────────────────────┘
注意一个容易被忽略的细节:Node.js 不是作为外部依赖链接进来的,而是作为 Chromium 的一个 third_party 目录编译的。
这个决定影响深远。它意味着:
- Node 的构建配置被改写成了 GN(Chromium 的构建系统),不再是 Node 自己的
configure.py+ gyp; - Node 的 V8 被替换成了 Chromium 的 V8,而不是 Node 自带的 V8 副本;
- Node 的 OpenSSL 被替换成了 Chromium 的 BoringSSL;
- 因此 Node 源码必须打补丁才能在这套环境下编译通过。
这三条在 all.gn:5-10 里都有明确体现:
# build/args/all.gn
# Registry of NMVs --> https://github.com/nodejs/node/blob/main/doc/abi_version_registry.json
node_module_version = 150
# Build Node.js against Chromium's BoringSSL instead of node's bundled OpenSSL.
node_openssl_path = "//third_party/boringssl"
# Build Node.js against Chromium's V8 instead of node's bundled copy.
node_v8_path = "//v8"
# Electron owns V8 platform initialization, so Node.js must not set up its own.
node_use_v8_platform = false
v8_promise_internal_field_count = 1
v8_embedder_string = "-electron.0"
逐行解读这五组参数,你会看到整个架构的轮廓。
node_module_version = 150
原生模块 ABI 版本。Node 官方 v24 的 NMV 是 137,Electron 45 是 150。为什么不一样?
因为 Electron 改了 V8 的 ABI。最直观的一个改动就在下面几行:v8_promise_internal_field_count = 1。
这个参数改变的是 v8::Promise 对象的内部字段数量。V8 的 Promise 内部有两个"内嵌字段"槽,供嵌入者存放私有数据。Node 需要用它存一些东西,Electron 也需要(gin_helper::Promise 就依赖它)。默认值 2 是给 Chrome 留的,Electron 改成 1,意味着重新划分了槽位。
只要 v8::Promise 的内存布局变了,所有编译期依赖这个布局的原生模块就都失效了。 这就是 NMV 必须改的原因。
任何 ABI 变化都必须换一个 NMV,否则用官方 Node 头文件编译出来的 .node 文件会被错误地加载,然后崩溃——而且是那种"函数指针指错位置"的崩溃,堆栈完全不可读。
这是"为什么我的原生模块要重新编译"这个经典问题的根源。node-gyp 会读取目标 Electron 的头文件(通过 node_headers 目标生成,见第 3 章),用正确的 ABI 重新编译。
node_openssl_path = "//third_party/boringssl"
Node 的 crypto 模块本来链接 OpenSSL。Chromium 用的是 BoringSSL(Google 从 OpenSSL 分叉并大幅裁剪的版本,API 有差异)。
如果不改,一个进程里会有两套 TLS 实现、两套证书验证逻辑、两份根证书,内存翻倍且行为不一致——更糟的是符号冲突,链接阶段就会炸。
所以 Electron 强制 Node 用 BoringSSL。代价是必须给 Node 打一系列兼容补丁:
patches/node/fix_handle_boringssl_and_openssl_incompatibilities.patch
这个补丁做的事情包括:把 OPENSSL_VERSION_NUMBER 的判断改掉、替换掉 BoringSSL 不提供的 API(比如某些 X509_* 函数)、处理 ERR_* 错误码的差异。
node_v8_path = "//v8"
同理,一个进程里不能有两个 V8。
但这条比 BoringSSL 那条难得多,因为 Node 深度依赖 V8 的许多内部 API(v8::internal::*),而 Chromium 的 V8 构建配置和 Node 期望的不一样——有些功能被关掉了(为了体积),有些调试接口没编进去。
patches/v8/ 下的 36 个补丁,很大一部分就是在把 Node 需要、但 Chromium 没启用的 V8 能力打开。举几个例子:
patches/v8/build_gn.patch 构建配置对齐
patches/v8/deps_optional_wasm.patch wasm 依赖处理
patches/v8/expose_mksnapshot.patch 暴露快照生成工具
patches/v8/trap-handler.patch WebAssembly 陷阱处理
node_use_v8_platform = false
这条最关键,值得单独深入。
V8 需要一个"平台"对象(v8::Platform)来管理线程池、任务队列、垃圾回收调度。它是个抽象接口,嵌入者必须提供实现。
Node 默认自己创建平台(node::MultiIsolatePlatform),Chromium 也自己创建平台。如果两者都创建,同一个 Isolate 就会被两个平台驱动,任务队列冲突,随机崩溃。
所以 Electron 规定:平台由 Electron 自己持有,Node 不许创建。
这条规则的代码体现,就在 node_bindings.cc:723-726 里:
node_bindings.cc:718-721
uint64_t process_flags =
node::ProcessInitializationFlags::kNoInitializeCppgc |
node::ProcessInitializationFlags::kNoInitializeV8 |
node::ProcessInitializationFlags::kNoInitializeNodeV8Platform;
三个 kNoInitialize* 标志,意思是"Node 你别初始化这些东西,我自己来"。
这是 Electron 与 Node 关系的缩影:Node 被当作一个"半成品运行时"嵌入,它的初始化流程被切碎,由 Electron 按自己的顺序重新编排。
而 Electron 的平台从哪来?来自 JavascriptEnvironment:
javascript_environment.h:33-40
// shell/browser/javascript_environment.h:29-60(结构)
class JavascriptEnvironment {
public:
explicit JavascriptEnvironment(
uv_loop_t* event_loop,
bool setup_wasm_streaming = false,
v8::TracingController* tracing_controller = nullptr);
~JavascriptEnvironment();
void CreateMicrotasksRunner();
void DestroyMicrotasksRunner();
node::MultiIsolatePlatform* platform() const { return platform_.get(); }
[[nodiscard]] v8::Isolate* isolate() const;
[[nodiscard]] static v8::Isolate* GetIsolate();
private:
v8::Isolate* Initialize(uv_loop_t* event_loop,
bool setup_wasm_streaming,
v8::TracingController* tracing_controller);
std::unique_ptr<node::MultiIsolatePlatform> platform_;
std::unique_ptr<gin::IsolateHolder> isolate_holder_;
std::optional<v8::Locker> locker_;
std::unique_ptr<MicrotasksRunner> microtasks_runner_;
};
注意 platform_ 是 node::MultiIsolatePlatform 类型——Electron 用的是 Node 提供的平台实现,但由 Electron 来控制创建时机和所有权。
这是一个精妙的折中:沿用 Node 的平台类(省得自己实现一堆 V8 接口),但把生命周期拿在自己手里。
v8_embedder_string = "-electron.0"
在 process.versions.v8 里加上 -electron.0 后缀。这个改动看似无害,实际上还有一层作用:V8 用它来给代码缓存(code cache)加盐。不同 embedder string 的 V8 不会复用彼此的字节码缓存,避免"用错误版本的字节码执行"这类极难排查的问题。
1.2.2 缝合的三个层次
把上面这些拼起来,Electron 的缝合工作可以分成三个层次,每一层解决一类问题:
┌─────────────────────────────────────────────────────────────┐
│ 第三层:API 层(lib/*.ts) │
│ 把 C++ 绑定包装成符合 Node 习惯的 JS API │
│ 例:lib/browser/api/web-contents.ts 里给 C++ 类加 JS 方法 │
├─────────────────────────────────────────────────────────────┤
│ 第二层:绑定层(shell/common/gin_helper) │
│ 把 C++ 对象暴露为 v8::Object,把 v8::Value 转成 C++ 类型 │
│ 例:gin_helper::Wrappable、EventEmitterMixin、gin_converters │
├─────────────────────────────────────────────────────────────┤
│ 第一层:运行时层(shell/common/node_bindings.cc 等) │
│ 让 V8 Isolate、libuv loop、Chromium message loop 共存 │
│ 例:NodeBindings 的单例、EmbedThread、UvRunOnce │
└─────────────────────────────────────────────────────────────┘
这三层分别对应书中的第 7、6、5 章。本章只给轮廓。
值得强调的是:这三层是严格单向依赖的。
- 第三层(TS)可以调用第二层(C++ 绑定),反之不行;
- 第二层可以调用第一层(运行时),反之不行;
- 第一层完全不知道第三层存在。
这个约束在代码里体现为目录依赖:lib/ 引用 shell/ 暴露的 binding 名(字符串),但 shell/ 里没有任何一行代码知道 lib/ 的存在。
唯一的例外是 electron_api_v8_util.cc:160 里的 getHiddenValue / setHiddenValue——它让 C++ 能往 JS 对象上挂"隐藏属性",从而把 appPackage 这类数据从 C++ 传给 JS 启动脚本。这是一个刻意留下的、受控的反向通道。
// lib/browser/init.ts
const appPackage = process
._linkedBinding('electron_common_v8_util')
.getHiddenValue(global, 'appPackage');
C++ 侧把找到的应用包信息(路径、main 入口、是否 ESM、v8Flags)挂在 global 的隐藏属性上,JS 启动脚本再取出来。这是"单向依赖"原则下的权宜之计,也是理解启动流程的关键一环(第 5 章详述)。
1.3 目录即架构:shell/ 的六个子目录
打开 shell/,会看到六个子目录。这不是随意划分的,它们精确对应 Chromium 的进程模型。
shell/
├── app/ 进程入口。每个平台一份 main 函数,最终汇聚到 ElectronMainDelegate
├── browser/ 浏览器进程(主进程)的实现,61 个 API 模块
├── renderer/ 渲染进程的实现
├── common/ 所有进程共享的代码(绑定层在这里)
├── utility/ 工具进程的实现
├── services/ Node.js 服务集成
└── app_shim/ macOS 特有的应用外壳通信
1.3.1 shell/app/:入口
这里有三个平台的入口文件:
electron_main_win.cc(Windows)electron_main_linux.cc(Linux)electron_main_mac.cc(macOS)
它们做的事都很少:解析命令行、处理平台差异(比如 Windows 的控制台编码、macOS 的 bundle 路径)、然后调用 ElectronMainDelegate。
为什么入口这么薄?因为 Chromium 已经把"跨平台启动"这件事做完了。content::ContentMain() 负责创建线程、初始化 ICU、设置崩溃处理器、启动 message loop。Electron 只需要提供"策略"。
真正的初始化逻辑在 electron_main_delegate.cc 里。它实现了 content::ContentMainDelegate 接口。这个接口是 Chromium 给"嵌入者"准备的第一道门:
electron_main_delegate.h:24-31
// shell/app/electron_main_delegate.h(结构示意)
class ElectronMainDelegate : public content::ContentMainDelegate {
public:
std::optional<int> BasicStartupComplete() override;
void PreSandboxStartup() override;
content::ContentBrowserClient* CreateContentBrowserClient() override;
content::ContentRendererClient* CreateContentRendererClient() override;
content::ContentUtilityClient* CreateContentUtilityClient() override;
content::ContentGpuClient* CreateContentGpuClient() override;
};
看懂这个接口,就理解了 Chromium 的嵌入模型:content 层是一个"没有 UI 的浏览器",它把"浏览器该有的行为"抽象成一组 Client 接口,嵌入者提供实现。Chrome 提供一份实现(chrome/browser/),Electron 提供另一份(shell/browser/)。
所以 electron_browser_client.cc 这个文件,本质上是"Electron 版的 Chrome 浏览器进程策略"。它的类声明能说明这一点:
electron_browser_client.h:50-51
class ElectronBrowserClient : public content::ContentBrowserClient,
private content::RenderProcessHostObserver {
ContentBrowserClient 有上百个虚函数,覆盖:进程创建、导航拦截、权限决策、网络请求、下载、证书、媒体设备、剪贴板、字体……每一个虚函数都是一次"Chromium 问嵌入者:这件事你想怎么做?"
Electron 的答案是:大部分交给默认实现,少数关键点改写,然后把一部分决策转发给 JavaScript。
最后这半句是 Electron 的灵魂。比如权限请求:当页面调用 navigator.geolocation.getCurrentPosition(),Chromium 会通过 ContentBrowserClient 问嵌入者"准不准",Electron 的实现在 electron_permission_manager.cc 里,它会先看 JS 有没有通过 session.setPermissionRequestHandler() 注册处理器,有就转发过去等回调,没有就按默认策略走。
这就是为什么 setPermissionRequestHandler 能生效——它在 C++ 的决策点上插了一个钩子。
1.3.2 shell/browser/:主进程的全部
这是最大的目录,61 个 electron_api_*.cc 文件对应 61 个原生 API 类。按功能可以分成几组:
窗口与视图: electron_api_base_window.cc / electron_api_browser_window.cc
electron_api_web_contents.cc / electron_api_web_contents_view.cc
electron_api_view.cc / electron_api_image_view.cc
应用与进程: electron_api_app.cc / electron_api_utility_process.cc
electron_api_service_worker_main.cc
网络: electron_api_session.cc / electron_api_cookies.cc
electron_api_net_log.cc / electron_api_web_request.cc
electron_api_protocol.cc / electron_api_web_socket.cc
系统集成: electron_api_menu.cc / electron_api_tray.cc / electron_api_dialog.cc
electron_api_notification.cc / electron_api_global_shortcut.cc
electron_api_clipboard.cc / electron_api_screen.cc
electron_api_power_monitor.cc / electron_api_native_theme.cc
媒体与图形: electron_api_desktop_capturer.cc / electron_api_shared_texture.cc
electron_api_content_tracing.cc
调试与诊断: electron_api_debugger.cc / electron_api_crash_reporter.cc
除了 API,还有一批"非 API"的核心文件,它们才是真正的骨架:
| 文件 | 职责 |
|---|---|
browser.cc / browser.h | app 模块的 C++ 后端,管理应用生命周期 |
electron_browser_main_parts.cc | 主进程初始化的总调度 |
electron_browser_client.cc | 上面说的"Electron 版 Chrome 策略" |
electron_browser_context.cc | 浏览器上下文,对应 JS 的 session |
native_window.h / native_window_views.cc / native_window_mac.mm | 跨平台窗口抽象 |
window_list.cc | 全局窗口列表,window-all-closed 事件的数据源 |
javascript_environment.cc | V8 Isolate 的创建与销毁 |
api/electron_api_web_contents.cc | 6184 行,整个仓库最大的单文件 |
electron_api_web_contents.cc 的 6184 行值得单独说一句:它继承自 12 个基类:
electron_api_web_contents.h:129-141
class WebContents final : public ExclusiveAccessContext,
public gin_helper::DeprecatedWrappable<WebContents>,
public gin_helper::EventEmitterMixin<WebContents>,
public gin_helper::Constructible<WebContents>,
public gin_helper::Pinnable<WebContents>,
public gin_helper::CleanedUpAtExit,
public content::WebContentsObserver,
public content::WebContentsDelegate,
private content::RenderWidgetHost::InputEventObserver,
public content::JavaScriptDialogManager,
public InspectableWebContentsDelegate,
public InspectableWebContentsViewDelegate,
public BackgroundThrottlingSource {
这 12 个基类精确地说明了 webContents 在 Electron 里的角色:
Wrappable—— 它是 JS 对象的包装;EventEmitterMixin—— 它能发事件(did-finish-load之类);Constructible—— 它能被new;Pinnable—— 它可以被 JS 侧"钉住"防止被 GC;CleanedUpAtExit—— 它参与退出清理;WebContentsObserver—— 它观察 content 层的事件;WebContentsDelegate—— 它是 content 层的委托(处理OpenURLFromTab、AddNewContents之类);InputEventObserver—— 它观察输入事件;JavaScriptDialogManager—— 它处理alert/confirm/prompt;InspectableWebContentsDelegate—— 它管理 DevTools;BackgroundThrottlingSource—— 它提供后台限流策略。
这就是"胶水类"的典型形态:一个对象同时站在两套系统的边界上,把两边的事件互相翻译。
它既是"Electron 的 webContents",又是"Chromium 的 WebContents 的宿主"。当你 win.webContents.send('x') 时,调用的是前者的方法;当 Chromium 想弹一个 JS 对话框时,调用的是后者的虚函数——但两者是同一个 C++ 对象。
理解了这一点,你就理解了 Electron 一半的设计。
1.3.3 shell/renderer/:渲染进程
渲染进程的代码量小得多,因为大部分渲染工作 Blink 已经做了。Electron 在这里只做三件事:
- 实现
ContentRendererClient(renderer_client_base.cc),在渲染进程启动时介入,决定加载哪些脚本、创建哪些上下文; - 加载 preload 脚本(
preload_environment.cc、preload_realm_context.cc); - 实现沙箱版本(
electron_sandboxed_renderer_client.cc),沙箱进程里没有 Node,需要另一套加载逻辑。
这个目录里有一个文件很能说明问题:window_setup.cc。它负责在页面脚本执行前,往 window 对象上挂 Electron 特有的属性。如果你好奇 window.process 是怎么来的,答案就在这类文件里,而不是在什么"初始化脚本"里。
1.3.4 shell/common/:绑定层
这是本书第二部分的主战场。核心是 gin_helper/ 目录:
shell/common/gin_helper/
├── wrappable.h C++ 对象 ⇄ v8::Object 的桥
├── event_emitter.h 事件发射(就是 Node 的 EventEmitter 协议)
├── constructible.h 让 C++ 类可以被 new
├── dictionary.h C++ 侧的"options 对象"读取器
├── promise.h C++ 侧创建/解决 Promise
├── object_template_builder.h 用链式 API 定义 JS 类的原型
├── callback.h 把 v8::Function 包成 C++ 回调
├── trackable_object.h 带 ID 的对象注册表
├── microtasks_runner.h 微任务泵(与 Chromium 的 microtask 机制对接)
├── error_thrower.h 统一的异常抛出接口
└── ...
gin_helper 这个名字里,gin 是 Chromium 的一个库——官方定义是 "A lightweight bindings library"(一个轻量绑定库)。它提供 Wrappable、Converter、Arguments 等基础设施,用于把 C++ 对象暴露给 V8。
Electron 在 gin 之上又包了一层 gin_helper,原因是 gin 的设计目标是"够用就好",而 Electron 需要:
- 事件发射(gin 不管事件)
- Promise(gin 有,但行为不完全符合 Node 习惯)
new语义(gin 的Wrappable不支持new,gin_helper::Constructible补上)- 生命周期钩子(
CleanedUpAtExit) - 微任务泵(Node 和 Chromium 各有各的微任务队列,需要桥接)
所以你会看到 gin_helper::Wrappable<T> 继承自 gin::Wrappable<T>,然后加上一堆能力。这是"适配层"的典型做法:不修改上游,在上游之上叠加。
1.3.5 shell/utility/ 与 shell/services/
utility/ 只有一个 electron_content_utility_client.cc 加上 ai/ 和 api/ 两个子目录。它实现 ContentUtilityClient,对应 JS 的 utilityProcess.fork()。
services/node/ 提供 mojom 接口定义,让 Node.js 能作为 Chromium 的一个 "service" 被访问。这块比较新,是 Electron 近年架构调整的一部分——把 Node 的能力暴露成 Chromium 的 mojo 服务,从而在沙箱进程里也能有限地访问 Node 功能。
1.4 lib/ 的分层:TypeScript 的三六九等
lib/ 只有 94 个文件、1 万行,但它的目录结构同样精确对应进程模型:
lib/
├── browser/ 主进程的 JS 实现(对应 shell/browser)
│ ├── api/ 47 个 API 模块的 TS 包装
│ ├── init.ts 主进程的启动脚本
│ ├── ipc-dispatch.ts IPC 消息分发
│ └── rpc-server.ts 远程对象协议(给 webview/guest 用)
├── renderer/ 渲染进程的 JS 实现
│ ├── api/ ipcRenderer、webFrame、contextBridge
│ ├── init.ts Node 集成模式下的渲染进程启动脚本
│ └── common-init.ts
├── isolated_renderer/ 隔离世界里的 preload 执行环境
├── webview/ webview 标签的实现
├── worker/ Web Worker 里的支持
├── utility/ utility process 的 JS 侧
├── node/ ELECTRON_RUN_AS_NODE 模式
└── common/ 所有环境共享
注意 lib/browser/api/module-list.ts:4-10 这个文件——它是 require('electron') 的真相:
// lib/browser/api/module-list.ts(节选)
export const browserModuleList: ElectronInternal.ModuleEntry[] = [
{ name: 'app', loader: () => require('./app') },
{ name: 'autoUpdater', loader: () => require('./auto-updater') },
{ name: 'BaseWindow', loader: () => require('./base-window') },
{ name: 'BrowserWindow', loader: () => require('./browser-window') },
...
{ name: 'crashReporter', loader: () => process._linkedBinding('electron_browser_crash_reporter') },
{ name: 'ImageView', loader: () => process._linkedBinding('electron_browser_image_view').ImageView },
...
];
两种 loader,对应两种 API 形态:
require('./app')—— 有 TS 实现,C++ 只是后端;process._linkedBinding(...)—— 直接就是 C++ 对象,没有 TS 包装。
这解释了为什么有些 API 在 JS 里"改不动"(比如 Notification),有些可以打补丁(比如 app)。
process._linkedBinding 这个函数是 Node 提供的内部 API,用于加载"链接进二进制的原生模块"。Electron 用它在 JS 里拿到 C++ 对象。它的注册机制在第 8 章讲。
顺便说一个工程细节:这个文件顶部有一行注释
// TODO: Updating this file also required updating the module-keys file
意思是改了这里,还要改另一个地方(lib/browser/api/exports/electron.ts 的类型声明)。这是常见的"手工同步"点,也是新手提 PR 常踩的坑。
1.5 启动时到底加载了什么:js2c 与七个 bundle
这是 Electron 架构里最容易被忽略、但理解之后最有"原来如此"感的一环。
问题:lib/ 下的 TypeScript 最终要跑到 V8 里,但 Electron 不是从磁盘加载这些文件的(用户装的应用里根本没有 lib/ 目录)。它们去哪了?
答案:编译进二进制。
构建时,lib/ 被 rolldown 打包成 7 个 JS bundle,然后由 js2c.py(JavaScript to C)转换成 C++ 源文件,内联为字符串常量,最终编进可执行文件。
BUILD.gn:283-290 里的 electron_js2c 目标定义了这个过程:
BUILD.gn:283-306
action("electron_js2c") {
deps = [
":electron_browser_bundle",
":electron_isolated_renderer_bundle",
":electron_node_bundle",
":electron_renderer_bundle",
":electron_utility_bundle",
":electron_webview_bundle",
":electron_worker_bundle",
"//third_party/electron_node:node_js2c($electron_js2c_toolchain)",
]
sources = [
"$root_gen_dir/internal/electron/js2c/browser_init.js",
"$root_gen_dir/internal/electron/js2c/isolated_bundle.js",
"$root_gen_dir/internal/electron/js2c/node_init.js",
"$root_gen_dir/internal/electron/js2c/renderer_init.js",
"$root_gen_dir/internal/electron/js2c/utility_init.js",
"$root_gen_dir/internal/electron/js2c/webview_bundle.js",
"$root_gen_dir/internal/electron/js2c/worker_init.js",
]
outputs = [ "$root_gen_dir/electron_natives.cc" ]
script = "build/js2c.py"
}
七个 bundle,对应七种执行环境:
| bundle | 输出变量名 | 在哪个环境执行 |
|---|---|---|
browser_init.js | electron/js2c/browser_init | 主进程 |
renderer_init.js | electron/js2c/renderer_init | 渲染进程(Node 集成模式) |
worker_init.js | electron/js2c/worker_init | Web Worker |
utility_init.js | electron/js2c/utility_init | utility process |
isolated_bundle.js | electron/js2c/isolated_bundle | 隔离世界的 preload |
webview_bundle.js | electron/js2c/webview_bundle | webview 的 guest 页面 |
node_init.js | electron/js2c/node_init | ELECTRON_RUN_AS_NODE 模式 |
这张表回答了本章开头的疑问之一:为什么 nodeIntegration 关掉之后 require 就没了?
因为 require 是 renderer_init.js 里装上去的。看 lib/renderer/init.ts:58-63:
// lib/renderer/init.ts(节选)
const nodeIntegration = mainFrame.getWebPreference('nodeIntegration');
...
if (nodeIntegration) {
// Export node bindings to global.
const { makeRequireFunction } =
require('internal/modules/helpers') as typeof import('@node/lib/internal/modules/helpers');
global.module = new Module('internal/electron/js2c/renderer_init');
global.require = makeRequireFunction(global.module) as NodeRequire;
...
}
global.require 只在这个 if 里被赋值。 条件不满足,它就永远不存在。这不是"被删掉了",是"从来没被创建过"。
而且注意这个细节:
lib/renderer/init.ts:125-132
// lib/renderer/init.ts:末尾
const shouldDeleteRendererNodeGlobals = !nodeIntegration && !process.contextIsolated;
const onPreloadsLoaded = () => {
if (shouldDeleteRendererNodeGlobals) {
delete (global as any).process;
delete (global as any).Buffer;
delete (global as any).setImmediate;
delete (global as any).clearImmediate;
delete (global as any).global;
delete (global as any).root;
delete (global as any).GLOBAL;
}
appCodeLoaded!();
};
在"无 Node 集成 + 无上下文隔离"这个组合下,Electron 会先把 process、Buffer 等挂上去(让 preload 能用),等 preload 执行完,再显式删除它们,防止页面脚本拿到。
这段代码解释了一个长期困扰开发者的问题:为什么 preload 里能用 process,页面里不能? 因为它们是先装后删,中间隔着 preload 的执行窗口。
顺便说,这个"先装后删"的窗口期曾经是一个 bug 源:如果 preload 是异步的(ESM preload),删除时机可能早于 preload 执行完毕,导致 preload 里拿不到 process。源码注释里明确提到了这个问题(issue #46142),解决方法是把删除延后到 onPreloadsLoaded 回调里。
这类"注释里写着 issue 号"的代码,是理解 Electron 历史包袱的最好入口。
1.5.1 bundle 里到底有什么
targets.mjs 定义每个 bundle 的入口。虽然我不逐行展开,但可以给出结构性的说明:
browser_init.js
← lib/browser/init.ts
├─ lib/common/init.ts 通用初始化
├─ lib/browser/ipc-dispatch.ts IPC 分发器
├─ lib/browser/rpc-server.ts 远程对象协议
├─ lib/browser/guest-view-manager.ts
└─ lib/browser/api/*.ts 47 个 API 模块(按需加载)
renderer_init.js
← lib/renderer/init.ts
├─ lib/common/init.ts
├─ lib/renderer/common-init.ts
└─ lib/renderer/api/*.ts
注意 browser_init.js 里 API 模块是"按需加载"的——module-list.ts 里的 loader 是函数,只有第一次访问 require('electron').app 时才执行。这个设计让主进程启动时不必加载全部 47 个模块,节省几十毫秒。
1.6 一次 new BrowserWindow() 的完整旅程
理论讲够了,走一遍实际的。这段代码发生了什么:
const win = new BrowserWindow({ width: 800, height: 600 })
一次调用,九个阶段,跨三个进程。
阶段 1:JS 构造函数
BrowserWindow 的 JS 类在 browser-window.ts 定义。它继承自 BaseWindow,构造函数里做三件事:
// lib/browser/api/browser-window.ts(结构示意)
class BrowserWindow extends BaseWindow {
constructor(options: BrowserWindowConstructorOptions = {}) {
// 1. 规范化 webPreferences:合并默认值、处理 nodeIntegration 与
// contextIsolation 的依赖关系、解析 preload 路径
const webPreferences = makeWebPreferences(options)
// 2. 调用 C++ 的 Super 构造(实际创建原生窗口)
super({ ...options, webPreferences })
// 3. 创建 WebContentsView 并加入窗口
this.contentView = new WebContentsView({ webPreferences })
this.contentView.setBounds({ x: 0, y: 0, width, height })
this.contentView.setBackgroundColor(...)
}
}
第一处的 makeWebPreferences 是个容易被忽视的关键函数。它处理了一堆"参数联动",比如:
contextIsolation默认true(Electron 12 之后);nodeIntegration默认false;- 如果设了
preload,转成绝对路径; sandbox的默认值取决于nodeIntegration。
这就是为什么文档里说"某些选项互相影响"——联动逻辑写在这个函数里,不在 C++ 里。
阶段 2:进入 C++ 绑定
super(options) 触发 V8 的 new,落到 C++ 的 BaseWindow::New。
BaseWindow 通过 gin_helper::Constructible 暴露构造函数。new 的时候,V8 调用到 C++ 的静态 New 方法,它做四件事:
- 从
options里读出窗口参数——gin_helper::Dictionary负责把v8::Object转成可读的键值表; - 调用
NativeWindow::Create(...); - 把创建好的
NativeWindow*包进BaseWindow对象; - 设置 JS 原型(让
instanceof BrowserWindow成立)。
第 4 步依赖 gin_helper::ObjectTemplateBuilder——它用链式 API 把 C++ 成员函数注册成 JS 方法:
// 伪代码,表达注册模式
ObjectTemplateBuilder(isolate)
.SetMethod("setTitle", &BaseWindow::SetTitle)
.SetMethod("getBounds", &BaseWindow::GetBounds)
.SetProperty("id", &BaseWindow::GetID)
.Build();
阶段 3:平台分叉
NativeWindow::Create 是个工厂函数,按平台走不同实现:
Linux / Windows → native_window_views.cc (基于 Chromium 的 views 框架)
macOS → native_window_mac.mm (基于 Cocoa / AppKit)
两者都实现 NativeWindow 这个纯虚接口:
// shell/browser/native_window.h(结构示意)
class NativeWindow : public base::SupportsWeakPtr<NativeWindow>,
public EventEmitter<NativeWindow> {
public:
static NativeWindow* Create(const gin_helper::Dictionary& options,
NativeWindow* parent);
virtual void SetTitle(const std::string& title) = 0;
virtual void Show() = 0;
virtual gfx::Rect GetBounds() = 0;
virtual void SetBounds(const gfx::Rect& bounds, ...) = 0;
// ... 上百个纯虚函数
};
上百个纯虚函数,意味着每加一个窗口能力,要写两到三遍。这是跨平台原生 UI 的固有成本,也是 Electron 窗口相关 bug 的高发区——同一个 API 在三个平台上的细微行为差异,往往源于各自实现里的取舍。
阶段 4:落到操作系统
native_window_views.cc:291 最终调用 views::Widget::Init(),创建 aura::Window:
- Windows:落到
HWND - Linux:X11 窗口或 Wayland surface
- macOS:
native_window_mac.mm直接创建NSWindow
到这一步,屏幕上出现了一个空白窗口。
阶段 5:内容的诞生
窗口有了,内容呢?BrowserWindow 在构造后把 WebContentsView 加进去,而 WebContentsView 内部持有一个 content::WebContents。
content::WebContents 是 Chromium 的对象,它的创建会:
- 决定用哪个渲染进程(如果有可复用的同站点进程,就用;否则新建);
- 初始化
WebContentsDelegate(Electron 的api::WebContents); - 设置
WebContentsObserver。
阶段 6:进程创建
新建渲染进程时,Chromium 的 RenderProcessHost 会 fork 一个子进程,命令行里带上 --type=renderer 和一堆参数(sandbox 开关、语言、features)。
Electron 在这里插了一脚:ElectronBrowserClient::AppendExtraCommandLineSwitches 会追加 Electron 特有的开关,ElectronBrowserClient 还会在渲染进程启动后通过 mojo 传一批 webPreferences 过去。
阶段 7:导航
win.loadFile('index.html') 触发导航。这条路径是:
WebContents::loadFile() [lib/browser/api/web-contents.ts]
→ 拼出 file:// URL
→ this.loadURL(url)
→ C++: WebContents::LoadURL()
→ content::NavigationController::LoadURL()
→ ElectronNavigationThrottle 介入(可拦截)
→ 网络请求 / 本地文件读取
→ 响应到达
→ 渲染进程解析 HTML
阶段 8:渲染与合成
渲染进程里,Blink 解析 HTML、构建 DOM、计算样式、布局、绘制。绘制结果是一堆 viz 的 CompositorFrame,通过 IPC 送到 GPU 进程,GPU 进程合成后上屏。
Electron 在这条链路上又插了钩子:WebContents::DidFinishNavigation(发 did-finish-load 事件)、FrameSubscriber(订阅帧,用于 webContents.beginFrameSubscription)。
阶段 9:回到 JS
页面加载完成,did-finish-load 事件通过 EventEmitterMixin::Emit 发射到 JS 层,你的 win.webContents.on('did-finish-load', ...) 回调被调用。
完整链路图
JS: new BrowserWindow(options)
│
├─▶ lib/browser/api/browser-window.ts TS 层:makeWebPreferences、创建 view
│ │
│ └─▶ super(options)
│ │
│ ├─▶ C++: BaseWindow::New() 绑定层:v8::Object → gin::Dictionary
│ │ │
│ │ ├─▶ NativeWindow::Create()
│ │ │ ├─▶ native_window_views.cc → views::Widget → HWND / X11
│ │ │ └─▶ native_window_mac.mm → NSWindow
│ │ │
│ │ └─▶ 返回 Wrappable 对象,设原型
│ │
│ └─▶ new WebContentsView() → content::WebContents::Create()
│ │
│ ├─▶ RenderProcessHost::Init() ── fork ──▶ 渲染进程
│ │ (--type=renderer)
│ └─▶ NavigationController::LoadURL()
│ │
│ ├─▶ ElectronNavigationThrottle(可拦截)
│ └─▶ 网络/文件 → 响应
│ │
│ └─▶ 渲染进程:Blink 解析 → 布局 → 绘制
│ └─▶ viz CompositorFrame ──IPC──▶ GPU 进程
│ └─▶ 合成 ──▶ 屏幕
从一行 JS 到屏幕像素,跨了 4 个抽象层、至少 3 个进程。
这就是为什么 Electron 应用的性能问题往往难定位:你在 JS 层看到的 new BrowserWindow() 只花了 2ms,但真正的时间花在进程创建、GL 上下文初始化、字体加载上,这些都在你看不到的地方。
第 9 至 13 章会把这条链路的每一段拆开。
1.7 三张地图
走到这里,可以画三张图收束本章。后面 23 章都会反复回到这三张图。
1.7.1 进程地图
┌─────────────────────────────────────────────────────────────┐
│ 浏览器进程(Browser Process) │
│ shell/app/ shell/browser/ shell/common/ │
│ │
│ ├─ 主线程:UI、窗口、JS 主进程执行、message loop │
│ ├─ IO 线程:IPC、网络 │
│ ├─ EmbedThread:Node 的 libuv loop │
│ └─ 线程池:Chromium 的 base::ThreadPool │
└──────────────┬──────────────────────────────────────────────┘
│ mojo IPC
┌──────────┼───────────┬──────────────┬──────────────┐
▼ ▼ ▼ ▼ ▼
┌────────┐ ┌────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐
│渲染进程 │ │渲染进程 │ │ GPU 进程 │ │utility │ │ 网络服务 │
│Blink │ │Blink │ │ viz 合成 │ │Node 环境 │ │ NetworkSvc │
│+Node? │ │ │ │ GL/Vulkan │ │ │ │ │
└────────┘ └────────┘ └──────────┘ └──────────┘ └────────────┘
关键点:只有主进程默认有完整的 Node 环境。渲染进程的 Node 是"可选外挂",utility process 的 Node 是"受限环境"。这个差异决定了你能在哪个进程里 require('fs')。
1.7.2 代码地图
你要做的事 去哪里找
──────────────────────────────────────────────────────────────
加一个新的 JS API lib/browser/api/ 或 lib/renderer/api/
加一个新的原生能力 shell/browser/api/electron_api_*.cc
改窗口行为(跨平台) shell/browser/native_window*.cc
改窗口行为(单平台) native_window_mac.mm / _views.cc
改事件、改序列化 shell/common/gin_helper/
改 IPC 协议 shell/common/api/*.mojom
改进程启动 shell/app/electron_main_delegate.cc
改浏览器策略 shell/browser/electron_browser_client.cc
改渲染进程初始化 shell/renderer/renderer_client_base.cc
改构建 BUILD.gn / filenames.gni / build/
改上游行为 patches/<target>/*.patch
这张表比任何架构图都实用。当你在调试一个"奇怪的行为"时,先问自己:这个行为属于哪一层?
1.7.3 数据地图
一份数据从 JS 传到另一个进程,要经过哪些变换?
JS 值(v8::Local<Value>)
│
├─ gin 序列化(structured clone 方言) ← 在发送进程
│ └─▶ base::Value(Chromium 的通用值类型)
│ └─▶ mojo 序列化(字节流)
│ └─▶ IPC 传输
│ └─▶ mojo 反序列化
│ └─▶ base::Value
│ └─▶ gin 反序列化(gin_converters)
│ └─▶ JS 值(在接收进程)
│
└─ 不可序列化的东西(函数、Symbol、Promise、Proxy)
└─ 直接抛异常:"An object could not be cloned"
第 14 章会把这条链路每一段拆开。现在只需要记住:跨进程传值不是免费的,它至少三次转换。
1.8 Electron 不是什么
理解一个系统,有时要先排除误解。
1.8.1 它不是"浏览器 + Node"
最常见的误解是:Electron = Chromium + Node,两者并列。
不对。Node 是被"折叠"进 Chromium 的进程模型的。
具体说:
- Node 没有自己的主循环,它跑在 Chromium 的 message loop 上;
- Node 没有自己的线程池(部分),它共享 Chromium 的;
- Node 的 V8 就是 Chromium 的 V8;
- Node 的进程创建被 Chromium 的 sandbox 机制约束(所以 Electron 的
child_process需要特殊处理)。
node_bindings.cc:1192-1199 里的 EmbedThreadRunner 函数揭示了这种"折叠"的机制:Node 的 libuv loop 跑在一个专门的线程上,通过 uv_async_t 与主线程通信。
// shell/common/node_bindings.cc:1192-1213(结构)
void NodeBindings::EmbedThreadRunner(void* arg) {
auto* self = static_cast<NodeBindings*>(arg);
while (true) {
// Wait for the main thread to wake us up.
int idle = uv_run(self->uv_loop(), UV_RUN_ONCE);
if (idle == 0) {
// The loop has work to do; signal the main thread.
self->WakeupMainThread();
} else {
// Nothing to do; block until kicked.
self->WakeupEmbedThread(); // 内部是 uv_sem_wait
}
if (self->embed_closed_) break;
}
}
这个设计的含义是:Node 的事件循环不是"主循环",它是一个被主线程驱动的从属循环。 主线程每次 message loop 迭代都会检查 Node 有没有事要做,有事就唤醒 EmbedThread。
第 6 章会完整拆解这个机制,包括它带来的一个经典问题:setImmediate 和 setTimeout 在 Electron 主进程里的执行顺序与纯 Node 不同。
1.8.2 它不是"Web 应用套壳"
这个说法在 2013 年可能成立,在 Electron 45 时代完全不成立。
现代 Electron 应用的能力边界:
- 可以创建多个窗口、每个窗口独立进程、独立 session(cookie 隔离);
- 可以 fork utility process 做 CPU 密集计算,不阻塞 UI;
- 可以注册自定义协议、拦截任意网络请求、改写响应;
- 可以调用系统 API:托盘、通知、全局快捷键、电源管理、屏幕捕获;
- 可以嵌入原生视图(
WebContentsView)与 Web 内容混合布局; - 可以跑 Service Worker、Web Worker、Node 子进程。
这些不是"Web 平台能力",是 Electron 在 content 层上开的口子。每一个口子都对应 shell/browser/ 下的一个文件。
1.8.3 它不是一个"轻量"框架
诚实的数字:一个最小的 Electron 应用安装包约 80-120 MB(压缩后 50-70 MB),解压后 200 MB 以上。
原因不是"Electron 臃肿",而是它内置了:完整的 Chromium 渲染引擎、完整的 V8、完整的 Node 运行时、ICU 数据(国际化)、字体渲染库、媒体编解码器(ffmpeg)、网络栈(含 TLS)。
对比一下:Chrome 浏览器安装包约 100 MB。Electron 应用包含的东西和 Chrome 差不多,因为它就是一个 Chrome。
这个体积换来的是一致性:Windows 10 和 macOS 15 上,你的应用用同一个渲染引擎、同一套 JS 语义、同一份排版算法。在企业应用场景下这个价值极高——你不需要为每个平台适配 CSS 渲染差异、不需要担心某个 CSS 特性在旧系统浏览器上不支持。
1.9 一个必须理解的矛盾:版本绑定的代价
Electron 的架构决定了它必须同时锁定 Chromium 和 Node 的版本。
DEPS 里那两个版本号不是可以随便改的:
- Chromium 版本决定了
content层的 API。content::WebContents的方法签名、ContentBrowserClient的虚函数列表,每个 Chromium 大版本都可能变。Electron 的 17 万行 C++ 必须跟着改。 - Node 版本决定了
process.binding的内部实现、libuv的 API、N-API 的版本。Electron 的 Node 集成代码必须跟着改。
所以每次 Chromium 升级(约每 8 周一次),Electron 团队要做的事是:
- 更新
DEPS里的chromium_version; - 运行
e sync --3,让 380 个补丁以三方合并方式重新应用; - 修复所有编译错误(通常几百个);
- 修复所有行为变化导致的测试失败(1003 个测试文件);
- 重新导出补丁(
e patches all)。
这是一个持续的、高强度的维护工作。它解释了为什么:
- Electron 的大版本总是落后 Chromium 几个版本(需要时间适配);
- Electron 的某些 Chromium 新特性"用不了"(还没适配到 content 层);
- Electron 的 bug 修复有时需要"等上游"(问题在 Chromium 里,而 Electron 不能随便改)。
CLAUDE.md 里有一整节讲这个流程,包括在 roller/chromium/main 分支上工作时需要激活专门的 skill。这不是过度工程,是必要流程。
对使用者的影响也很实际:Electron 大版本升级往往意味着"某些东西悄悄变了"。 第 24 章会讨论如何管理这种升级风险。
1.10 主进程启动:五个阶段的真实顺序
前面说了"Electron 是 content 层的嵌入者"。这句话落到实处,就是一系列按固定顺序回调的钩子。这一节把顺序摆出来,因为顺序本身就是架构:为什么 Node 环境要在 V8 平台之后创建?为什么日志要初始化两次?为什么 FeatureList 要被清空重建?
看懂了顺序,这些问题自动有答案。
1.10.1 阶段 0:BasicStartupComplete
electron_main_delegate.cc:177-181
// shell/app/electron_main_delegate.cc(结构)
std::optional<int> ElectronMainDelegate::BasicStartupComplete() {
auto* command_line = base::CommandLine::ForCurrentProcess();
...
chrome::RegisterPathProvider();
electron::RegisterPathProvider();
...
return std::nullopt;
}
这个阶段非常早,早到还没有 V8、没有线程池、没有 message loop。它能做的事只有:读命令行、注册路径、设置进程级的开关。
看它实际做了什么:
// 节选,逐条说明
#if BUILDFLAG(IS_WIN)
v8_crashpad_support::SetUp();
if (IsBrowserProcess()) std::wcout << std::endl;
#endif
Windows 上要提前装 V8 的崩溃支持,因为 V8 可能在初始化阶段就崩。那行 std::wcout << std::endl 看起来莫名其妙,注释解释了原因:Windows 终端不会自动换行,不加这一行,后续输出会跟在提示符同一行。
electron_main_delegate.cc:189-193
auto env = base::Environment::Create();
if (env->HasVar(kElectronEnableStackDumping))
base::debug::EnableInProcessStackDumping();
if (env->HasVar(kElectronDisableSandbox))
command_line->AppendSwitch(sandbox::policy::switches::kNoSandbox);
两个环境变量在这里被消费:
ELECTRON_ENABLE_STACK_DUMPING:开启进程内堆栈打印(崩溃时输出 C++ 栈)。ELECTRON_DISABLE_SANDBOX:等价于--no-sandbox。
注意第二条的写法:不是设置一个布尔标志,而是往命令行里追加 --no-sandbox。 这是 Chromium 的惯例——所有配置最终都收敛到命令行,因为命令行是唯一能跨进程传递的东西(子进程靠它决定自己的行为)。
electron_main_delegate.cc:199-200
tracing_sampler_profiler_ =
tracing::TracingSamplerProfiler::CreateOnMainThread();
创建堆栈采样分析器。它服务于 contentTracing 模块——你在 DevTools 的 Performance 面板里看到的 JS 调用栈与 C++ 调用栈的关联,靠它。
electron_main_delegate.cc:223-224
#if BUILDFLAG(IS_LINUX)
if (getuid() == 0 && IsSandboxEnabled(command_line))
LOG(FATAL) << "Running as root without --no-sandbox is not supported.";
#endif
以 root 运行且没关沙箱,直接致命错误退出。这条限制来自 Chromium(crbug.com/638180):setuid sandbox 在 root 下行为不可预测。很多 CI 环境踩过这个坑,解决办法就是加 --no-sandbox(安全上不推荐,但容器里常见)。
#if IS_MAS_BUILD()
command_line->AppendSwitch(::switches::kDisableGpuMemoryBufferCompositorResources);
#endif
MAS(Mac App Store)构建的特殊处理。注释引用了 Chromium 开发者的解释:MAS 构建禁用 remote core animation,而禁用之后 IOSurface 就不再带来好处,只剩重量级开销,所以顺带把 GPU memory buffer 也关掉。
这一段是"Electron 的每个怪异分支背后都有一个具体原因"的典型例子。 你如果只看代码不读注释,会觉得这是随手加的;读了注释才知道是被 App Store 的审核规则逼出来的。
1.10.2 阶段 1:PreSandboxStartup
名字说明了一切:沙箱启动之前。这是最后一个能自由访问文件系统的时机之一。
electron_main_delegate.cc:247-254
void ElectronMainDelegate::PreSandboxStartup() {
auto* command_line = base::CommandLine::ForCurrentProcess();
std::string process_type = GetProcessType();
base::FilePath user_data_dir =
command_line->GetSwitchValuePath(::switches::kUserDataDir);
if (!user_data_dir.empty()) {
base::PathService::OverrideAndCreateIfNeeded(chrome::DIR_USER_DATA,
user_data_dir, false, true);
}
第一件事:如果命令行给了 --user-data-dir,覆盖默认的用户数据目录。这个覆盖必须现在做,因为后面所有路径计算都依赖它。
#if !BUILDFLAG(IS_WIN)
logging::InitElectronLogging(*command_line,
/* is_preinit = */ IsBrowserProcess() || IsZygoteProcess());
#endif
日志的第一次初始化,而且带 is_preinit = true。
为什么是"预初始化"?注释写得很清楚:Linux 上 zygote 在 JS 运行之前就启动了,它不可能知道正确的用户数据目录(那个目录由应用名决定,而应用名要读 package.json)。所以此时只能做"不落文件"的初始化,等知道了路径再正式初始化。
这就解释了后面 PostEarlyInitialization 里为什么又调了一次 InitElectronLogging,参数是 is_preinit = false。
两次初始化日志,是启动顺序约束的直接产物。 这类"看起来冗余"的代码,在 Electron 里非常多,每一处都对应一个时序约束。
electron_main_delegate.cc:278-280
if (SubprocessNeedsResourceBundle(process_type)) {
std::string locale = command_line->GetSwitchValueASCII(::switches::kLang);
LoadResourceBundle(locale);
}
资源包加载。哪些子进程需要?
electron_main_delegate.cc:92-104
bool SubprocessNeedsResourceBundle(const std::string& process_type) {
return
#if BUILDFLAG(IS_LINUX)
process_type == ::switches::kZygoteProcess ||
#endif
#if BUILDFLAG(IS_MAC)
process_type == ::switches::kGpuProcess ||
#endif
process_type == ::switches::kRendererProcess ||
process_type == ::switches::kUtilityProcess;
}
这张条件表本身就是平台差异的说明书:
- Linux 的 zygote 要开资源,因为后续 fork 出的所有渲染进程都继承它的地址空间;
- macOS 的 GPU 进程要开资源,因为滚动条之类要用图片资源;
- 渲染进程和 utility 进程在所有平台都要。
electron_main_delegate.cc:318-319
if (IsBrowserProcess()) {
command_line->AppendSwitch(::switches::kAllowFileAccessFromFiles);
主进程追加 --allow-file-access-from-files。这是 Electron 与 Chrome 的一个显著行为差异:Chrome 里 file:// 页面不能 XHR 另一个 file:// 文件(同源策略把每个 file 当成独立源),Electron 默认允许。
为什么?因为 Electron 应用的典型形态是"本地 HTML + 本地资源",如果按 Chrome 的规则,fetch('./data.json') 会失败,开发者会疯。
这条也是安全问题的一个来源:加载了不可信 HTML 的应用,等于给了它读取本地文件的能力。第 15 章讲安全时会回头看这条。
1.10.3 阶段 2:PreEarlyInitialization
electron_browser_main_parts.cc:278-285
int ElectronBrowserMainParts::PreEarlyInitialization() {
#if BUILDFLAG(IS_POSIX)
HandleSIGCHLD();
#endif
#if BUILDFLAG(IS_MAC)
screen_ = std::make_unique<display::ScopedNativeScreen>();
#endif
ui::ColorProviderManager::Get().AppendColorProviderInitializer(
base::BindRepeating(AddChromeColorMixers));
#if BUILDFLAG(IS_WIN)
ui::ColorProviderManager::Get().AppendColorProviderInitializer(
base::BindRepeating(AddMenuHighlightColorMixer));
#endif
return GetExitCode();
}
四件事:
HandleSIGCHLD:POSIX 上要处理子进程退出信号,否则僵尸进程堆积。Electron 应用经常 fork 子进程(child_process、utility process),这条必需。ScopedNativeScreen(仅 macOS):拿到NSScreen的句柄,供screen模块使用。必须在 Cocoa 初始化前拿。- 颜色混合器:Chromium 的
ColorProviderManager负责把设计系统的颜色 token 解析成实际颜色值。Electron 追加"Chrome 颜色"(让nativeTheme的表现接近 Chrome)和 Windows 的菜单高亮色。 - 返回退出码。
注意这里没有创建 V8。V8 的创建被推迟到了下一个阶段,原因写在下一阶段的注释里。
1.10.4 阶段 3:PostEarlyInitialization——整个启动流程的心脏
如果全书只能精读一个函数,就是这个。它 120 行左右,做了十几件互相依赖的事。
electron_browser_main_parts.cc:297-298
void ElectronBrowserMainParts::PostEarlyInitialization() {
DCHECK(base::SingleThreadTaskRunner::HasCurrentDefault());
第一行是断言:当前线程必须有 TaskRunner。注释说"以前需要一个 workaround,因为当时没有设置 ThreadTaskRunner;如果这个检查失败,可能要重新加回那个 workaround"。
这是一条考古线索:说明历史上这里出过问题,后来上游修了,但断言留着防止回归。
第一步:WebAssembly 陷阱处理器
#if (...x86_64 或 arm64...)
if (electron::fuses::IsWasmTrapHandlersEnabled()) {
electron::SetUpWebAssemblyTrapHandler();
}
#endif
注释极其关键:
Enable trap handlers before creating the V8 isolate. V8 initialization calls
IsTrapHandlerEnabled()which prevents later EnableTrapHandler calls.
意思是:必须在创建 Isolate 之前装好。因为 V8 初始化时会查询"陷阱处理器是否已启用",一旦它认为没启用,之后就不允许再启用。
这是典型的"一次性决策"型 API,顺序错了就永久失效。而它受 fuse 控制(IsWasmTrapHandlersEnabled),说明有安全考量:Wasm 陷阱处理器用信号处理实现边界检查,某些加固场景下要关掉。
第二步:创建 V8 环境
electron_browser_main_parts.cc:314-316
js_env_ = std::make_unique<JavascriptEnvironment>(node_bindings_->uv_loop());
v8::Isolate* const isolate = js_env_->isolate();
v8::HandleScope scope(isolate);
注释解释了为什么拖到现在:
The ProxyResolverV8 has setup a complete V8 environment, in order to avoid conflicts we only initialize our V8 environment after that.
ProxyResolverV8 是 Chromium 网络栈里用于解析 PAC 代理脚本的组件,它自己会建一个 V8 环境。如果 Electron 早于它创建,两者的全局状态会打架。
"等别人先建完"是嵌入者必须遵守的礼节。 这类顺序依赖在 Chromium 生态里随处可见,也是 Electron 升级 Chromium 时最容易被打破的东西。
第三步:Node 初始化
node_bindings_->Initialize(isolate, context);
这一行进入 node_bindings.cc:691-698 的 691 行,做的是:
void NodeBindings::Initialize(v8::Isolate* const isolate,
v8::Local<v8::Context> context) {
TRACE_EVENT0("electron", "NodeBindings::Initialize");
...
RegisterBuiltinBindings();
electron::util::InstallProcessCodeCache();
auto env = base::Environment::Create();
SetNodeOptions(env.get());
std::vector<std::string> args = ParseNodeCliFlags();
...
std::shared_ptr<node::InitializationResult> result =
node::InitializeOncePerProcess(args, process_flags);
...
}
拆开看:
RegisterBuiltinBindings():把 Electron 自己的 61 个electron_browser_*/electron_common_*模块注册到 Node 的模块表里。这就是process._linkedBinding('electron_browser_app')能找到东西的原因。InstallProcessCodeCache():装上构建期生成的字节码缓存。注释说得很直接:让 Node 的启动过程"消费缓存而不是从源码编译约 100 个内置模块"。SetNodeOptions():把环境变量(NODE_OPTIONS等)转成 Node 的选项。注意这里受 fuse 控制:if (!fuses::IsNodeOptionsEnabled())时加kDisableNodeOptionsEnv。也就是说,打包时关掉这个 fuse,用户就没法通过NODE_OPTIONS注入参数——这是一个安全加固点。ParseNodeCliFlags():解析--js-flags之类的开关。node::InitializeOncePerProcess():Node 自己的进程级初始化。
process_flags 那段前面已经引过,三个 kNoInitialize*。这里再补两个:
node_bindings.cc:733-736
if (browser_env_ == BrowserEnvironment::kRenderer)
process_flags |= node::ProcessInitializationFlags::kNoDefaultSignalHandling;
if (browser_env_ != BrowserEnvironment::kUtility)
process_flags |= node::ProcessInitializationFlags::kEnableStdioInheritance;
- 渲染进程禁用 Node 的默认信号处理,因为 Chromium 有自己的信号处理体系,两套会冲突。
- utility 进程禁用 stdio 继承,因为 utility process 的 stdio 被 Electron 重定向到了自定义管道(用于
utilityProcess的stdout/stderr事件);如果继承,子进程会拿到错误的句柄。
每一个 flag 都是一次冲突的产物。 这句话可以作为理解整个 node_bindings.cc 的钥匙。
第四步:创建 Node Environment
electron_browser_main_parts.cc:337-342
node_env_ = node_bindings_->CreateEnvironment(
isolate, context, js_env_->platform(),
js_env_->max_young_generation_size_in_bytes());
if (context.IsEmpty()) {
node_env_->context()->Enter();
}
node_bindings_->SetUpIsolate(isolate);
CreateEnvironment 是 Electron 版的 node::CreateEnvironment,参数里有两个值得注意的东西:
js_env_->platform():把 Electron 持有的平台传进去,落实了node_use_v8_platform = false的约定;max_young_generation_size_in_bytes():新生代堆大小上限,用于控制 GC 频率。
context.IsEmpty() 那个分支对应"从 Node 启动快照恢复"的场景:此时 context 是在 node::CreateEnvironment 内部创建的,JavascriptEnvironment 构造函数没有建 context,所以这里要手动 Enter。注释说明了这个细节。
SetUpIsolate 做的事是给 Isolate 装上一堆回调:
node_bindings.cc:774-777
void NodeBindings::SetUpIsolate(v8::Isolate* const isolate) {
node::IsolateSettings is;
is.fatal_error_callback = V8FatalErrorCallback;
is.oom_error_callback = V8OOMErrorCallback;
...
}
V8FatalErrorCallback 和 V8OOMErrorCallback 是 Electron 定制的——它们在 V8 致命错误时往崩溃报告里附加信息,而不是直接 abort。这让"OOM 崩溃"的诊断变得可能。
第五步:绑定 Electron 扩展 API
electron_browser_main_parts.cc:351-352
node_env_->options()->unhandled_rejections = "warn-with-error-code";
electron_bindings_->BindTo(isolate, node_env_->process_object());
第一行:未处理的 Promise rejection 不崩溃主进程,只警告。 这是 Electron 与 Node 的一个行为差异——Node 15 之后默认 throw,Electron 改成了 warn-with-error-code。
原因很实际:主进程崩了,整个应用就没了。一个未处理的 rejection 不应该导致这种后果。
第二行:ElectronBindings::BindTo 往 process 对象上挂 Electron 特有的方法和属性。process.versions.electron、process.resourcesPath、process.type 都是在这里加的。第 1.11 节的练习题 3 就是让你找这个。
第六步:找到应用并传给 JS
electron_browser_main_parts.cc:358-365
if (std::optional<AppPackage> package = LoadAppPackage()) {
v8::Local<v8::Context> env_context = node_env_->context();
gin_helper::Dictionary app_package = gin::Dictionary::CreateEmpty(isolate);
app_package.Set("path", package->path);
app_package.Set("main", package->main);
app_package.Set("esm", package->esm);
if (!package->v8_flags.empty())
app_package.Set("v8Flags", package->v8_flags);
env_context->Global()
->SetPrivate(env_context,
v8::Private::ForApi(
isolate, gin::StringToSymbol(isolate, "appPackage")),
gin::ConvertToV8(isolate, app_package))
.Check();
}
LoadAppPackage() 定义在 app_package.cc,它的注释就是一份规格说明:
app_package.h:19-23
// shell/browser/app_package.h
// The app the browser process is going to run: the first of
// resources/app.asar, resources/app, resources/default_app.asar (or only
// app.asar under the OnlyLoadAppFromAsar fuse) with a readable package.json.
struct AppPackage {
base::FilePath path;
// package.json "main", or index.js.
std::string main;
// Whether |main| is loaded as an ES module.
bool esm = false;
// package.json "v8Flags"; applied just before |main| is loaded so that the
// bundled startup scripts still match their code cache.
std::string v8_flags;
};
四条信息,四个用途。最后一条 v8_flags 的注释值得单独说:为什么"在加载 main 之前"才应用 v8Flags?
因为 browser_init.js 自己也要执行,而它的执行依赖构建期生成的字节码缓存。如果提前改了 V8 标志,缓存可能失效(不同的标志会让 V8 拒绝某些缓存的字节码),启动变慢。所以延后到"框架脚本已经跑完、应用脚本即将运行"的那一刻。
这就是 lib/browser/init.ts:95-98 里这段代码的由来:
const { appCodeLoaded } = process;
delete process.appCodeLoaded;
// Applied only now so that everything above still matched its code cache.
if (appPackage.v8Flags) {
(require('v8') as typeof v8).setFlagsFromString(appPackage.v8Flags);
}
那行注释 "Applied only now so that everything above still matched its code cache" 和 C++ 里的注释是同一件事的两半。读到这种跨语言的呼应,说明你真的读懂了一段流程。
而 SetPrivate 用的 key 是 v8::Private::ForApi——私有符号,JS 里无法枚举、无法猜测,只能通过 v8Util.getHiddenValue(global, 'appPackage') 拿到。这就是 1.2.2 节说的"受控反向通道"。
第七步:微任务泵
js_env_->CreateMicrotasksRunner();
MicrotasksRunner 是 Electron 特有的东西。V8 的微任务队列(Promise 回调)需要一个"泵"来驱动——通常是 message loop 在每轮迭代后调用 PerformCheckpoint()。
但 Electron 有两个 loop:Chromium 的和 libuv 的。如果只在 Chromium 的 loop 里泵,Node 侧的 Promise 在 libuv 阶段产生的微任务就得不到及时处理。
MicrotasksRunner 的职责就是协调这两者。第 6 章会展开。
第八步:加载 JS 启动脚本
node_bindings_->set_uv_env(node_env_.get());
...
node_bindings_->LoadEnvironment(node_env_.get());
LoadEnvironment 是"从 C++ 跨进 JS"的那一刻:
node_bindings.cc:1006-1013
void NodeBindings::LoadEnvironment(node::Environment* env) {
electron::util::FeedEnvironmentCodeCache(env);
...
const std::string bundle_id =
"internal/electron/js2c/" + std::string(ProcessType()) + "_init";
node::LoadEnvironment(env, [&](const node::StartExecutionCallbackInfo& info) {
...
v8::LocalVector<v8::String> params =
js2c::MakeBundleParams(isolate, js2c::kInitBundleParams);
v8::Local<v8::Value> args[] = {info.process_object, require};
v8::Local<v8::Function> bundle;
if (!electron::util::CompileBundle(context, bundle_id.c_str(), ¶ms)
.ToLocal(&bundle)) {
return v8::MaybeLocal<v8::Value>();
}
return bundle->Call(context, v8::Null(isolate), std::size(args), args);
},
&OnNodePreload);
gin_helper::EmitEvent(env->isolate(), env->process_object(), "loaded");
}
三件事:
- 拼 bundle id:
internal/electron/js2c/browser_init(主进程)、renderer_init(渲染进程)……这就是 1.5 节那张表在运行时的用法。 - 编译并调用 bundle:
CompileBundle从内置字符串里取出源码,编译成函数,然后用(process, require)两个参数调用。这就是browser_init.js的执行方式。 - 发射
loaded事件:注意这是 C++ 侧直接EmitEvent到process对象上,JS 侧可以监听。
CompileBundle 里有个细节值得看:
node_bindings.cc:1025-1026
// Node pauses for --inspect-brk before an embedder entry point runs; mask it
// so the pause stays on the app's own entry rather than the first line of
// the init bundle
const bool break_first_line = debug_options->break_first_line;
debug_options->break_first_line = false;
--inspect-brk 本该停在"用户代码第一行"。如果不管,它会停在 browser_init.js 的第一行——对调试者毫无意义。所以先屏蔽,等 bundle 跑完再恢复。
这是一个 20 行的细节,但它决定了成千上万开发者的调试体验。 好的基础设施代码,就是这样一堆体贴的细节堆出来的。
第九步:等应用代码加载完
electron_browser_main_parts.cc:388
node_bindings_->JoinAppCode();
这个函数(node_bindings.cc:1116)非常有意思:
void NodeBindings::JoinAppCode() {
if (browser_env_ != BrowserEnvironment::kBrowser) return;
auto* browser = Browser::Get();
node::Environment* env = uv_env();
if (!env) return;
v8::HandleScope handle_scope(env->isolate());
v8::Context::Scope context_scope(env->context());
// Pump the event loop until we get the signal that the app code has finished loading
while (!app_code_loaded_ && !browser->is_shutting_down()) {
int r = uv_run(uv_loop_, UV_RUN_ONCE);
if (r == 0) {
base::RunLoop().QuitWhenIdle();
break;
}
}
}
这是一个同步的、阻塞的事件循环泵。
它不断调 uv_run(uv_loop_, UV_RUN_ONCE),直到 app_code_loaded_ 变成 true。而 app_code_loaded_ 是 JS 侧调 process.appCodeLoaded() 设置的:
// lib/browser/init.ts
const { appCodeLoaded } = process;
delete process.appCodeLoaded;
...
Module._load(path.join(appPackage.path, appPackage.main), Module, true);
appCodeLoaded!(); // ← 这里有同步调用,也有 ESM 的异步分支
所以整个流程是:
C++: PostEarlyInitialization
└─▶ LoadEnvironment 执行 browser_init.js
└─▶ browser_init.js 同步 require 应用的 main.js
└─▶ main.js 执行(注册 app.whenReady 回调、创建窗口……)
└─▶ appCodeLoaded() 设置 app_code_loaded_ = true
└─▶ JoinAppCode 泵 uv loop 直到上面那个标志变 true
这意味着:main.js 的顶层代码是在 app ready 之前同步跑完的。 这就是为什么你可以在 main.js 顶层直接 app.whenReady().then(...)——那时 ready 还没发生,回调会被正确排队。
如果你在 main.js 顶层做耗时操作(比如同步读大文件),整个启动会被阻塞,窗口出现的时间被推迟。这不是"最佳实践建议",是这段代码的机械后果。
base::RunLoop().QuitWhenIdle() 那行是给异步场景准备的:如果 uv loop 没活了(uv_run 返回 0)而应用代码还没标记加载完,就退出一次 RunLoop,让 Chromium 的 loop 有机会跑。
第十步:重建 FeatureList 和日志
electron_browser_main_parts.cc:404-409
base::FeatureList::ClearInstanceForTesting();
InitializeFeatureList();
InitializeFieldTrials();
logging::InitElectronLogging(*base::CommandLine::ForCurrentProcess(),
/* is_preinit = */ false);
fake_browser_process_->PostEarlyInitialization();
为什么要把 FeatureList 清空重建?
注释给了答案:FeatureList 在 PreEarlyInitialization 已经初始化过一次,但那时用户 JS 还没跑,没机会改命令行开关。用户可能在自己的 main.js 里 app.commandLine.appendSwitch('enable-features', ...)。为了让这些改动生效,必须重建。
这是一个"用户代码在框架初始化中间执行"带来的必然结果。Electron 的启动流程不是一条直线,而是"框架初始化 → 用户代码 → 框架再初始化"的折返跑。
logging 的第二次初始化同理:现在应用名和用户数据目录都确定了,可以把日志写到正确的位置。
1.10.5 阶段 4:线程与工具包
int ElectronBrowserMainParts::PreCreateThreads() { ... }
void ElectronBrowserMainParts::ToolkitInitialized() { ... }
void ElectronBrowserMainParts::PreCreateMainMessageLoopCommon() { ... }
void ElectronBrowserMainParts::PostCreateMainMessageLoop() { ... }
这四个钩子对应 Chromium 的四个时机:
| 钩子 | 时机 | Electron 在这里做什么 |
|---|---|---|
PreCreateThreads | 创建 IO 线程等之前 | 初始化 LayoutProvider、views 委托 |
ToolkitInitialized | UI 工具包(GTK/Cocoa/Views)就绪 | 设置字体、图标、托盘 |
PreCreateMainMessageLoop | 主循环创建前 | macOS 加载 MainNib、注册 URL handler;Windows 初始化 OSCrypt |
PostCreateMainMessageLoop | 主循环创建后 | Linux 的 Ozone/DBus/os_crypt;macOS 的 Keychain;POSIX 的 SIGINT 处理 |
PostCreateMainMessageLoop 里有一段值得单独看:
electron_browser_main_parts.cc:707-710
#if BUILDFLAG(IS_LINUX)
// Set up crypt config. This needs to be done before anything starts the
// network service, as the raw encryption key needs to be shared with the
// network service for encrypted cookie storage.
...
os_crypt::SelectedLinuxBackend selected_backend =
os_crypt::SelectBackend(config->store, use_backend, desktop_env);
fake_browser_process_->SetLinuxStorageBackend(selected_backend);
OSCrypt::SetConfig(std::move(config));
#endif
Linux 上的 cookie 加密需要一个密钥,密钥存哪取决于桌面环境(GNOME Keyring / KWallet / 纯文本)。这段代码在做"选后端"的决策。
注释点出了时序约束:必须在网络服务启动之前配置好,因为网络服务需要那把原始密钥来加密 cookie。
这也解释了一个常见问题:为什么 Linux 上换个桌面环境,登录状态就丢了? 因为后端换了,密钥取不出来,旧 cookie 解不开。
1.10.6 阶段 5:进入主循环
electron_browser_main_parts.cc:663-667
void ElectronBrowserMainParts::WillRunMainMessageLoop(
std::unique_ptr<base::RunLoop>& run_loop) {
exit_code_ = content::RESULT_CODE_NORMAL_EXIT;
Browser::Get()->SetMainMessageLoopQuitClosure(
run_loop->QuitWhenIdleClosure());
}
这个函数只做一件事:把"退出主循环"的闭包存到 Browser 里。之后 app.quit() 就是调用它。
browser.cc:282-287
void Browser::SetMainMessageLoopQuitClosure(base::OnceClosure quit_closure) {
if (is_shutdown_)
RunQuitClosure(std::move(quit_closure));
else
quit_main_message_loop_ = std::move(quit_closure);
}
注意 is_shutdown_ 分支:如果已经处于关闭流程,不能存闭包(存了也不会被调用),要立刻 PostTask 执行。
而 RunQuitClosure 又做了一层延迟:
browser.cc:49-56
void RunQuitClosure(base::OnceClosure quit) {
// On Linux/Windows the "ready" event is emitted in "PreMainMessageLoopRun",
// make sure we quit after message loop has run for once.
base::SingleThreadTaskRunner::GetCurrentDefault()->PostTask(FROM_HERE,
std::move(quit));
}
注释解释了原因:如果在 ready 事件里立刻退出,某些初始化任务还挂着,退出时会崩。 所以延迟一个 task。
这类"退出时崩溃"的 bug 在 Electron 历史上有过多次,修复方式往往就是这种"再等一轮"。
1.10.7 完整时序表
把上面所有阶段压成一张表:
时间轴 C++ 侧 JS 侧
────────────────────────────────────────────────────────────────────────
│
├─ ContentMain()
│ └─ BasicStartupComplete() (无 V8)
│ · 注册路径
│ · 读环境变量 → 追加命令行开关
│
├─ PreSandboxStartup() (无 V8)
│ · 覆盖 user-data-dir
│ · 日志预初始化
│ · 加载资源包(子进程)
│ · 追加 --allow-file-access-from-files
│
├─ PreEarlyInitialization() (无 V8)
│ · SIGCHLD、颜色混合器
│
├─ PostEarlyInitialization() ★ V8 诞生
│ 1. Wasm 陷阱处理器
│ 2. JavascriptEnvironment → Isolate + Platform
│ 3. NodeBindings::Initialize(Node 进程初始化)
│ 4. CreateEnvironment(Node 环境 + context)
│ 5. BindTo(process 对象扩展)
│ 6. LoadAppPackage → global 私有属性 appPackage
│ 7. CreateMicrotasksRunner
│ 8. LoadEnvironment ────────────────────────▶ 执行 browser_init.js
│ · require 应用 main.js
│ · 顶层代码同步执行
│ · appCodeLoaded() ◀──┐
│ 9. JoinAppCode(泵 uv loop,等上面的信号)───────────────────────┘
│ 10. 重建 FeatureList / 日志
│
├─ PreCreateThreads()
├─ ToolkitInitialized()
├─ PreCreateMainMessageLoop()
├─ PostCreateMainMessageLoop() (os_crypt、Keychain、信号)
│
├─ PreMainMessageLoopRun() ★ 发射 'ready'
│
└─ WillRunMainMessageLoop() 存退出闭包
│
▼
主循环开始运转(UI 事件、IPC、定时器……)
这张表是第 5 章的骨架。 现在只需要记住两个星号的位置:V8 在 PostEarlyInitialization 诞生,ready 在 PreMainMessageLoopRun 发射。
1.11 关闭:严格逆序的拆卸
启动是"按依赖顺序建立",关闭就必须"按依赖逆序拆除"。Electron 的关闭流程写在 PostMainMessageLoopRun:
electron_browser_main_parts.cc:724-731
void ElectronBrowserMainParts::PostMainMessageLoopRun() {
#if BUILDFLAG(IS_MAC)
FreeAppDelegate();
#endif
// Shutdown the DownloadManager before destroying Node to prevent
// DownloadItem callbacks from crashing.
for (auto* browser_context : ElectronBrowserContext::BrowserContexts()) {
if (auto* download_manager = browser_context->GetDownloadManager())
download_manager->Shutdown();
}
// Shutdown utility process created with Electron API before
// stopping Node.js so that exit events can be emitted.
api::UtilityProcessWrapper::ShutdownAll();
// Destroy node platform after all destructors_ are executed, as they may
// invoke Node/V8 APIs inside them.
node_env_->set_trace_sync_io(false);
js_env_->DestroyMicrotasksRunner();
node::Stop(node_env_.get(), node::StopFlags::kDoNotTerminateIsolate);
node_bindings_->set_uv_env(nullptr);
node_env_.reset();
browser_.reset();
js_env_.reset();
ElectronBrowserContext::DestroyAllContexts();
fake_browser_process_->PostMainMessageLoopRun();
content::DevToolsAgentHost::StopRemoteDebuggingPipeHandler();
...
}
逐条读,每条注释都在解释"为什么是这个顺序"。
1. FreeAppDelegate()(macOS)
释放 Objective-C 的 app delegate。必须在其他清理之前,因为它可能持有窗口引用。
2. 先关 DownloadManager
注释:如果不先关,DownloadItem 的回调会在 Node 已销毁之后触发,然后崩溃。
想象这个场景:用户下载到一半退出应用。DownloadManager 的析构会触发"下载取消"事件,事件回调可能调到 JS(item.on('done')),而 JS 环境已经没了 → 崩。
3. 再关 utility process
注释很长,值得完整读:
Shutdown utility process created with Electron API before stopping Node.js so that exit events can be emitted. We don't let content layer perform this action since it destroys child process only after this step (PostMainMessageLoopRun) via BrowserProcessIOThread::ProcessHostCleanUp() which is too late for our use case.
意思是:Chromium 会在 PostMainMessageLoopRun 之后才清理子进程,但那时 Node 已经停了,exit 事件发不出去。所以 Electron 自己提前关。
这是一个"抢占上游清理时机"的例子——因为语义需求(要发 exit 事件)与上游的清理顺序冲突。
4. 停 Node
electron_browser_main_parts.cc:750-754
node_env_->set_trace_sync_io(false);
js_env_->DestroyMicrotasksRunner();
node::Stop(node_env_.get(), node::StopFlags::kDoNotTerminateIsolate);
node_bindings_->set_uv_env(nullptr);
node_env_.reset();
四个动作:
- 关掉同步 IO 追踪(否则
node::Stop里会打印一堆东西); - 先销毁微任务泵(它依赖 Node 环境);
node::Stop但不终止 Isolate(kDoNotTerminateIsolate)——因为 Isolate 归JavascriptEnvironment管,Node 无权销毁它;- 断开 uv 环境指针,防止悬垂。
kDoNotTerminateIsolate 这个 flag 是所有权边界的体现。 Node 想说"我清理完了,Isolate 你可以扔了",Electron 说"不,Isolate 是我的,我来扔"。这又回到 node_use_v8_platform = false 那条原则。
5. 销毁 Browser 与 JavascriptEnvironment
electron_browser_main_parts.cc:756-757
browser_.reset();
js_env_.reset();
顺序不能反。Browser 里存着退出闭包和一些窗口引用,先销毁它,再销毁 Isolate。
6. 销毁 BrowserContext,最后是 BrowserProcess
electron_browser_main_parts.cc:758-759
ElectronBrowserContext::DestroyAllContexts();
fake_browser_process_->PostMainMessageLoopRun();
到这里,一个进程的生命结束。
1.11.1 关闭流程中的三态
Browser::OnWindowAllClosed 揭示了关闭流程的状态机:
browser.cc:316-324
void Browser::OnWindowAllClosed() {
if (is_exiting_) {
Shutdown();
} else if (is_quitting_) {
NotifyAndShutdown();
} else {
observers_.Notify(&BrowserObserver::OnWindowAllClosed);
}
}
三个状态:
| 状态 | 含义 | 行为 |
|---|---|---|
is_exiting_ | 用户调了 app.exit() | 直接关,不问 |
is_quitting_ | 用户调了 app.quit() 且在退出中 | 发 will-quit,可被阻止 |
| 都没设 | 只是窗口关完了 | 发 window-all-closed,交给 JS 决定 |
这就是为什么 window-all-closed 的默认行为(在 lib/browser/init.ts:89-91 里)是 app.quit(),但如果你监听并阻止,应用就继续活着:
// lib/browser/init.ts
app.on('window-all-closed', () => {
if (app.listenerCount('window-all-closed') === 1) {
app.quit();
}
});
listenerCount === 1 的意思是"只有我自己(框架)在监听"。 一旦用户加了监听器,数量变成 2,框架就不自动退出。
这是一个很聪明的设计:不需要"是否阻止默认行为"的显式 API,用监听器数量就能表达意图。
1.11.2 一个真实的坑:before-quit 与 beforeunload
HandleBeforeQuit 与 OnWindowCloseCancelled 这两个函数共同处理一个微妙场景:
browser.cc:303-307
bool Browser::HandleBeforeQuit() {
bool prevent_default = false;
observers_.Notify(&BrowserObserver::OnBeforeQuit, &prevent_default);
return !prevent_default;
}
// shell/browser/browser.cc:309-314
void Browser::OnWindowCloseCancelled(NativeWindow* window) {
if (is_quitting_)
// Once a beforeunload handler has prevented the closing, we think the quit
// is cancelled too.
is_quitting_ = false;
}
场景:用户点关闭 → app.quit() 设置 is_quitting_ = true → 窗口触发 beforeunload → 页面的 handler return false 阻止关闭 → 必须把 is_quitting_ 改回 false,否则下次 window-all-closed 会误判为"正在退出"从而强关。
这个 bug 在 Electron 早期版本里真实存在过。注释里的 "we think the quit is cancelled too" 就是那次修复留下的说明。
1.12 三张地图的补充:如何自己找答案
前面给了三张图。但真正工作时,你面对的是"这个行为到底是哪段代码做的"这种具体问题。这一节给一套可操作的方法。
1.12.1 从 JS API 反查 C++ 绑定
假设你想知道 app.getPath('userData') 的实现。
第一步,看 app.ts:1-2:
const { app } = process._linkedBinding('electron_browser_app');
export default app;
一句话,说明 app 完全是 C++ 对象,binding 名是 electron_browser_app。
第二步,搜这个 binding 名在 C++ 里的注册:
grep -rn "electron_browser_app" shell/
会找到 electron_api_app.cc 末尾的宏:
electron_api_app.cc:2274
NODE_LINKED_BINDING_CONTEXT_AWARE(electron_browser_app, Initialize)
第三步,看 Initialize 函数,找 getPath 的注册:
grep -n "getPath" shell/browser/api/electron_api_app.cc
通常是一个 .SetMethod("getPath", &App::GetPath) 之类的链式调用。
第四步,看 App::GetPath 的实现。
四步,五分钟。这个套路适用于 90% 的 API。
1.12.2 从事件名反查发射点
想知道 did-finish-load 什么时候发。
grep -rn "did-finish-load" shell/
或者更通用地搜事件名常量。Electron 的事件名大多是字符串字面量,直接搜得到:
grep -rn "\"did-finish-load\"" shell/browser/
会找到 api::WebContents 里的 Emit("did-finish-load"),然后看它在哪个回调里。
1.12.3 从行为差异反查补丁
如果某个行为和 Chrome 不一样,先去 patches/chromium/ 里找:
ls patches/chromium/ | grep -i "file_access\|same_origin"
补丁文件名通常是描述性的,allow_file_access_from_files 之类一眼就能认出来。
如果找不到,再搜 electron_browser_client.cc 里对应的虚函数。
1.12.4 从崩溃栈反查模块
Electron 的崩溃栈里会出现 electron::api::WebContents::... 这样的符号。命名空间 electron::api 对应 shell/browser/api/,electron:: 对应 shell/browser/ 或 shell/common/。
按命名空间找目录,是读 Chromium 系代码的基本功。
1.12.5 一个反直觉的建议:先读测试
spec/ 下有 1003 个测试文件。当你不确定某个行为时,测试比源码更快给出答案——因为测试直接表达了"期望行为"。
grep -rn "did-finish-load" spec/
会找到一批用例,告诉你这个事件在什么条件下触发、参数是什么、是否可取消。
源码告诉你"怎么实现的",测试告诉你"承诺了什么"。两者结合才是完整的事实。
1.13 十二个必读文件的导读
如果只能读十二个文件,读这些。每一个我都说明:它解决什么问题、读的时候盯住哪里、以及它最容易让人误解的地方。
1. electron_main_delegate.cc
它是什么:进程入口的"策略层",实现 content::ContentMainDelegate。
读什么:BasicStartupComplete 和 PreSandboxStartup 两个函数。前者是"还没有任何基础设施时能做什么",后者是"沙箱之前必须做完什么"。
易误解处:看到一大堆 #if BUILDFLAG(IS_*),容易以为这是"平台适配代码",随便跳过。实际上每一段都对应一个具体的平台约束,比如 MAS 构建的特殊开关、Linux root 检查、Windows 的 handle verifier 禁用。跳过它们,你就无法解释某些"只在某个平台上出现"的行为。
2. electron_browser_main_parts.cc
它是什么:主进程初始化的总调度,实现 content::BrowserMainParts。
读什么:PostEarlyInitialization 一个函数就够了。它是全仓库信息密度最高的函数之一,前面 1.10.4 节已经逐行拆过。
易误解处:容易把它当成"一堆初始化调用的清单"。实际上它的注释里藏着大量时序约束("必须在 V8 之前"、"必须在网络服务之前"、"等 ProxyResolverV8 之后")。这些注释比代码重要。
3. browser.cc
它是什么:app 模块的 C++ 后端,只有 340 行,但它是应用生命周期的中枢。
读什么:Quit、Exit、NotifyAndShutdown、OnWindowAllClosed 四个函数,以及 RunQuitClosure 那个小工具函数。
易误解处:容易以为 app.quit() 就是"关闭所有窗口"。实际上它是一条状态机路径:设置 is_quitting_ → 通知观察者(可被 before-quit 阻止)→ 关窗口 → 每个窗口可能被 beforeunload 阻止 → 如果全关了才 Shutdown。
4. electron_browser_client.cc:507-514
它是什么:2380 行,"Electron 版的 Chrome 浏览器策略"。整个 content 层的决策入口。
读什么:先读 OverrideWebPreferences(507 行起),这是理解"Electron 的网页和普通网页有什么不同"的最佳入口:
electron_browser_client.cc:507-514
void ElectronBrowserClient::OverrideWebPreferences(
content::WebContents* web_contents,
content::SiteInstance& main_frame_site,
blink::web_pref::WebPreferences* prefs) {
prefs->javascript_enabled = true;
prefs->web_security_enabled = true;
prefs->plugins_enabled = true;
prefs->dom_paste_enabled = false;
prefs->javascript_can_access_clipboard = false;
prefs->allow_scripts_to_close_windows = true;
prefs->local_storage_enabled = true;
prefs->allow_universal_access_from_file_urls =
electron::fuses::IsGrantFileProtocolExtraPrivilegesEnabled();
prefs->allow_file_access_from_file_urls =
electron::fuses::IsGrantFileProtocolExtraPrivilegesEnabled();
prefs->webgl1_enabled = true;
prefs->webgl2_enabled = true;
prefs->allow_running_insecure_content = false;
...
}
这里每一行都是一次"Electron 与 Chrome 的行为差异声明":
javascript_enabled = true强制开启(用户不能在webPreferences里关掉它,实际上会忽略);dom_paste_enabled = false、javascript_can_access_clipboard = false——这是安全默认值,剪贴板访问要通过 Electron 的clipboard模块;allow_scripts_to_close_windows = true——window.close()在 Electron 里可用,这在 Chrome 里受限;allow_file_access_from_file_urls受 fuse 控制——这就是 1.10.2 节说的"file://可以读file://"的最终落点,而且可以通过打包时的 fuse 关掉,提升安全性。
再看 AppendExtraCommandLineSwitches(583 行起)。它在每个子进程启动前被调用,做两件事:校验要启动的可执行文件是不是预期的那个(防止命令注入),然后追加 Electron 需要的开关。
那段校验代码很值得看:
electron_browser_client.cc:598-601
base::FilePath program =
base::MakeAbsoluteFilePath(command_line->GetProgram());
...
CHECK_EQ(program, child_path)
<< "Aborted from launching unexpected helper executable";
这是针对一类攻击的防御:如果攻击者能控制子进程的启动路径,就能让 Electron 启动任意程序。CHECK_EQ 在 release 构建里也会生效(不是 DCHECK),说明这是安全关键路径。
易误解处:容易以为这个文件只是"转发一堆回调"。实际上它承担了安全边界、平台差异、以及与 JS 层配置的对接三重职责。
5. electron_api_web_contents.cc
它是什么:6184 行,最大的单文件,webContents 的全部实现。
读什么:不要从头读。先读构造函数区(953、1005、1024 行有三个重载),理解"一个 WebContents 是怎么被造出来的";再读 WebContentsCreatedWithFullParams(1474 行),理解"别人(比如 window.open)创建的 WebContents 如何被接管"。
易误解处:容易以为这是个"API 实现文件"。实际上它是 Electron 与 content 层之间最厚的一层适配,12 个基类(见 1.3.2 节)说明了它的多重身份。
6. native_window.h
它是什么:跨平台窗口的纯虚接口。
读什么:数一数纯虚函数的数量,然后随便挑三个(SetTitle、Show、SetBounds),去 native_window_views.cc 和 native_window_mac.mm:685 里找各自实现,对比差异。
易误解处:容易以为"纯虚接口 = 行为一致"。实际上平台差异全在实现里:SetBounds 在 macOS 上要考虑 titlebar 高度,在 Windows 上要考虑 DPI 缩放,在 Linux 上要考虑窗口管理器是否支持客户端装饰。
7. node_bindings.cc
它是什么:1261 行,Node 与 Chromium 的接缝。
读什么:Initialize(691)、CreateEnvironment(843)、LoadEnvironment(1006)、JoinAppCode(1116)、UvRunOnce(1143)、EmbedThreadRunner(1192)。这六个函数串起来就是完整的 Node 集成机制。
易误解处:容易以为 Node 是"链接进来的库,调一下就行"。实际上这里有一整套生命周期编排:进程级初始化、Isolate 设置、Environment 创建、脚本加载、事件循环桥接。
8. wrappable.h
它是什么:C++ 对象与 v8::Object 的双向绑定基类。
读什么:GetWrapper 的实现,以及它如何通过 kWrapperInfo 这个静态成员把类型信息传给 gin。这是 gin 的类型擦除技巧。
易误解处:容易以为"Wrappable 就是让 C++ 对象有个 JS 壳"。实际上它还管生命周期:当 JS 对象被 GC,C++ 对象要不要删?答案由 wrapper 的 weak callback 决定,而 Electron 又在其上加了 Pinnable(手动钉住防删)。
9. lib/browser/init.ts
它是什么:121 行,主进程的 JS 启动脚本。
读什么:整篇。它做了七件事:设置 EventEmitter 原型、安装未捕获异常处理、改写 process.exit、加载 IPC 分发器、加载 RPC 服务器、读取 appPackage、加载用户入口。
易误解处:容易以为它只是"引导脚本"。实际上它定义了主进程的错误语义:为什么 uncaughtException 会弹一个原生对话框而不是退出?为什么 process.exit() 等同于 app.exit()?答案都在这里。
lib/browser/init.ts:15-20
process.on('uncaughtException', function (error) {
if (process.listenerCount('uncaughtException') > 1) return;
Promise.resolve().then(() => {
const { dialog } = require('electron') as typeof import('electron');
const stack = error.stack ? error.stack : `${error.name}: ${error.message}`;
dialog.showErrorBox('A JavaScript error occurred in the main process', 'Uncaught Exception:\n' + stack);
});
});
这段代码解释了那个著名的红色错误弹窗。注意 listenerCount > 1 的判断:如果你自己监听了 uncaughtException,Electron 就不弹窗了,交给你处理。
10. lib/renderer/init.ts:35-38
它是什么:180 行,渲染进程的启动脚本。
读什么:nodeIntegration 分支、Module.wrapper 的改写、以及末尾的 onPreloadsLoaded 删除逻辑。
易误解处:容易以为渲染进程的 Node 集成是"把 Node 全局变量挂上去"。实际上它还改写了 Module.wrapper:
lib/renderer/init.ts:35-38
Module.wrapper = [
'(function (exports, require, module, __filename, __dirname, process, global, Buffer) { ' +
'return function (exports, require, module, __filename, __dirname) { ',
'\n}.call(this, exports, require, module, __filename, __dirname); });'
];
为什么要包两层函数?注释解释了:为了让模块代码无法通过局部变量覆盖 process 和 Buffer。
单层 wrapper 的话,模块里写 var process = null 就会把全局的 process 遮住(因为参数名相同)。双层 wrapper 让内层函数的作用域里没有 process 参数,模块代码只能访问外层闭包里的 process。
这是一个用 JS 语言特性做的沙箱加固,成本极低,效果直接。
11. lib/browser/api/module-list.ts
它是什么:require('electron') 的模块表。
读什么:整篇,重点是每个条目的 loader 类型。
易误解处:容易以为这是个"导入清单"。实际上它决定了哪些 API 有 JS 包装层(可以打补丁、可以做参数规范化),哪些是裸 C++ 对象(行为完全由 C++ 决定)。
这个区分在排查问题时极其有用:如果某个 API 的参数处理很奇怪,先看它有没有 TS 包装。
12. std_converter.h
它是什么:293 行,标准库类型与 JS 值之间的转换规则。
读什么:随便挑几个 Converter<T> 特化,比如 std::set<T>、std::map<K,V>、std::u16string。
易误解处:容易以为"类型转换是自动的"。实际上每一个类型都需要显式特化,C++ 的 std::map 转成 JS 的普通对象(不是 Map),std::set 转成 JS 数组,这些选择都有语义后果。
这也解释了为什么 Electron API 的返回值形态有时"不太 JS":它们直接反映了 C++ 侧的类型。
阅读顺序建议
如果你只有一天时间,按这个顺序读:
lib/browser/init.ts (121 行,先看 JS 侧怎么起)
↓
lib/browser/api/module-list.ts (看清 API 的两种形态)
↓
shell/app/electron_main_delegate.cc (C++ 入口)
↓
shell/browser/electron_browser_main_parts.cc 的 PostEarlyInitialization
↓
shell/common/node_bindings.cc 的 LoadEnvironment + JoinAppCode
↓
shell/browser/browser.cc (生命周期状态机)
六步,大约 4 小时,你会建立起一个能自我解释的模型。之后遇到任何"为什么这样"的问题,都知道该往哪找。
1.14 十个高频问题的源码级回答
这一节收集十个几乎每周都有人在社区问的问题,每个答案都指向具体代码。你可以把它们当作本章的"验收测试"——如果每个答案你都能自己推出个大概,说明地图已经在脑子里了。
问题 1:为什么主进程里 window 是 undefined?
因为主进程没有 DOM,也没有 Blink。
主进程是一个 Chromium 的 "browser process",它只有 content 层和 Node 的 V8 环境。window 是 Blink 提供的全局对象,只在渲染进程里存在。主进程的全局对象是 Node 的 global。
有意思的是 Electron 并没有把 window 从主进程里"删掉"——它压根没被创建过。
验证方式:在主进程 console.log(typeof globalThis.Blob)。你会看到 function——因为 Node 24 提供了 Blob,但那是 Node 的实现,和浏览器的 Blob 不是同一个东西,虽然接口相似。
问题 2:为什么 process.type 在不同进程里值不同?
因为它就是 --type 命令行的映射。
grep -rn "process.type\|type\"" shell/common/api/electron_bindings.cc | head
electron_bindings.cc 在往 process 对象上挂属性时,会读当前进程类型。主进程是 "browser",渲染进程是 "renderer",utility process 是 "utility",GPU 进程是 "gpu"。
这个属性最常见的用途是在共享代码里做分支:
if (process.type === 'renderer') {
// 只在渲染进程执行
}
顺带一个陷阱:ELECTRON_RUN_AS_NODE 模式下,process.type 仍然是 "browser"——因为那个进程没有 --type 开关,Chromium 认为它是 browser process。process_util.h:19 里专门有个函数来处理这个歧义:
// True when this process is the ELECTRON_RUN_AS_NODE entry point (e.g. a
// child_process.fork()ed Node process). Such a process has no --type switch,
// so IsBrowserProcess() is also true for it; use this to tell the two apart.
bool IsRunningAsNode();
这段注释值得反复读。 它说明了一个真实的坑:process.type === 'browser' 并不等于"我是主进程",因为 fork 出来的 Node 子进程也满足这个条件。
问题 3:为什么打包之后 __dirname 指向 asar 里的路径,文件却读得到?
因为 Electron 给 asar 装了文件系统补丁。
asar 是一个归档格式(本质是把一堆文件拼成一个文件,加一个 JSON 索引)。Node 的 fs 模块本来不认识它。Electron 在 shell/common/asar/ 下实现了一个 "asar 文件系统",并替换了 Node 的 fs 内部实现:
shell/common/asar/
├── asar_util.cc 路径解析
├── archive.cc 归档读取
├── asar_file_validator.cc
└── ...
当 fs.readFileSync('/path/to/app.asar/index.html') 被调用时,Electron 会:
- 判断路径是否在 asar 归档内;
- 是的话,从归档里读对应字节;
- 否则走正常文件系统。
对 Node 的 fs 来说,这一切都是透明的。所以 __dirname 是一个看起来像普通路径的字符串,而读取它下面的文件也正常。
代价是:asar 里的文件不能用 mmap,也不支持写入。此外某些依赖 fs.stat 真实行为的库(比如判断是否符号链接)会出问题——这是 asarUnpack 存在的原因。
问题 4:为什么 nodeIntegration: true 时不建议再用 contextIsolation: true?
严格说这个组合是允许的,但它会产生一个诡异的状态:页面主世界有 Node,隔离世界也有 Node,但两者是不同的 require 实例。
结果是:你在 preload 里 require('fs') 拿到的模块对象,和页面里 require('fs') 拿到的不是同一个。如果这个模块内部有状态(比如缓存、连接池),就会出现"两份状态"。
更实际的问题是:contextIsolation: true 的目的是"让页面脚本拿不到 preload 的能力",而 nodeIntegration: true 等于"页面本来就有全部 Node 能力"——两者的目标直接矛盾,组合起来没有意义。
正确的做法是二选一:
- 需要页面直接访问 Node:
nodeIntegration: true+contextIsolation: false(老式写法,不推荐用于加载远程内容); - 需要安全隔离:
nodeIntegration: false+contextIsolation: true+preload里用contextBridge暴露最小接口。
问题 5:为什么 ipcRenderer.send 是同步返回、invoke 返回 Promise,但两者底层是同一条通道?
因为 send 只是"发出去了",不等结果;invoke 是"发出去了,并且期待一个回复"。
在 mojo 层面,两者都会走到 ElectronApiIPCService 的 Message 方法,区别在参数里有没有一个"回复通道"。invoke 会带一个 pending_receiver,主进程处理后通过它把结果送回来。
第 14 章会给出完整的 mojom 定义和调用链。
问题 6:为什么窗口 show: false 之后 ready-to-show 事件有时不触发?
因为 ready-to-show 依赖"首帧已绘制"。如果页面加载失败、或者被 will-navigate 拦截、或者渲染进程崩溃,首帧永远不会来,事件也就永远不触发。
源码里这个事件是从 WebContents 的某个观察者回调发出的(第 11 章会具体指出位置),条件判断相当严格。
实践建议:不要只依赖 ready-to-show,加一个超时兜底:
const timer = setTimeout(() => win.show(), 3000)
win.once('ready-to-show', () => { clearTimeout(timer); win.show() })
这不是"框架的缺陷",而是"事件语义本身就是条件性的"。理解条件,才能正确使用。
问题 7:为什么 webContents.send 在页面还没加载完时发不出去?
因为渲染进程还没有对应的 ipcRenderer 监听器,消息会落到"无人接收"的状态。
准确地说:IPC 消息是发给"渲染进程的某个 frame"的,如果那个 frame 还没准备好(导航还没提交),消息要么被排队、要么被丢弃,取决于发送时机和 API。
webContents.send 的文档里有一句"Send an asynchronous message to the renderer process via channel"——它不保证送达,只保证尽力而为。
可靠的模式是"渲染进程主动请求"(invoke),或者"等 did-finish-load 之后再发"。
问题 8:为什么同一个应用的两个窗口,localStorage 是共享的,但 sessionStorage 不共享?
因为 localStorage 的隔离维度是"origin + session(浏览器上下文)",而 sessionStorage 的隔离维度是"tab/frame 树"。
Electron 里,两个 BrowserWindow 默认共享同一个 session(session.defaultSession),所以 localStorage 共享。如果给其中一个窗口指定 partition: 'persist:other',它就有一个独立的 session,localStorage 也随之隔离。
sessionStorage 永远跟着 frame 走,所以在任何情况下都不共享。
这套语义完全继承自 Chromium,Electron 没有改动。
问题 9:为什么 app.getPath('userData') 在 app.ready 之前就能调用?
因为它不依赖 Chromium 的初始化,只依赖 PathService 的注册。
BasicStartupComplete 里就调了 electron::RegisterPathProvider(),userData 的路径在那时已经能算出来(应用名 + 平台约定目录)。
但注意:如果你在 ready 之前用 app.setName() 改了应用名,userData 的路径也会跟着变。 这个"路径随名称变化"的行为曾经导致过数据丢失(用户在 ready 前改名,结果读到了另一个空目录)。
问题 10:为什么 require('electron') 在渲染进程(nodeIntegration: true)里返回的对象,和主进程里的不完全一样?
因为模块表不一样。
lib/browser/api/module-list.ts:9 和 lib/renderer/api/module-list.ts:5 是两份不同的清单。渲染进程没有 app、BrowserWindow、Tray 这些概念(它们是主进程专属的),反过来主进程没有 ipcRenderer、contextBridge。
这个差异在 lib/common/api/module-list.ts:3 里还有一份"共享部分"——clipboard、nativeImage、shell 这些两边都能用。
三份清单,对应三种上下文。如果你在渲染进程里 require('electron').app 得到 undefined,不是 bug,是设计。
1.15 本章小结:三条主线
如果你只记住三件事,记这三条:
主线一:Electron 是"content 层的嵌入者"
Chromium 被设计成可嵌入的。content::ContentMainDelegate 是入口,四个 Content*Client 是策略接口,Electron 实现了它们。理解 Electron 的浏览器进程,就是理解 ElectronBrowserClient 那上百个虚函数各自在什么时候被调用。
主线二:Node 被切碎后重新编排
Node 的初始化流程在 Electron 里被拆成若干段:V8 初始化归 Electron、平台初始化归 Electron、Node 只负责自己的 Environment 创建。kNoInitializeV8、kNoInitializeNodeV8Platform 这些标志就是切割点。这也是为什么 Electron 里的 Node 行为与纯 Node 有差异。
主线三:JS 层是编译进二进制的
lib/ 下的 TypeScript 不会出现在用户的应用目录里。它们被打包成 7 个 bundle,转成 C++ 字符串常量,编进可执行文件。process._linkedBinding('electron_browser_app') 拿到的就是这个机制的另一半——C++ 侧的绑定注册。
理解这三条,后面 23 章都是在它们之上做展开。
1.16 练习题
不需要写代码,只需要打开源码找答案。做完这几题,你对仓库的熟悉程度会超过大多数 Electron 使用者。
1. 找一个 API 的三种形态。
挑 clipboard 这个模块,找出:它的 TS 实现在哪(lib/)、它的 C++ 后端在哪(shell/)、它在 module-list.ts 里用的是哪种 loader。然后解释为什么 clipboard 需要 TS 包装而不是直接暴露 C++。
提示:看 clipboard.ts,注意它对 write() 做了什么额外处理(提示:处理了多种参数形态)。
2. 追踪一个事件。
在 window-all-closed 事件触发时,代码路径是什么?从最后一个窗口的 Close() 开始,找到 WindowList 如何检测"没有窗口了",再找到 Browser::OnWindowAllClosed(),最后看它如何发射 JS 事件。
提示:window_list.cc、browser.cc:316。
3. 解释一个差异。
为什么 process.versions.electron 存在,但你在纯 Node 里跑同样的代码就报错?找到给 process.versions 加字段的代码。
提示:搜索 versions 在 shell/common/ 下,注意 electron_bindings.cc。
4. 验证一个结论。
本章说 webContents 相关代码有 6184 行。验证一下:
wc -l shell/browser/api/electron_api_web_contents.cc
然后找出这个文件里最大的三个函数,猜猜它们各自负责什么。
5. 找一处历史包袱。
BrowserView 已被标记废弃,但代码还在。找出它的 JS 实现与 C++ 实现,看看它是如何"复用" WebContentsView 的(这是一个典型的向后兼容适配层)。
提示:browser-view.ts。
6. 亲手验证"JS 编译进二进制"。
在一台装了 Electron 的机器上,找到 dist/ 目录:
ls node_modules/electron/dist/
里面有没有 lib/ 目录?没有。然后尝试:
strings <可执行文件> | grep -c "electron/js2c"
你会看到 electron/js2c/browser_init 之类的字符串。这就是 js2c 的产物。
1.17 下一章的入口
本章建立的模型里,有一个东西一直在背景里:进程。
我们说"主进程初始化"、"渲染进程加载 preload"、"utility process 的 Node 受限",但一直没有正面回答:这些进程是怎么被创建的?谁来创建?创建之后它们之间怎么建立通信?
这就是第 2 章的内容。它会回答:
- 为什么 Electron 需要四种进程(browser / renderer / GPU / utility),而不是两种?
- zygote 是什么,为什么只有 Linux 有?
--type=renderer这条命令行是怎么被消费的,从字符串到"我是谁"的判定发生在哪个函数?- 为什么渲染进程可以有 Node 也可以没有,这个"有/没有"是在哪一层决定的?
- 进程崩溃之后,谁会知道?重建策略是什么?
读第 2 章时请带着本章的一张图:1.7.1 的进程地图。那一章会把它填满细节。
一个术语约定
在进入第 2 章之前,先把本书的术语固定下来,避免后面产生歧义。Electron 社区里这几个词经常混用:
| 本书用法 | 指什么 | 常见混用 |
|---|---|---|
| 主进程 / browser process | --type 为空的那个进程,跑 main.js | 有人叫"服务端"、"后端" |
| 渲染进程 / renderer | --type=renderer,跑 Blink | 有人叫"前端进程"、"页面进程" |
| GPU 进程 | --type=gpu-process,跑 viz 合成与 GL | 常被忽略 |
| utility process | --type=utility,Chromium 的通用子进程容器 | 与 utilityProcess.fork() 的结果常混淆 |
| Node 环境 | 一个 node::Environment 实例 | 有人直接说"Node 进程",不准确 |
| 隔离世界 / isolated world | Blink 的独立 JS 上下文 | 与"进程隔离"混淆 |
| 浏览器上下文 / BrowserContext | 一份存储与网络状态的集合,对应 JS 的 session | 与"浏览上下文(browsing context)"混淆 |
最后一行尤其需要强调:session 在 Electron 里对应 content::BrowserContext,不是 W3C 规范里的 "browsing context"(那是 frame 树)。 两个概念重名但完全无关,读 Chromium 文档时容易搞错。
本书严格使用左列术语,需要引用 API 名时保持原样。