《Electron 45.2.3 内核解剖》第 5 章 主进程启动链路:从 `main()` 到 `app ready`

1 阅读1小时+

《Electron 45.2.3 内核解剖》第 5 章 主进程启动链路:从 main() 到 app ready

这一章只回答一个问题:你在 main.js 顶层写下 app.whenReady().then(...) 的那一刻,到那个 .then 真正执行之间,引擎里发生了多少件事。

答案不是"几件",是四十七个可辨识的阶段。本章会把它们按时间顺序排出来,并且每一段都给出源码位置。


5.0 一个让人困惑的现象

先看一段最普通的 Electron 主进程代码:

const { app, BrowserWindow } = require('electron')
console.log('A: 模块顶层')
console.log('B: app 存在吗?', typeof app)
console.log('C: isReady?', app.isReady())
app.whenReady().then(() => {
	console.log('D: ready 到了')
})
console.log('E: 顶层结束')

如果你真的跑一遍,输出是:

A: 模块顶层
B: app 存在吗? object
C: isReady? false
E: 顶层结束
D: ready 到了

三件事值得注意:

**第一,require('electron') 在 main.js 顶层就能拿到完整的 app 对象。**不是"等一会儿才有",是同步就有。typeof app === 'object',app.getVersion()、app.getPath('userData') 这时候都能调用。

**第二,app.isReady() 是 false。**API 全都在,但"就绪"这件事还没发生。

**第三,whenReady() 返回的 Promise 在顶层代码执行完之后才 resolve。**注意顺序:E 在 D 之前。这不是"异步所以晚一点"那么简单——whenReady() 在你的代码运行时就已经知道"我还没 ready",它注册了一个待兑现的 Promise,然后在 C++ 侧某个时刻被 resolve。

那么问题来了:

如果 ready 还没到,那 electron 模块是谁创建出来的?它背后的 app 对象在什么时候、被谁构造的?

答案在 lib/browser/init.ts 和 electron_browser_main_parts.cc 之间。而这两者之间的来回,就是本章的主线。

5.0.1 一个更尖锐的问题

再看一段:

const { app } = require('electron')
console.log(app.getPath('userData'))

这行代码在 ready 之前执行,但它返回了一个真实存在的路径——不是空字符串,不是 undefined。

可是 userData 目录的最终值取决于 app.setName()、app.setPath('userData', ...)。而这些 API 通常在 ready 之后才调用。

也就是说:**getPath('userData') 在 ready 之前就能用,但它的值可能不是你最终想要的那个。**这解释了为什么 Electron 文档反复强调"app.setPath 要在 ready 之前调用"——因为在 ready 之后,很多东西已经用那个路径初始化完了。

这类"API 早就存在、但语义还没定型"的状态,是本章要解释的核心现象。

5.0.2 本章的走法

我们会沿着一条真实的时间线走:

[平台入口] main() / wWinMain / ElectronMain
	↓
[ContentMain]  content 层的初始化骨架
	↓
[ContentMainDelegate]  Electron 插入的 17 个钩子
	↓
[BrowserMainParts]  Electron 的 12 个阶段
	↓
[Node 引导]  NodeBindings + JavascriptEnvironment
	↓
[JS 引导]  lib/browser/init.ts(121 行)
	↓
[用户代码]  你的 main.js
	↓
[JoinAppCode]  C++ 等 JS 把 app 代码加载完
	↓
[ready]  DidFinishLaunching

这条线上有两次"控制权反转",需要特别注意:

第一次反转:C++ 调 JS。PostEarlyInitialization 里,C++ 主动去执行 lib/browser/init.ts 这个 JS 文件。这时候是 C++ 在驱动 JS。

第二次反转:JS 阻塞 C++。JoinAppCode 里,C++ 停在一个 while 循环里,泵 uv 事件循环,等 JS 调用 process.appCodeLoaded() 才继续。这时候是 JS 在驱动 C++。

这两次反转之间,就是你的 main.js 执行的那段时间。


5.1 三个平台,三个入口,一副骨架

Electron 的可执行文件在不同平台上的入口函数长得完全不一样。但骨架是同一副。

5.1.1 Linux:main() 只有 22 行

electron_main_linux.cc:44-51 第 44 到 66 行:

int main(int argc, char* argv[]) {
	FixStdioStreams();
	PreallocateFileDescriptorTable();
	// Chromium expects the original argv in its original memory location
	// to update /proc/<pid>/cmdline.
	const char** original_argv = UNSAFE_BUFFERS(const_cast<const char**>(argv));
	argv = uv_setup_args(argc, argv);
	base::CommandLine::Init(argc, argv);
	electron::ElectronCommandLine::Init(argc, argv);
	if (electron::fuses::IsRunAsNodeEnabled() && IsEnvSet(electron::kRunAsNode)) {
	base::i18n::InitializeICU();
	base::AtExitManager atexit_manager;
	return electron::NodeMain();
	}
	electron::ElectronMainDelegate delegate;
	content::ContentMainParams params{&delegate};
	params.argc = argc;
	params.argv = original_argv;
	return content::ContentMain(std::move(params));
}

逐行看,每一行都有理由。

FixStdioStreams() —— 定义在 uv_stdio_fix.cc(28 行)。它解决的问题是:Electron 在很多场景下不是从终端启动的(从 .desktop 文件、从文件管理器双击、从 systemd),此时 stdin/stdout/stderr 可能是无效的 fd。而 libuv 在初始化时会检查这三个 fd,如果它们指向一个已经不存在的终端,uv_tty_init 会失败,进而影响整个 Node 初始化。

FixStdioStreams 的做法是把无效的 fd 重定向到 /dev/null。

这个修复的存在说明一件事:**Electron 的启动路径比 Chrome 宽得多。**Chrome 总是从图形界面或终端启动,Electron 应用可能是任何东西启动的。

PreallocateFileDescriptorTable() —— 源码里有注释:

electron_main_linux.cc:37-39

// Linux grows the descriptor table in powers of two and, once the process has
// threads, each expansion waits out an RCU grace period (tens of ms). Growing
// it to 1024 entries now is free; content's zygote does the same for the
// children it forks.
void PreallocateFileDescriptorTable() {
	base::ScopedFD high_fd(
	HANDLE_EINTR(fcntl(STDIN_FILENO, F_DUPFD_CLOEXEC, 512)));
}

Linux 的 fd 表是按 2 的幂扩展的。每次扩展,内核要做一次 RCU 同步——如果进程已经有多线程,这个同步要等所有线程都不在 RCU 读临界区,可能要几十毫秒。

在 main() 的第一行做一次 F_DUPFD_CLOEXEC 到 512,就把表一次性撑到 1024 项。后续所有 fd 分配都不会触发扩展。

代价是:一个多余的 fd(high_fd 在作用域结束时关闭)。收益是:启动路径上少了几十毫秒的潜在停顿。

这个技巧 Chromium 的 zygote 也用(注释里说了),Electron 只是把它搬到了主进程的 main()。

original_argv 与 uv_setup_args —— 注释写得很清楚:

// Chromium expects the original argv in its original memory location
// to update /proc/<pid>/cmdline.

uv_setup_args(argc, argv) 是 libuv 的函数,它会把 argv 复制到一块新内存(因为 libuv 要修改它,把 argv[0] 换成进程名)。返回值是新的 argv 指针。

但 Chromium 在需要更新 /proc/self/cmdline 时,会去写原始 argv 所在的内存。如果 params.argv 传的是 libuv 复制后的那份,Chromium 写的就不是 /proc 实际读取的那块,ps 看到的进程名就不会更新。

所以 Electron 保存了 original_argv,传给 ContentMainParams 的是原始指针。而 base::CommandLine::Init 用的是 libuv 处理过的 argv(因为它需要 argv[0] 是规范化后的进程名)。

这是一个非常细的细节,但它是"为什么 ps aux | grep electron 能看到 --type=renderer"这种可观测行为的基础。

ElectronCommandLine::Init —— 这是 Electron 自己的一层。为什么 base::CommandLine 不够?

因为 Chromium 的 base::CommandLine 会在某些时机丢掉它不认识的开关,或者重新排列参数。而 Electron 需要保留完整的、原始的、按顺序的 argv——因为渲染进程的启动参数需要通过命令行传给子进程,而 Node 的 process.argv 要还原成用户看到的样子。

第 2 章讲过 process.argv 在 Electron 里的特殊处理:主进程的 process.argv 是 [electron, ...userArgs],不是 [electron, ..., userArgs] 中间夹着一堆 Chromium 开关。这个"剔除"就是在 ElectronCommandLine 里做的。

run_as_node 短路 —— 这三行(加 IsEnvSet 检查)决定了 ELECTRON_RUN_AS_NODE=1 的行为:

electron_main_linux.cc:55-58

if (electron::fuses::IsRunAsNodeEnabled() && IsEnvSet(electron::kRunAsNode)) {
	base::i18n::InitializeICU();
	base::AtExitManager atexit_manager;
	return electron::NodeMain();
}

两个条件:

  1. fuses::IsRunAsNodeEnabled() —— fuse 开关。如果构建时关掉了 run_as_node fuse,这个分支在二进制里就不存在(或者永远不成立)。
  2. ELECTRON_RUN_AS_NODE 环境变量非空。

注意 IsEnvSet 的实现(第 28-31 行):

[[nodiscard]] bool IsEnvSet(const base::cstring_view name) {
	const char* const indicator = getenv(name.c_str());
	return indicator && *indicator;
}

*indicator 这一项意味着 空字符串不算"设置"。ELECTRON_RUN_AS_NODE= 不会触发 Node 模式。这是一个细节设计:有些工具会把未使用的环境变量设成空字符串,如果空字符串也生效,electron 会意外地变成 node。

AtExitManager —— 这个也是必需的。Chromium 的 base::AtExitManager 是一个栈式的退出回调注册表,它要求每个线程最多一个实例,且必须在 base::CommandLine 之前存在(因为有些早期初始化会注册退出回调)。

正常路径下,AtExitManager 由 ContentMain 内部的 ContentMainRunnerImpl 创建。但 NodeMain() 不走 ContentMain,所以 Electron 必须自己创建一个。

注意它的作用域:在 if 块内部。所以它只在 Node 模式下存在,正常路径下不会重复创建(重复创建会 CHECK 失败)。

最后三行:delegate 与 ContentMain。

electron_main_linux.cc:61-65

electron::ElectronMainDelegate delegate;
content::ContentMainParams params{&delegate};
params.argc = argc;
params.argv = original_argv;
return content::ContentMain(std::move(params));

delegate 是栈对象。它的生命周期覆盖整个 ContentMain 调用。这一点很重要:ContentMain 内部会多次回调 delegate 的虚函数,如果 delegate 被提前析构,就是悬垂指针。

ContentMain 的返回值是进程退出码。

5.1.2 Windows:wWinMain 多了五个分支

electron_main_win.cc:157-158 有 243 行,是三个平台里最长的。多出来的部分全是 Windows 特有的分支。

骨架仍然是:stdio → argv → run_as_node → delegate → ContentMain。但中间插了:

分支一:base::RouteStdioToConsole(false)。

electron_main_win.cc:157-158

// Make sure the output is printed to console.
if (run_as_node || !IsEnvSet("ELECTRON_NO_ATTACH_CONSOLE"))
	base::RouteStdioToConsole(false);

Windows 的 GUI 子系统程序(/SUBSYSTEM:WINDOWS)默认没有控制台。如果你从 cmd 里启动一个 Electron 应用,console.log 的内容不会出现在 cmd 里——因为进程根本没有 attach 到父控制台。

RouteStdioToConsole 会调用 AttachConsole(ATTACH_PARENT_PROCESS) 把 stdout 接到父进程的控制台上。

ELECTRON_NO_ATTACH_CONSOLE 环境变量可以关掉这个行为——因为 attach 到父控制台会有一个副作用:如果父进程是 cmd,Electron 的退出会让 cmd 提前返回提示符。有些工具(比如 npm scripts)不喜欢这个。

注释里的 run_as_node || 说明:Node 模式下必须 attach,因为 Node 的整个价值就在于 stdout/stderr(console.log、管道输出)。

分支二:crashpad-handler 进程。

electron_main_win.cc:172-174

if (process_type == crash_reporter::switches::kCrashpadHandler) {
	...
	int crashpad_status = crash_reporter::RunAsCrashpadHandler(
	*command_line, user_data_dir, kProcessType, kUserDataDir);
	...
	return crashpad_status;
}

Crashpad 在 Windows 上是一个独立的可执行文件(crashpad_handler.exe)。但在 Electron 里,它是同一个 electron.exe 的一个进程类型——通过 --type=crashpad-handler 区分。

为什么不用独立的 exe?因为打包体积。一个 Electron 应用已经有 5 个 helper(renderer/gpu/utility/plugin/crashpad),如果每个都是独立的 exe,安装包里会多出几 MB 的重复代码。

这个分支里的 ExitCodeWatcher 值得看一眼:它 DuplicateHandle 拿到父进程句柄,然后监视父进程退出。父进程死了,crashpad-handler 也要退出——否则会留下僵尸进程。

分支三:SetProcessShutdownParameters。

electron_main_win.cc:210-211

if (!process_type.empty()) {
	// Have Windows shut child processes down after the browser at logoff and
	// shutdown, as Chrome does, so the browser never watches them die.
	::SetProcessShutdownParameters(0x280 - 1, SHUTDOWN_NORETRY);
}

Windows 关机/注销时,系统会按 SetProcessShutdownParameters 设定的顺序终止进程。数字越小越晚被终止。

0x280 - 1 是 0x27F,比默认值(0x280)小一级——意思是"比默认更晚关"。配合 SHUTDOWN_NORETRY(不显示"此程序阻止关机"对话框),保证子进程在 browser 之后被关掉。

注释说了原因:"so the browser never watches them die"。如果子进程先死,browser 会收到 RenderProcessExited,走崩溃处理逻辑——在关机过程中做这些是浪费,而且可能卡住。

分支四:base::win::AllowDarkModeForApp(true)。

// access ui native theme here to prevent blocking calls later
base::win::AllowDarkModeForApp(true);

这一行看起来很怪——"access ui native theme here to prevent blocking calls later"。

背景:Windows 的深色模式检测需要读注册表(AppsUseLightTheme)。如果第一次读发生在 UI 线程的某个敏感时刻(比如创建窗口时),会阻塞。

在 wWinMain 里提前读一次,把值缓存起来,后续就不会阻塞。

分支五:InitializeSandboxInfo 与 utility 进程的强制终止。

electron_main_win.cc:227-231

sandbox::SandboxInterfaceInfo sandbox_info = {nullptr};
content::InitializeSandboxInfo(&sandbox_info);
// ... ContentMain ...
// System DLLs loaded into utility processes crash in their DLL_PROCESS_DETACH
// handlers during CRT exit, so leave the way Chrome does: without running it.
// Node utility processes keep the normal exit for their addons' handlers.
if (process_type == kUtilityProcess &&
	command_line->GetSwitchValueASCII(kUtilitySubType) != kNodeService) {
	base::Process::TerminateCurrentProcessImmediately(rc);
}

最后这几行非常精彩。它说的是:

非 Node 的 utility 进程,不要走正常的 CRT 退出流程,直接 TerminateProcess。

为什么?因为 utility 进程里加载了一些系统 DLL,这些 DLL 的 DLL_PROCESS_DETACH 处理器在退出时会崩溃。这是 Windows 上的一个老问题:某些 DLL 假设宿主进程的生命周期和它自己的假设一致,退出时访问已经释放的东西。

Chrome 的应对就是"不跑 CRT 退出"。Electron 学了过来。

但注意那个例外:!kNodeService。Node 的 utility 进程必须走正常退出,因为 Node 的原生模块(.node 文件)可能在 DLL_PROCESS_DETACH 或者 atexit 里做清理。跳过这些清理会导致资源泄漏或者数据损坏。

这个 if 是"平台怪癖"和"运行时正确性"之间的一次精确权衡。

5.1.3 macOS:三层入口

macOS 最复杂,因为它有三个不同的可执行文件,走三条不同的路径。

路径一:主应用的 main()(electron_main_mac.cc:70-77)。

int main(int argc, char* argv[]) {
	FixStdioStreams();
	if (electron::fuses::IsRunAsNodeEnabled() && IsEnvSet(electron::kRunAsNode)) {
	return ElectronInitializeICUandStartNode(argc, argv);
	}
#if defined(HELPER_EXECUTABLE)
	if (!HasProcessType(argc, argv)) {
	std::cerr << "This is a helper executable and cannot be launched directly; "
				"it requires a --type argument from the browser process."
			<< std::endl;
	return EX_USAGE;
	}
#endif
#if defined(HELPER_EXECUTABLE) && !IS_MAS_BUILD()
	// Seatbelt 沙箱初始化
	uint32_t exec_path_size = 0;
	int rv = _NSGetExecutablePath(nullptr, &exec_path_size);
	...
	sandbox::SeatbeltExecServer::CreateFromArgumentsResult seatbelt =
	sandbox::SeatbeltExecServer::CreateFromArguments(exec_path.get(), argc, argv);
	if (seatbelt.sandbox_required) {
	if (!seatbelt.server) FatalError("Failed to create seatbelt sandbox server.");
	if (!seatbelt.server->InitializeSandbox()) FatalError("Failed to initialize sandbox.");
	}
#endif
	return ElectronMain(argc, argv);
}

三个 #if 把"主应用"和"helper 应用"分开了。同一个 main() 函数,编译成不同的可执行文件时,HELPER_EXECUTABLE 宏的取值不同。

HasProcessType(argc, argv) 检查 --type= 前缀。helper 应用必须带这个参数——因为它只应该由 browser 进程启动。如果你手动双击 Electron Helper (Renderer).app,会看到那句错误提示。

路径二:ElectronMain()(electron_library_main.mm:70-77)。

int ElectronMain(int argc, char* argv[]) {
	if (!HasProcessTypeSwitch(argc, argv))
	electron::PrefetchFrameworkFilesIfCold();
	argv = uv_setup_args(argc, argv);
	base::CommandLine::Init(argc, argv);
	electron::ElectronCommandLine::Init(argc, argv);
	electron::ElectronMainDelegate delegate;
	// Ensure that Bundle Id is set before ContentMain.
	// Refs https://chromium-review.googlesource.com/c/chromium/src/+/5581006
	delegate.OverrideChildProcessPath();
	delegate.OverrideFrameworkBundlePath();
	delegate.SetUpBundleOverrides();
	content::ContentMainParams params{&delegate};
	params.argc = argc;
	params.argv = UNSAFE_BUFFERS(const_cast<const char**>(argv));
	return content::ContentMain(std::move(params));
}

这里有 macOS 特有的三件事:

PrefetchFrameworkFilesIfCold() —— 冷启动时预读 framework 里的文件。macOS 的 .app/Contents/Frameworks/Electron Framework.framework 里有几百个文件,第一次启动时它们可能都在磁盘的冷区。预读能把启动时间缩短几百毫秒。

注意条件 !HasProcessTypeSwitch —— 只有 browser 进程预读。子进程的启动速度取决于 browser,browser 先把它自己的文件读热了,子进程共享同一份 page cache。

OverrideChildProcessPath / OverrideFrameworkBundlePath / SetUpBundleOverrides —— 这三个是 base::apple::BundleLocations 的覆盖。

Chromium 用 base::apple::OuterBundle()、FrameworkBundle() 这些函数来找资源。默认实现是通过 [NSBundle mainBundle] 往上找。但 Electron 的目录结构和 Chrome 不同:

MyApp.app/
	Contents/
	MacOS/MyApp
	Frameworks/
	Electron Framework.framework/
		Versions/A/Electron Framework
		Resources/
	MyApp Helper.app/
	MyApp Helper (GPU).app/
	...

Electron Framework.framework 里既有代码也有资源(resources.pak、icudtl.dat、v8_context_snapshot.bin)。而 NSBundle mainBundle 指向的是 MyApp.app,不是 framework。

所以必须显式覆盖:告诉 Chromium"资源在 framework 里,不在 main bundle 里"。

注释里的那个 CL 链接(chromium-review.googlesource.com/c/chromium/src/+/5581006)说明:上游在某个版本改了 Bundle Id 的读取时机,必须在 ContentMain 之前设好,否则 ContentMain 里的某些初始化会读到错误的 bundle id。

路径三:ElectronAppShimMain()。

electron_library_main.mm:112-119

int ElectronAppShimMain(int argc, char* argv[]) {
	const base::FilePath host_bundle_path = HostBundlePathFromLoadedFramework();
	CHECK(!host_bundle_path.empty())
	<< "An app shim must load the framework from inside its host app";
	// The main bundle is the shim's; resources come from the host's.
	base::apple::SetOverrideOuterBundlePath(host_bundle_path);
	base::apple::SetOverrideFrameworkBundlePath(
	host_bundle_path.Append("Contents")
		.Append("Frameworks")
		.Append(ELECTRON_PRODUCT_NAME " Framework.framework"));
	base::CommandLine::Init(argc, argv);
	base::CommandLine::ForCurrentProcess()->AppendSwitchASCII(
	"type", electron::app_shim::kProcessType);
	electron::AppShimMainDelegate delegate(host_bundle_path);
	content::ContentMainParams params{&delegate};
	return content::ContentMain(std::move(params));
}

app shim 是 macOS 的一个特殊机制。当一个 Electron 应用被注册为某个协议(myapp://)或者文件类型的处理器时,系统需要知道"用什么应用打开"。但 Electron 的 helper 不是独立的 .app,系统无法直接启动它。

app shim 就是一个极小的 .app,它的 Info.plist 里声明的 URL scheme 指向自己,而它的可执行文件会加载主应用的 framework 然后启动。

HostBundlePathFromLoadedFramework() 用 dladdr 反查自己是从哪个 framework 加载的,然后往上走三级找到宿主 .app。这个"往上走"的循环写得很小心:

base::FilePath path = base::MakeAbsoluteFilePath(base::FilePath(info.dli_fname));
// <host>.app/Contents/Frameworks/<name>.framework/Versions/A/<name>
while (!path.empty() && path != path.DirName() &&
	path.Extension() != ".framework") {
	path = path.DirName();
}
if (path.Extension() != ".framework")
	return {};
path = path.DirName().DirName().DirName();
return path.Extension() == ".app" ? path : base::FilePath();

注意 path != path.DirName() 这个条件——它是防死循环的(根目录的 DirName() 返回自己)。

AppendSwitchASCII("type", kProcessType) 这一行把 shim 伪装成一个子进程类型。这样 ContentMain 里的某些"我是不是 browser 进程"的判断就不会把它当成 browser。

5.1.4 三个入口的共同点

把三份代码叠在一起,共同的骨架是:

1. FixStdioStreams()                    // 修 stdio
2. uv_setup_args(argc, argv)            // libuv 接管 argv
3. base::CommandLine::Init              // Chromium 的命令行
4. ElectronCommandLine::Init            // Electron 的命令行(保留原始顺序)
5. if (run_as_node fuse && env) NodeMain()   // 短路
6. ElectronMainDelegate delegate        // 栈对象
7. content::ContentMain(params)         // 进入 content

七步。这七步的顺序不能变,原因分别是:

  • 1 必须在 2 之前:libuv 初始化要看 fd
  • 2 必须在 3 之前:CommandLine::Init 会用 libuv 处理过的 argv
  • 3 必须在 7 之前:ContentMain 里到处在读命令行
  • 5 必须在 6 之前:NodeMain 不创建 delegate,如果 delegate 先创建了,栈上会多一个对象(虽然无害,但语义上不对)
  • 6 必须在 7 之前:ContentMainParams 持有 delegate 的指针

这个顺序在三个平台上完全一致。差异只在"中间插了哪些平台特有的分支"。


5.2 NodeMain():短路之后是另一套世界

ELECTRON_RUN_AS_NODE=1 之后,进程变成普通 Node 运行时。node_main.cc(388 行)做五件事:初始化 ICU、初始化 V8 平台、解析 Node 命令行、创建 Environment、跑脚本或 REPL。

和正常路径最大的区别是:不创建 ElectronMainDelegate,不进 content::ContentMain。所以这个进程里没有 Browser、没有 ElectronBrowserMainParts、没有 NodeBindings,也没有任何 Chromium 的消息循环——只有 Node 的一切。

两个实际用途:(1)用应用自带的 Node 跑脚本(用户机器上可能没装 Node,npx electron script.js 走的就是这条路);(2)构建工具(electron-builder 之类需要在构建时跑 Node,用内置版本保证一致性)。

这也是唯一完全不碰 Chromium 的入口,启动最快(30ms 量级,正常路径 200ms+)。


5.3 ContentMain 与十七个钩子

content::ContentMain 是 Chromium 提供的"应用启动骨架"。它的签名是:

int ContentMain(ContentMainParams params);

ContentMainParams 里有一个 ContentMainDelegate* delegate。这个 delegate 就是 Electron 插入 Chromium 启动流程的唯一通道。

ElectronMainDelegate 继承了 content::ContentMainDelegate,实现了 17 个虚函数。这 17 个虚函数被 ContentMain 在特定时刻调用,构成了 Electron 的"启动时间轴"。

5.3.1 完整时序

下面这条时间线是从 content_main_runner_impl.cc 的调用顺序 + ElectronMainDelegate 的实现推导出来的。左侧是 content 层的阶段,右侧是 Electron 在这个阶段做了什么。

┌─ ContentMainRunnerImpl::Initialize
│
├─ [1] BasicStartupComplete()                 ← Electron: 11 件事
│      ├─ Windows: v8_crashpad_support::SetUp()
│      ├─ ELECTRON_ENABLE_STACK_DUMPING
│      ├─ ELECTRON_DISABLE_SANDBOX → --no-sandbox
│      ├─ TracingSamplerProfiler::CreateOnMainThread()
│      ├─ chrome::RegisterPathProvider()
│      ├─ electron::RegisterPathProvider()
│      ├─ ContentSettingsPattern 白名单
│      ├─ Windows: _set_invalid_parameter_handler / DisableHandleVerifier / PinUser32
│      ├─ Linux: root + 沙箱 → LOG(FATAL)
│      └─ MAS: --disable-gpu-memory-buffer-compositor-resources
│
├─ [2] PreSandboxStartup()                    ← Electron: 8 件事
│      ├─ --user-data-dir 覆盖 DIR_USER_DATA
│      ├─ 日志预初始化(非 Windows)
│      ├─ crash_reporter::InitializeCrashKeys()
│      ├─ 子进程需要时 LoadResourceBundle()
│      ├─ 非 browser 进程初始化 crashpad
│      ├─ crash_keys::SetCrashKeysFromCommandLine()
│      ├─ browser: --allow-file-access-from-files
│      └─ browser: Ozone 平台初始化
│
├─ [3] 沙箱初始化(平台相关,非 delegate)
│
├─ [4] SandboxInitialized(process_type)       ← Electron: Windows 日志正式初始化
│
├─ [5] PreBrowserMain()                       ← Electron: FieldTrialList + Mojo
│      ├─ new FieldTrialList()(永不释放)
│      ├─ InitializeFeatureList()
│      ├─ content::InitializeMojoCore()
│      ├─ Mac: RegisterAtomCrApp()
│      └─ Linux: ExtractXdgActivationTokenFromEnv()
│
├─ [6] CreateContentClient()                  ← Electron: ElectronContentClient
│
├─ [7] BrowserMain 开始
│      ├─ [7a] PostEarlyInitialization()      ← Electron delegate: 内存系统
│      ├─ [7b] ElectronBrowserMainParts 构造
│      ├─ [7c] PreEarlyInitialization()
│      ├─ [7d] PostEarlyInitialization()      ← ★ Electron 最重要的一段
│      ├─ [7e] PreCreateThreads()
│      ├─ [7f] PostCreateThreads()
│      ├─ [7g] ToolkitInitialized()
│      ├─ [7h] PreCreateMainMessageLoop()
│      ├─ [7i] PreMainMessageLoopRun()        ← ★ ready 在这里发射
│      ├─ [7j] WillRunMainMessageLoop()
│      ├─ [7k] 主消息循环运行
│      ├─ [7l] PostMainMessageLoopRun()
│      └─ [7m] PostDestroyThreads()
│
├─ [8] CreateContentBrowserClient()           ← Electron: ElectronBrowserClient
├─ [9] CreateContentGpuClient()               ← Electron: ElectronGpuClient
├─ [10] CreateContentRendererClient()         ← Electron: Sandboxed 或非 Sandboxed
├─ [11] CreateContentUtilityClient()          ← Electron: ElectronContentUtilityClient
├─ [12] RunProcess()                          ← Electron: relauncher 分支
├─ [13] ShouldCreateFeatureList()
├─ [14] ShouldInitializeMojo()
├─ [15] ShouldLoadV8Snapshot()
├─ [16] ShouldLockSchemeRegistry()
└─ [17] ZygoteForked()(仅 Linux)

注意几个不直观的地方:

CreateContentBrowserClient 在列表里排第 8,但实际调用时机很早——它在 BrowserMain 开始之前就要被调用,因为 content 层需要知道用哪个 Client。上面这个列表是按"Electron 实现顺序"排的,不是严格的时间顺序。真实顺序里,CreateContent*Client 系列在 [6] 之后、[7] 之前。

**PostEarlyInitialization 出现了两次。**一次是 delegate 的([7a]),一次是 BrowserMainParts 的([7d])。它们不是同一个函数——delegate 的那个是 content::ContentMainDelegate::PostEarlyInitialization,BrowserMainParts 的那个是 content::BrowserMainParts::PostEarlyInitialization。

这个重名不是巧合,是 Chromium 的设计:ContentMainDelegate 的钩子是"进程级"的,BrowserMainParts 的钩子是"主消息循环级"的。前者在所有进程类型里都会被调用,后者只在 browser 进程里。

Electron 在两个地方都做了事:

  • delegate 侧:InitializeMemorySystem()(内存观测,进程级)
  • parts 侧:整个 Node + JS 的引导(只有 browser 进程需要)

5.3.2 BasicStartupComplete:十一件事,每一件都有理由

electron_main_delegate.cc 第 177-245 行。这是整个启动链路里"密度最高"的一个函数——58 行,11 个动作。

动作 1(Windows):v8_crashpad_support::SetUp()。

#if BUILDFLAG(IS_WIN)
	v8_crashpad_support::SetUp();

V8 有自己的崩溃处理器(用于生成可读的 JS 栈)。Crashpad 需要知道 V8 的栈布局,才能把 V8 的帧翻译出来。SetUp() 把 V8 的处理器注册到 Crashpad 的异常处理链里。

这件事必须在任何 V8 代码运行之前做——所以放在 BasicStartupComplete,这是最早的可插入点。

动作 2(Windows):std::wcout << std::endl。

electron_main_delegate.cc:185-186

	// On Windows the terminal returns immediately, so we add a new line to
	// prevent output in the same line as the prompt.
	if (IsBrowserProcess())
	std::wcout << std::endl;

这个看起来是纯粹的 UI 打磨。原因:Windows 上双击一个 GUI 程序,cmd 会立刻返回提示符。如果程序随后输出错误信息,会接在提示符后面:

C:\> Some error happened

前面加一个换行,变成:

C:\>
Some error happened

动作 3:ELECTRON_ENABLE_STACK_DUMPING。

electron_main_delegate.cc:189-191

	auto env = base::Environment::Create();
	// Enable convenient stack printing. This is enabled by default in
	// non-official builds.
	if (env->HasVar(kElectronEnableStackDumping))
	base::debug::EnableInProcessStackDumping();

EnableInProcessStackDumping 让 SIGSEGV / SIGABRT 之类的信号在进程内打印栈,而不是只生成 core dump。这对开发调试极其有用。

注意注释:"This is enabled by default in non-official builds"。也就是说,官方 release 构建里这个默认是关的,但如果设了环境变量就打开。这样做是因为栈打印有性能开销(要对所有信号注册处理器),而且会输出敏感信息(路径、符号)。

动作 4:ELECTRON_DISABLE_SANDBOX。

electron_main_delegate.cc:196-197

	if (env->HasVar(kElectronDisableSandbox))
	command_line->AppendSwitch(sandbox::policy::switches::kNoSandbox);

环境变量 → 命令行开关的转换。为什么不直接让用户传 --no-sandbox?

因为 --no-sandbox 是一个"危险"的开关,很多场景下不希望它出现在 ps 的输出里。环境变量的方式更隐蔽,也更容易在容器/CI 环境里设置。

动作 5:TracingSamplerProfiler::CreateOnMainThread()。

	tracing_sampler_profiler_ =
	tracing::TracingSamplerProfiler::CreateOnMainThread();

这是 Chromium 的采样性能分析器。它定期抓取主线程的调用栈,用于 chrome://tracing 里的 CPU profile。

必须在主线程创建,且要在任何 tracing 会话开始之前。放在这里是因为 BasicStartupComplete 是"主线程已经确定、但还没开始干活"的时刻。

动作 6、7:两个 RegisterPathProvider。

	chrome::RegisterPathProvider();
	electron::RegisterPathProvider();

base::PathService 是 Chromium 的路径解析服务。DIR_USER_DATA、DIR_ASSETS、DIR_EXE 这些 key 到实际路径的映射,是通过"path provider"注册的。

chrome::RegisterPathProvider() 注册 Chrome 的那一套(DIR_USER_DATA 指向 ~/.config/google-chrome 之类)。electron::RegisterPathProvider() 覆盖成 Electron 的(DIR_USER_DATA 指向 app 的 userData)。

两个都注册,后者覆盖前者。这是"复用 Chrome 的路径体系,但改掉具体值"的做法。

动作 8:ContentSettingsPattern::SetNonWildcardDomainNonPortSchemes。

#if BUILDFLAG(ENABLE_ELECTRON_EXTENSIONS)
	ContentSettingsPattern::SetNonWildcardDomainNonPortSchemes(
	GetNonWildcardDomainNonPortSchemes());
#endif

这个函数名长得离谱,但它的作用很具体:告诉 content settings 系统"chrome-extension:// 这个 scheme 不用通配符域名 + 端口的匹配规则"。

因为扩展的 URL 是 chrome-extension://<id>/path,没有域名和端口的概念。如果不告诉它,某些内容设置(比如"允许这个源的图片")会解析失败。

GetNonWildcardDomainNonPortSchemes() 返回的是 {extensions::kExtensionScheme},即 "chrome-extension"。

(Electron 的扩展用的是 chrome-extension:// scheme,不是自定义的。这是为了兼容 Chrome 扩展生态。)

动作 9(Windows):三件事。

	// Ignore invalid parameter errors.
	_set_invalid_parameter_handler(InvalidParameterHandler);
	// Disable the ActiveVerifier, which is used by Chrome to track possible
	// bugs, but no use in Electron.
	base::win::DisableHandleVerifier();
	if (IsBrowserProcess())
	base::win::PinUser32();

_set_invalid_parameter_handler —— CRT 的"无效参数"处理器。默认行为是弹一个对话框然后终止进程。Electron 换成一个 no-op,让调用失败但不崩。

DisableHandleVerifier —— Chrome 的句柄验证器,用于检测"关闭了不属于自己的句柄"。它对 Chrome 有用(Chrome 有很多句柄管理代码),对 Electron 是纯开销。

PinUser32() —— 把 user32.dll 固定在内存里。原因:user32.dll 在某些情况下会被卸载,而 Chromium 的窗口代码会继续调用它的函数,导致崩溃。Pin 住它,避免这个问题。

动作 10(Linux):root + 沙箱检查。

	// Check for --no-sandbox parameter when running as root.
	if (getuid() == 0 && IsSandboxEnabled(command_line))
	LOG(FATAL) << "Running as root without --"
			<< sandbox::policy::switches::kNoSandbox
			<< " is not supported. See https://crbug.com/638180.";

这是 Chromium 的一条硬规则:以 root 运行且开启沙箱,直接拒绝启动。

原因:Linux 的 setuid 沙箱机制在 root 下不工作(root 已经有全部权限,setuid 没有意义),而 namespace 隔离在 root 下也有不同的语义。如果不拒绝,会出现"看起来开了沙箱但实际上没有"的情况——这比不开沙箱更危险,因为用户以为自己是安全的。

LOG(FATAL) 会打印栈并 abort()。所以你在 Docker 里用 root 跑 Electron 会看到这个错误。

动作 11(MAS):关闭 GPU memory buffer。

#if IS_MAS_BUILD()
	// In MAS build we are using --disable-remote-core-animation.
	//
	// According to ccameron:
	// If you're running with --disable-remote-core-animation, you may want to
	// also run with --disable-gpu-memory-buffer-compositor-resources as well.
	// That flag makes it so we use regular GL textures instead of IOSurfaces
	// for compositor resources. IOSurfaces are very heavyweight to
	// create/destroy, but they can be displayed directly by CoreAnimation (and
	// --disable-remote-core-animation makes it so we don't use this property,
	// so they're just heavyweight with no upside).
	command_line->AppendSwitch(
	::switches::kDisableGpuMemoryBufferCompositorResources);
#endif

这段注释是一次真实的架构讨论记录("According to ccameron"——ccameron 是 Chromium 的图形负责人)。

逻辑链:

  1. MAS 构建必须用 --disable-remote-core-animation(因为 remote CA 用了私有 API)
  2. 关掉 remote CA 之后,IOSurface 就失去了它的价值(IOSurface 的唯一优势是能被 CoreAnimation 直接显示)
  3. IOSurface 的创建/销毁很重
  4. 所以连带关掉 --disable-gpu-memory-buffer-compositor-resources,用普通 GL texture

两个 flag 必须配对使用,单独用任何一个都是"付出了代价但没得到好处"。这种成对关系在 Chromium 的 flag 体系里很常见,但文档很少写清楚——所以 Electron 把它写在了注释里。

5.3.3 PreSandboxStartup:沙箱之前的最后窗口

这个钩子的名字说明了它的语义:沙箱还没初始化,你还能做任何事。

一旦沙箱初始化,进程就被限制了:不能随便读文件、不能随便开 socket、不能加载新的动态库。所有"需要特权"的初始化都必须在 PreSandboxStartup 里完成。

electron_main_delegate.cc:251-255 第 247-338 行,92 行,8 个动作。

动作 1:--user-data-dir。

	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);
	}

OverrideAndCreateIfNeeded(key, path, create, ...) —— 四个参数里 false, true 是什么意思?

第三个 false 是 create:不立即创建目录。 第四个 true 是 create_intermediates:创建中间目录。

等一下,这个读法不对。实际的签名是 OverrideAndCreateIfNeeded(int key, const FilePath& path, bool create, bool create_intermediates)。所以 false = 不创建,true = 允许创建中间目录。

理解了:**这里只做覆盖,不创建目录。**目录的创建在 Browser::DidFinishLaunching 里(见 5.9 节)——那时候才需要目录真的存在。

为什么在这里只覆盖不创建?因为 DIR_USER_DATA 在 PreSandboxStartup 之后会被很多地方读(比如日志路径),但真正需要目录存在是在 ready 之后。提前创建会带来一个副作用:如果用户的路径是错的(比如指向一个只读位置),会在启动早期就失败,错误信息很难懂。

动作 2:日志预初始化。

#if !BUILDFLAG(IS_WIN)
	// For windows we call InitLogging later, after the sandbox is initialized.
	//
	// On Linux, we force a "preinit" in the zygote (i.e. never log to a default
	// log file), because the zygote is booted prior to JS running, so it can't
	// know the correct user-data directory. (And, further, accessing the
	// application name on Linux can cause glib calls that end up spawning
	// threads, which if done before the zygote is booted, causes a CHECK().)
	logging::InitElectronLogging(
	*command_line,
	/* is_preinit = */ IsBrowserProcess() || IsZygoteProcess());
#endif

这段注释是全章最好的注释之一。它解释了两件事:

为什么 Windows 上不在这里初始化? 因为 Windows 的日志要写文件,写文件需要访问 %LOCALAPPDATA%\YourApp\logs。这个路径需要沙箱权限。所以要等沙箱初始化之后再调(在 SandboxInitialized 里)。

为什么 Linux 上 zygote 要"预初始化"(is_preinit = true)? 三个原因叠加:

  1. zygote 在 JS 运行之前就启动了,所以它不知道正确的 userData 目录
  2. 不知道目录,就不能写文件日志,所以只能预初始化(只输出到 stderr)
  3. 更麻烦的是:在 Linux 上获取应用名会调用 glib,glib 可能创建线程,而在 zygote 启动之前创建线程会导致 CHECK() 失败

第 3 点是一个真实的踩坑。zygote 的哲学是"fork 之前不要有线程"——因为 fork 只复制调用线程,其它线程在子进程里不存在,但它们持有的锁还在,子进程一用锁就死锁。glib 内部有线程池,一旦初始化就创建了线程。

所以 Linux 上的规则是:**在 zygote fork 之前,不要碰任何可能创建线程的东西。**日志初始化看起来无害,但它要读应用名,读应用名要 glib,glib 创建线程。链条就这么连起来了。

动作 3、4、5:崩溃报告的三个层次。

	crash_reporter::InitializeCrashKeys();          // 分配崩溃键的存储
#if WIN || (MAC && !MAS)
	// In the main process, we wait for JS to call crashReporter.start() before
	// initializing crashpad. If we're in the renderer, we want to initialize it
	// immediately at boot.
	if (!IsBrowserProcess()) {
	ElectronCrashReporterClient::Create();
	crash_reporter::InitializeCrashpad(false, process_type);
	}
#endif

为什么 browser 进程要等 JS? Crashpad 需要 submitURL 和是否上报,这些是应用在 crashReporter.start() 里决定的。

为什么子进程立刻初始化? 它们可能在 JS 跑起来之前就崩(GPU 进程初始化失败)。它们的 submitURL 由 browser 进程通过命令行传下去。

Windows 上还有一行 SetErrorMode(GetErrorMode() & ~SEM_NOGPFAULTERRORBOX),注释解释了它的来历:沙箱的 Job Object 用 JOB_OBJECT_LIMIT_DIE_ON_UNHANDLED_EXCEPTION 让子进程以 SEM_NOGPFAULTERRORBOX 启动(不弹 WER 框),但这也让 Crashpad 的进程外处理器看不到崩溃。Crashpad 装好后要把这个标志清掉。这是一个"先禁用再恢复"的模式。

动作 6:LoadResourceBundle。

	if (SubprocessNeedsResourceBundle(process_type)) {
	std::string locale = command_line->GetSwitchValueASCII(::switches::kLang);
	LoadResourceBundle(locale);
	}

SubprocessNeedsResourceBundle 是一个 14 行的函数:

bool SubprocessNeedsResourceBundle(const std::string& process_type) {
	return
#if BUILDFLAG(IS_LINUX)
	// The zygote process opens the resources for the renderers.
	process_type == ::switches::kZygoteProcess ||
#endif
#if BUILDFLAG(IS_MAC)
	// Mac needs them too for scrollbar related images and for sandbox
	// profiles.
	process_type == ::switches::kGpuProcess ||
#endif
	process_type == ::switches::kRendererProcess ||
	process_type == ::switches::kUtilityProcess;
}

三个平台不同的判定:

  • Linux:zygote 也要(因为它为 renderer 打开资源)
  • macOS:GPU 进程也要(滚动条图片、沙箱 profile)
  • 所有平台:renderer 和 utility 都要

browser 进程不在列表里——它的资源在 PreCreateThreads 里加载(见 5.8 节)。为什么?因为 browser 进程需要先确定 locale,而 locale 的确定需要 PreCreateThreads 里那一堆平台特定的逻辑。

动作 7、8:browser 专属的两个开关。

	if (IsBrowserProcess()) {
	// Allow file:// URIs to read other file:// URIs by default.
	command_line->AppendSwitch(::switches::kAllowFileAccessFromFiles);
	// ...
#if BUILDFLAG(IS_OZONE)
	ui::SetOzonePlatformForLinuxIfNeeded(*command_line);
	ui::OzonePlatform::PreSandboxStartup();
#endif
	}

--allow-file-access-from-files —— 这个开关的默认值在 Chromium 里是关的,即 file://a.html 不能 XHR 读 file://b.json(同源策略把每个 file URL 当成独立源)。Electron 默认打开它。

这是一个安全性与可用性的权衡,而且是一个争议性的选择。打开它意味着:如果你的应用加载了不可信的本地 HTML,那个 HTML 能读用户磁盘上的任何文件。

Electron 的安全文档反复提醒:不要加载不可信内容,如果必须加载,用自定义协议而不是 file://。

为什么默认打开?因为 Electron 的早期用户大量使用 file:// 加载本地页面 + XHR 读本地数据,如果默认关掉,几乎所有应用都跑不起来。这是一个"历史包袱",但也是一个"本地应用"和"网页"的区别所在——本地应用本来就该能读本地文件。

ui::OzonePlatform::PreSandboxStartup() —— Ozone 是 Chromium 的窗口系统抽象层(Wayland/X11)。PreSandboxStartup 要在沙箱之前做,因为它可能 dlopen 平台库(libwayland-client.so)。

5.3.4 SandboxInitialized:Windows 的补课

void ElectronMainDelegate::SandboxInitialized(const std::string& process_type) {
#if BUILDFLAG(IS_WIN)
	logging::InitElectronLogging(*base::CommandLine::ForCurrentProcess(),
							/* is_preinit = */ process_type.empty());
#endif
}

只有 Windows 有实现。InitElectronLogging 的第二个参数 is_preinit = true 表示"只输出到 stderr,不建文件"。browser 进程的 process_type 为空,所以这里仍是 true;子进程传 false,可以写文件了。

browser 进程为什么还要等?因为日志文件路径依赖 app.setName(),而应用名在 JS 里设置。所以它的正式初始化在 PostEarlyInitialization 末尾(5.5 节第 [22] 步)。

三段式由此形成:PreSandboxStartup(非 Windows 预初始化)→ SandboxInitialized(Windows 子进程正式化)→ PostEarlyInitialization 末尾(browser 正式化)。

5.3.5 PreBrowserMain:FieldTrial 与 Mojo

std::optional<int> ElectronMainDelegate::PreBrowserMain() {
	// This is initialized early because the service manager reads some feature
	// flags and we need to make sure the feature list is initialized before the
	// service manager reads the features.
	if (!base::FieldTrialList::GetInstance()) {
	// Intentionally never destroyed: the FieldTrialList has to outlive
	// everything that reads field trials. Storing it in a static keeps the
	// allocation reachable, both for static analysis and for LeakSanitizer.
	[[maybe_unused]] static base::FieldTrialList* leaked_field_trial_list =
		new base::FieldTrialList();
	ANNOTATE_LEAKING_OBJECT_PTR(leaked_field_trial_list);
	}
	InitializeFeatureList();
	// Initialize mojo core as soon as we have a valid feature list
	content::InitializeMojoCore();
	// ...
}

FieldTrialList 为什么"故意泄漏"?

base::FieldTrialList 是 Chromium 的 A/B 实验框架。它的实例是一个全局单例,所有 base::FeatureList::IsEnabled(...) 的调用都要通过它。

问题:这个对象的析构顺序无法保证。如果它在某个还在用 feature 的对象之前被析构,那个对象访问的就是悬垂指针。

Chromium 的解法是:永不析构。用 new 分配,然后故意不 delete,并加 ANNOTATE_LEAKING_OBJECT_PTR 告诉 LeakSanitizer"这是故意的,不要报"。

注释里那句 "Storing it in a static keeps the allocation reachable, both for static analysis and for LeakSanitizer" 说明了为什么要存在一个 static 指针里——如果只是 new 一个不保存指针,静态分析工具会说"内存泄漏",LeakSanitizer 也会报。存到 static 变量里,工具就能看到"这个指针还活着",判定为"可达但未释放",不报泄漏。

**InitializeFeatureList() 是 Electron 自己的。**它在 feature_list.cc 里,做的事是:把 Electron 自己的 feature 列表(kElectronFeatures)注册进去,然后处理 --enable-features / --disable-features 命令行。

**Mojo 必须在 FeatureList 之后。**注释说了原因:service manager 会读 feature flags。如果 Mojo 先初始化,它读到的 feature 是空的(默认值),后续的 --enable-features 就无效了。

这是一个典型的初始化顺序依赖:B 依赖 A 的数据,所以 A 必须先完成。

**macOS:RegisterAtomCrApp()。**注册 com.apple.atom 的 CR app 类型。这是 macOS 的"进程间通信"机制的一部分,用于 NSConnection。窗口管理相关的代码需要它。

Linux:ExtractXdgActivationTokenFromEnv()。

	// Set the global activation token sent as an environment variable.
	auto env = base::Environment::Create();
	base::nix::ExtractXdgActivationTokenFromEnv(*env);

Wayland 的 xdg-activation 协议要求:如果应用是被另一个应用启动的(比如从浏览器点一个链接),启动者会通过环境变量传一个 "activation token"。应用用这个 token 请求窗口焦点。

如果不读这个 token,应用启动后窗口可能不会获得焦点——用户点了链接,窗口在后台打开了,但没跳到前面。

这个 token 必须在窗口创建之前读,所以在 PreBrowserMain。

5.3.6 delegate 侧的 PostEarlyInitialization:内存系统

std::optional<int> ElectronMainDelegate::PostEarlyInitialization(
	InvokedIn invoked_in) {
	// Start memory observation as early as possible so it can start recording
	// memory allocations.
	InitializeMemorySystem();
	return std::nullopt;
}
void ElectronMainDelegate::InitializeMemorySystem() {
	const base::CommandLine* const command_line =
	base::CommandLine::ForCurrentProcess();
	const std::string process_type =
	command_line->GetSwitchValueASCII(::switches::kProcessType);
	// PoissonAllocationSampler is necessary for heap profiling.
	memory_system::Initializer()
	.SetDispatcherParameters(memory_system::DispatcherParameters::
								PoissonAllocationSamplerInclusion::kEnforce,
							memory_system::DispatcherParameters::
								AllocationTraceRecorderInclusion::kIgnore,
							process_type)
	.Initialize(memory_system_);
}

PoissonAllocationSampler 是 Chromium 的堆采样器:它以概率 p 记录每次 malloc,用采样结果推算总体的分配分布。这是 heap profile 的基础。

kEnforce 意味着"必须装上,装不上就失败"。AllocationTraceRecorderInclusion::kIgnore 意味着"不需要逐次记录"(那个很贵)。

这个初始化必须在"尽可能早"——因为晚一步,之前的分配就没被采样到。PostEarlyInitialization 是所有进程类型都会经过的最早的"可以创建对象"的时机。

注意 memory_system_ 是 ElectronMainDelegate 的成员(electron_main_delegate.h:74)。它的生命周期跟着 delegate,也就是整个进程。

5.3.7 五个 Client 工厂与四个 Should*

content::ContentClient* ElectronMainDelegate::CreateContentClient() {
	content_client_ = std::make_unique<ElectronContentClient>();
	return content_client_.get();
}

五个工厂函数(Content/ContentBrowser/ContentGpu/ContentRenderer/ContentUtility)的模式完全一样:成员变量持有 unique_ptr,返回裸指针。

为什么不用 unique_ptr 返回?因为 content 层的接口是裸指针,它不接管所有权。delegate 必须自己持有。

这个模式很重要:delegate 是这些 Client 的唯一所有者。它们的生命周期和 delegate 一样长(整个进程)。这也解释了为什么 delegate 必须是栈对象或长期存在的对象——不能是临时对象。

CreateContentRendererClient 有一个分支:

content::ContentRendererClient*
ElectronMainDelegate::CreateContentRendererClient() {
	auto* command_line = base::CommandLine::ForCurrentProcess();
	if (IsSandboxEnabled(command_line)) {
	renderer_client_ = std::make_unique<ElectronSandboxedRendererClient>();
	} else {
	renderer_client_ = std::make_unique<ElectronRendererClient>();
	}
	return renderer_client_.get();
}

两个实现,取决于沙箱开关。这是编译期无法决定的选择——它取决于运行时的 --no-sandbox,或者 webPreferences.sandbox: false。

但等等,渲染进程的渲染进程类型(sandboxed vs not)是每个渲染进程决定的,不是全局的。为什么这里只有两个全局实现?

答案在第 4 章的 support_mixed_sandbox_with_zygote.patch:同一个 browser 进程可以启动两种渲染进程。它们通过命令行区分。

所以 CreateContentRendererClient 在每个渲染进程里被调用一次,那里读的是该进程自己的命令行。如果一个渲染进程是 --no-sandbox 启动的,它创建 ElectronRendererClient;否则创建 ElectronSandboxedRendererClient。

CreateContentRendererClient 名字里有 "Create",容易误以为是 browser 侧创建 renderer client。实际上是渲染进程自己创建自己的 client。这是 content 层的一个反直觉设计。

如果你不熟悉 content 层:ContentRendererClient 是"渲染进程侧的扩展点集合",每个渲染进程有自己的实例。同理 ContentGpuClient 在 GPU 进程里,ContentUtilityClient 在 utility 进程里。只有 ContentBrowserClient 在 browser 进程里。

四个 Should* 函数:

bool ElectronMainDelegate::ShouldCreateFeatureList(InvokedIn invoked_in) {
	return std::holds_alternative<InvokedInChildProcess>(invoked_in);
}
bool ElectronMainDelegate::ShouldInitializeMojo(InvokedIn invoked_in) {
	return ShouldCreateFeatureList(invoked_in);
}
bool ElectronMainDelegate::ShouldLoadV8Snapshot(
	const std::string& process_type) {
	// The gpu does not need v8
	if (process_type == ::switches::kGpuProcess) {
	return false;
	}
	return true;
}
bool ElectronMainDelegate::ShouldLockSchemeRegistry() {
	return false;
}

ShouldCreateFeatureList / ShouldInitializeMojo 都返回"是否在子进程里"。

这意味着:在 browser 进程里,content 层不要自己创建 FeatureList 和 Mojo,Electron 自己管。

为什么?因为 browser 进程的 FieldTrial 和 Mojo 在 PreBrowserMain 里手工创建(见 5.3.5),要精确控制顺序。如果 content 层也创建一次,就是重复初始化(会 CHECK 失败)。

子进程则相反:它们不需要 Electron 的那套精细控制,让 content 层按标准流程创建就行。

这个 InvokedIn 的设计本身很有意思。它是一个 std::variant<InvokedInBrowserProcess, InvokedInChildProcess>,把"我在哪里被调用"编码进类型系统,而不是用一个 bool is_browser 参数。这样编译器能强制你在两个分支上都写代码。

ShouldLoadV8Snapshot 返回 GPU 进程不加载。因为 GPU 进程不跑 JS——它只跑 GL/Vulkan 命令。加载 V8 snapshot 会浪费几 MB 内存和几毫秒启动时间。

ShouldLockSchemeRegistry 返回 false。

这个函数默认(Chromium 里)返回 true,意思是"初始化完成后锁定 scheme registry,不允许再注册新 scheme"。

Electron 返回 false,因为应用需要在运行时注册自定义协议(protocol.registerSchemesAsPrivileged)。如果锁定了,那个 API 就失效了。

代价是:scheme registry 不是线程安全的。所以 Electron 在 PreMainMessageLoopRun 里手工调 url::LockSchemeRegistries()(见 5.9 节)——在"应用已经注册完所有 scheme、消息循环即将开始"的那个时刻锁。

这是一个"推迟锁定"的模式:不是不锁,是晚点锁。

5.3.8 RunProcess:relauncher

std::variant<int, content::MainFunctionParams> ElectronMainDelegate::RunProcess(
	const std::string& process_type,
	content::MainFunctionParams main_function_params) {
	if (process_type == kRelauncherProcess)
	return relauncher::RelauncherMain(main_function_params);
	else
	return std::move(main_function_params);
}

kRelauncherProcess 是 "relauncher"(第 92 行定义)。

relauncher 是干什么的?它是在应用退出之后、重新启动一个新的应用实例的进程。

场景:应用自动更新完成,需要重启。但当前进程还在跑,不能自己重启自己(文件被占用)。所以启动一个 relauncher,让它在当前进程退出后启动新版本。

这个设计在 Windows 上尤其必要——electron.exe 被当前进程锁着,只有当前进程完全退出才能替换。

RunProcess 返回 std::variant<int, MainFunctionParams>:返回 int 表示"这个进程类型我处理完了,退出码是这个";返回 MainFunctionParams 表示"我不处理,你继续走正常流程"。

这个 variant 的设计比"返回 int,-1 表示没处理"好得多——类型系统强制你处理两种情况。


5.4 ElectronBrowserMainParts 的构造函数:四件事

ContentMain 走到 BrowserMain 之后,会构造一个 BrowserMainParts。Electron 的实现是 ElectronBrowserMainParts。

它的构造函数只有 10 行(electron_browser_main_parts.cc:202-212):

ElectronBrowserMainParts::ElectronBrowserMainParts()
	: fake_browser_process_(std::make_unique<BrowserProcessImpl>()),
	node_bindings_{
		NodeBindings::Create(NodeBindings::BrowserEnvironment::kBrowser,
							uv_default_loop())},
	electron_bindings_{
		std::make_unique<ElectronBindings>(node_bindings_->uv_loop())},
	browser_{std::make_unique<Browser>()} {
	DCHECK(!self_) << "Cannot have two ElectronBrowserMainParts";
	self_ = this;
}

四个成员,在初始化列表里按声明顺序构造:

1. fake_browser_process_ —— BrowserProcessImpl。

名字里的 "fake" 很诚实。Chromium 有一个全局的 g_browser_process,类型是 BrowserProcess(一个抽象接口),Chrome 的实现是 ChromeBrowserProcessImpl。这个对象持有:本地状态(local_state)、IO 线程的任务运行器、下载管理器、扩展管理器……几十个服务。

Electron 没有 Chrome 的那套服务,但很多 Chromium 组件要求 g_browser_process 存在(它们会 g_browser_process->local_state())。所以 Electron 提供了一个最小实现。

BrowserProcessImpl 的构造函数会把自己注册成 g_browser_process 吗?我们看它的实现(第 5.4.1 小节)。

2. node_bindings_ —— NodeBindings::Create(kBrowser, uv_default_loop())。

注意 uv_default_loop()。这是 libuv 的默认循环,一个全局单例。browser 进程用它,而不是 uv_loop_new() 创建一个新的。

为什么用默认的?因为某些 Node 原生模块硬编码了 uv_default_loop()(它们不接收 loop 参数)。如果用自定义 loop,这些模块会跑到另一个 loop 上,事件永远不被处理。

代价是:browser 进程只能有一个 Node environment(因为只有一个 default loop)。这也是为什么 utility process 要用单独的进程而不是同进程的第二个 environment。

3. electron_bindings_ —— ElectronBindings(node_bindings_->uv_loop())。

这是 Electron 自己的 C++ 绑定(process.versions、process.electronBinding 之类)。它需要 uv loop 是因为某些绑定会创建 uv handle(比如 electron_bindings 里的 SetImmediate)。

4. browser_ —— Browser()。

这是 Electron 的 app 对象背后的 C++ 类。它管理窗口列表、生命周期、单实例、协议注册。

注意 self_ = this。 这是一个静态成员,用于 ElectronBrowserMainParts::Get()。Browser::Get() 就是通过它拿到的:

// static
Browser* Browser::Get() {
	return ElectronBrowserMainParts::Get()->browser();
}

这个全局单例的存在,说明整个架构假设"一个进程只有一个 BrowserMainParts"。DCHECK(!self_) 就是这个假设的断言。

5.4.1 一个顺序陷阱

四个成员的构造顺序由声明顺序决定,不是初始化列表的顺序。

看头文件 electron_browser_main_parts.h 的成员声明(顺序很重要):

std::unique_ptr<BrowserProcessImpl> fake_browser_process_;
std::unique_ptr<NodeBindings> node_bindings_;
std::unique_ptr<ElectronBindings> electron_bindings_;
std::unique_ptr<Browser> browser_;

fake_browser_process_ 在最前面。这不是随便排的——BrowserProcessImpl 的构造函数会设置 g_browser_process,而后续三个成员的构造可能会读 g_browser_process。

如果顺序反了(比如 browser_ 在前),Browser() 构造时 g_browser_process 还是 null,某些代码路径会崩。

这类"成员顺序依赖"是 C++ 里最隐蔽的 bug 来源之一:初始化列表写 a_(1), b_(a_) 看起来 a 先于 b,但实际顺序由声明顺序决定,反了就读到未初始化的 a。Electron 靠"声明顺序 = 依赖顺序"避开这个问题。


5.5 PostEarlyInitialization:主进程最重的 120 行

如果说前面所有阶段都是"准备工作",那么 PostEarlyInitialization(electron_browser_main_parts.cc:297-417)就是真正把 Electron 造出来的地方。

121 行,做了 13 件事。这是整个启动链路里密度最高的函数,没有之一。

先给出完整的调用顺序,然后逐段拆。

PostEarlyInitialization()
├─ [1]  DCHECK(SingleThreadTaskRunner::HasCurrentDefault())
├─ [2]  SetUpWebAssemblyTrapHandler()          (fuse + 架构条件)
├─ [3]  js_env_ = make_unique<JavascriptEnvironment>(uv_loop)
│         ├─ node::MultiIsolatePlatform::Create(...)
│         ├─ v8::V8::InitializePlatform(platform)
│         └─ gin::IsolateHolder::Initialize(..., create_v8_platform=false)
├─ [4]  isolate = js_env_->isolate(); HandleScope
├─ [5]  context = isolate->GetCurrentContext()   (可能为空!)
├─ [6]  node_bindings_->Initialize(isolate, context)
│         ├─ RegisterBuiltinBindings()
│         ├─ InstallProcessCodeCache()
│         ├─ SetNodeOptions()
│         ├─ ParseNodeCliFlags()
│         └─ node::InitializeOncePerProcess(args, flags)
├─ [7]  Linux: SystemFontConfigInit 线程启动
├─ [8]  node_env_ = node_bindings_->CreateEnvironment(isolate, context, platform, max_young)
├─ [9]  if (context.IsEmpty()) node_env_->context()->Enter()
├─ [10] node_bindings_->SetUpIsolate(isolate)
├─ [11] node_env_->options()->unhandled_rejections = "warn-with-error-code"
├─ [12] electron_bindings_->BindTo(isolate, node_env_->process_object())
├─ [13] LoadAppPackage() → global.setPrivate("appPackage", {...})
├─ [14] js_env_->CreateMicrotasksRunner()
├─ [15] node_bindings_->set_uv_env(node_env_.get())
├─ [16] Linux: JoinSystemFontConfigInit()
├─ [17] node_bindings_->LoadEnvironment(node_env_.get())     ← 执行 init bundle
├─ [18] node_bindings_->JoinAppCode()                        ← 泵循环等 JS
├─ [19] Linux: 如果 FONTCONFIG_* 变了,FcInitReinitialize()
├─ [20] base::FeatureList::ClearInstanceForTesting() + InitializeFeatureList()
├─ [21] InitializeFieldTrials()
├─ [22] logging::InitElectronLogging(..., is_preinit=false)
└─ [23] fake_browser_process_->PostEarlyInitialization()

23 个动作。下面挑出七个最关键的展开。

5.5.1 DCHECK(SingleThreadTaskRunner::HasCurrentDefault())

void ElectronBrowserMainParts::PostEarlyInitialization() {
	// A workaround was previously needed because there was no ThreadTaskRunner
	// set.  If this check is failing we may need to re-add that workaround
	DCHECK(base::SingleThreadTaskRunner::HasCurrentDefault());

这行看起来是个无害的断言,但它背后是一次真实的架构演进。

base::SingleThreadTaskRunner::GetCurrentDefault() 返回"当前线程的默认任务运行器"。在 Chromium 里,主线程(UI 线程)必须在某个时刻被"绑定"一个 TaskRunner,之后所有 PostTask(FROM_HERE, ...) 才能工作。

历史上,Electron 的 PostEarlyInitialization 执行时,这个绑定还没发生。所以 Electron 需要自己做一次 workaround:手工创建一个 SequenceManager 或者用别的办法让 task runner 可用。

后来 Chromium 改了初始化顺序,PostEarlyInitialization 时 task runner 已经可用了。workaround 被移除,但注释被保留下来,并且加了一个 DCHECK 来守住这个前提。

这是一个非常好的实践:当你移除了一个 workaround,不要只删代码,要加一个断言来验证"前提真的成立了"。如果将来 Chromium 又改回去,这个断言会在 debug 构建里立刻炸,而不是让你在某个更难查的地方发现 task 没执行。

5.5.2 WASM trap handler:必须先于 isolate

	// Enable trap handlers before creating the V8 isolate. V8 initialization
	// calls IsTrapHandlerEnabled() which prevents later EnableTrapHandler calls.
#if ((BUILDFLAG(IS_LINUX) || BUILDFLAG(IS_WIN) || BUILDFLAG(IS_MAC)) && \
	defined(ARCH_CPU_X86_64)) ||                                       \
	((BUILDFLAG(IS_LINUX) || BUILDFLAG(IS_MAC)) && defined(ARCH_CPU_ARM64))
	if (electron::fuses::IsWasmTrapHandlersEnabled()) {
	electron::SetUpWebAssemblyTrapHandler();
	}
#endif

WASM 的 trap 是"越界访问 / 除零 / unreachable"之类的运行时错误。传统实现是每次内存访问都插入边界检查——慢。

V8 的优化方案是:把 WASM 的一部分线性内存映射到一块巨大的虚拟地址空间(比如 10GB 的 guard region),然后在段错误信号处理器里判断"这个地址是不是落在 guard 里"。如果是,就是 WASM 的 trap;不是,就是真的段错误。

这需要安装一个 SIGSEGV 处理器(Windows 上是 vectored exception handler)。

**为什么必须在 isolate 创建之前?**注释说了:V8 initialization calls IsTrapHandlerEnabled()。

V8 在初始化时会检查"trap handler 装了吗"。这个检查的结果会被缓存下来——如果当时没装,V8 就认为这个进程不支持 trap handler,后续即使你装了,V8 也不会启用快速路径。

而 IsolateHolder::Initialize(在 JavascriptEnvironment 里)会触发这个检查。所以顺序必须是:

SetUpWebAssemblyTrapHandler()   ← 先装
	↓
JavascriptEnvironment()          ← V8 初始化,检查到已装

顺序反了不会报错,只会让 WASM 变慢。这是一个性能正确性问题,不是功能正确性问题——所以它没有任何报错,只能靠注释和 code review 守住。

条件编译那一大坨也值得看:

((LINUX || WIN || MAC) && X86_64) || ((LINUX || MAC) && ARM64)

x86-64 三个平台都支持;ARM64 只有 Linux 和 macOS 支持。Windows on ARM 不支持——因为 Windows 的 ARM64 上没有等价的 "guard page + 信号处理"机制(Windows 的 SEH 在 ARM64 上的行为不同)。

fuses::IsWasmTrapHandlersEnabled() 是一个 fuse:某些安全敏感的应用可能希望关掉它(因为一个装错信号处理器的 bug 会把正常的段错误变成静默的错误行为)。

5.5.3 JavascriptEnvironment:V8 平台的真正创建者

	// The ProxyResolverV8 has setup a complete V8 environment, in order to
	// avoid conflicts we only initialize our V8 environment after that.
	js_env_ = std::make_unique<JavascriptEnvironment>(node_bindings_->uv_loop());

注释里的 ProxyResolverV8 是 Chromium 网络栈的一部分——它用 V8 解析代理的 PAC 脚本。它会在 NetworkService 或 browser 进程里创建一个 V8 isolate。

也就是说:在 Electron 创建自己的 isolate 之前,进程里可能已经有一个 V8 isolate 了(ProxyResolverV8 的)。这个 isolate 有自己的平台、自己的内存。

Electron 的 isolate 必须和它隔离,不能共享堆、不能共享 context。

JavascriptEnvironment 的构造在哪?在 Initialize() 里(javascript_environment.cc:254-306):

v8::Isolate* JavascriptEnvironment::Initialize(
	uv_loop_t* event_loop,
	bool setup_wasm_streaming,
	v8::TracingController* tracing_controller) {
	auto* cmd = base::CommandLine::ForCurrentProcess();
	// --js-flags.
	std::string js_flags = "--no-freeze-flags-after-init ";
	js_flags.append(cmd->GetSwitchValueASCII(blink::switches::kJavaScriptFlags));
	v8::V8::SetFlagsFromString(js_flags.c_str(), js_flags.size());
	// The V8Platform of gin relies on Chromium's task schedule, which has not
	// been started at this point, so we have to rely on Node's V8Platform.
	platform_ = node::MultiIsolatePlatform::Create(
	base::RecommendedMaxNumberOfThreadsInThreadGroup(3, 8, 0.1, 0),
	tracing_controller, gin::V8Platform::Get()->GetPageAllocator());
	v8::V8::InitializePlatform(platform_.get());
	gin::IsolateHolder::Initialize(
	gin::IsolateHolder::kNonStrictMode,
	gin::ArrayBufferAllocator::SharedInstance(),
	nullptr /* external_reference_table */, js_flags,
	false /* disallow_v8_feature_flag_overrides */,
	nullptr /* fatal_error_callback */, nullptr /* oom_error_callback */,
	false /* create_v8_platform */);
	...
}

这里有第 4 章 4.7 节讲的 create_v8_platform = false。现在可以看到它的完整上下文了:

第一行 platform_ = node::MultiIsolatePlatform::Create(...) —— 用 Node 的平台,不用 gin 的。

注释解释了原因:

The V8Platform of gin relies on Chromium's task schedule, which has not been started at this point, so we have to rely on Node's V8Platform.

gin::V8Platform 把 V8 的后台任务(GC、并发编译)投递到 Chromium 的 ThreadPool。而在 PostEarlyInitialization 这个时刻,Chromium 的 ThreadPool 还没启动(它在 PreCreateThreads 之后才可用)。

如果这时候用 gin 的平台创建 isolate,V8 一启动就会尝试投递后台任务,投到不存在的池里——任务丢失,或者 CHECK 失败。

node::MultiIsolatePlatform 则把任务投递到 libuv 的线程池。libuv 是 Node 初始化时启动的,已经可用。

三个参数:

node::MultiIsolatePlatform::Create(
	base::RecommendedMaxNumberOfThreadsInThreadGroup(3, 8, 0.1, 0),  // 线程数
	tracing_controller,                                              // tracing
	gin::V8Platform::Get()->GetPageAllocator()                       // page allocator
);

第一个参数是后台线程数。RecommendedMaxNumberOfThreadsInThreadGroup(3, 8, 0.1, 0) 的意思是:最少 3 个,最多 8 个,按 CPU 核数的 10% 计算,最少 0 个(不设下限?)。

这是 Chromium 的一个启发式函数:clamp(cores * 0.1, min, max),然后上限是 8。一台 8 核机器算出来是 0.8 → 至少 3;32 核机器算出来是 3.2 → 4(因为要取整)。

为什么要限制在 8? 因为 V8 的后台任务主要是 GC 的并发标记和编译。超过 8 个线程,收益趋零而上下文切换成本上升。而且 Electron 应用可能有几十个进程,每个进程 8 个后台线程就是几百个线程——太多了。

第三个参数 gin::V8Platform::Get()->GetPageAllocator() 很有意思:用的是 gin 的 page allocator。

PageAllocator 负责向操作系统申请"页"(V8 的堆、代码空间、WASM 内存都从这里分配)。gin 的实现用 base::AllocatePages,它有一些额外的能力(比如 DiscardSystemPages,把页还给系统但保留地址空间)。

即使不用 gin 的平台,也可以用 gin 的 PageAllocator——因为 PageAllocator 是一个纯接口,和平台调度无关。

v8::V8::InitializePlatform(platform_.get()) —— 这一步是"注册"。

V8 允许你创建平台对象,但必须显式 InitializePlatform 才会生效。这个函数只能调用一次(第二次会 CHECK)。

gin::IsolateHolder::Initialize(..., false /* create_v8_platform */) —— 第 4 章讲的补丁在这里落地。

如果传 true(默认),gin 会调用 v8::V8::InitializePlatform(V8Platform::Get())——把 gin 的平台注册进去。但前面已经注册了 Node 的平台,第二次注册会 CHECK 失败。

所以必须传 false。

这一行就是补丁存在的全部理由,也是第 4 章那个 bool 参数的最终消费者。

--no-freeze-flags-after-init ——

std::string js_flags = "--no-freeze-flags-after-init ";
js_flags.append(cmd->GetSwitchValueASCII(blink::switches::kJavaScriptFlags));
v8::V8::SetFlagsFromString(js_flags.c_str(), js_flags.size());

V8 默认在初始化完成后"冻结"flag——之后 SetFlagsFromString 会失败(静默失败)。

为什么 V8 要冻结?因为某些 flag 会影响已编译代码的假设(比如 --jitless)。如果运行时改了,已编译的代码就错了。

但 Electron 需要不冻结,因为:

  1. v8.setFlagsFromString() 是一个公开 API(用户可以在 app.commandLine.appendSwitch('js-flags', ...) 里传)
  2. appPackage.v8Flags(package.json 里的 v8Flags 字段)需要在应用加载时才应用

第 3 章的 3.x 节讲过:electron_js2c 的四个 flavor 里有一个 --no-freeze-flags-after-init。现在是它在运行时的对应物。

node::MultiIsolatePlatform 的 "MultiIsolate" —— 这个类名很关键。它支持注册多个 isolate,每个 isolate 绑定到一个 uv loop:

v8::Isolate* isolate = v8::Isolate::Allocate();
platform_->RegisterIsolate(isolate, event_loop);

RegisterIsolate(isolate, loop) 把 isolate 和 loop 绑定。之后这个 isolate 的后台任务会投递到这个 loop 上。

这就是为什么 Electron 的渲染进程可以在同一个 MultiIsolatePlatform 上跑 Blink 的 isolate 和 Node 的 isolate——虽然实际上渲染进程用的是不同的架构(Blink 有自己的一套)。但 worker 线程里的 Node isolate 确实是这样注册的。

5.5.4 NodeBindings::Initialize:五个 ProcessInitializationFlags

	node_bindings_->Initialize(isolate, context);

这个调用在 node_bindings.cc:691-772,76 行。核心是这一段:

	uint64_t process_flags =
	node::ProcessInitializationFlags::kNoInitializeCppgc |
	node::ProcessInitializationFlags::kNoInitializeV8 |
	node::ProcessInitializationFlags::kNoInitializeNodeV8Platform;
	// We do not want the child processes spawned from the utility process
	// to inherit the custom stdio handles created for the parent.
	if (browser_env_ != BrowserEnvironment::kUtility)
	process_flags |= node::ProcessInitializationFlags::kEnableStdioInheritance;
	if (browser_env_ == BrowserEnvironment::kRenderer)
	process_flags |= node::ProcessInitializationFlags::kNoDefaultSignalHandling;
	if (!fuses::IsNodeOptionsEnabled())
	process_flags |= node::ProcessInitializationFlags::kDisableNodeOptionsEnv;

四个 flag,每个都在说"Node,这件事你别做,Electron 已经做了"或"这件事你换个做法"。

kNoInitializeCppgc —— 不要初始化 cppgc(C++ 垃圾回收,用于 Oilpan)。

Node 在启动时会初始化 cppgc,因为它的一些 API(v8::CppHeap)需要。但 Electron 的进程里,cppgc 可能已经由 Blink 初始化了(渲染进程),或者根本不需要(browser 进程)。

如果 Node 也初始化一次,会出现两个 CppHeap,它们的对象互不可见——这会导致 V8 的 GC 看不到某些跨堆引用,产生"对象被提前回收"的崩溃。

kNoInitializeV8 —— 不要初始化 V8。

V8 已经由 JavascriptEnvironment 初始化了(v8::V8::InitializePlatform + gin::IsolateHolder::Initialize)。Node 的 InitializeOncePerProcess 默认会调 v8::V8::Initialize(),那是第二次,CHECK 失败。

kNoInitializeNodeV8Platform —— 对应 all.gn:14 里的 node_use_v8_platform = false(第 3 章讲过)。

这三个 flag 合起来的效果是:Node 的进程级初始化只做它自己该做的部分(读环境变量、解析 CLI 参数、初始化 libuv、注册 builtin),V8 和 cppgc 都由 Electron 管。

kEnableStdioInheritance(非 utility 进程) ——

注释:We do not want the child processes spawned from the utility process to inherit the custom stdio handles created for the parent.

utility 进程的 stdio 是特殊的:Electron 在创建 utility 进程时会传入自定义的 stdio(electron_api_utility_process.cc 里的 stdio 选项)。这些 stdio 是管道,不是文件。

如果 utility 进程里的 Node 认为"stdio 可以继承",它 spawn 子进程时会把这些管道也继承过去。子进程的 stdout 就接到了 utility 进程的管道上——而那个管道是给 utility 进程和主进程通信用的,子进程写进去会污染协议。

所以 utility 进程要显式关闭 stdio 继承。

kNoDefaultSignalHandling(渲染进程) ——

Node 默认会注册 SIGINT、SIGTERM 等信号处理器,用于优雅退出。

但渲染进程的信号应该由 Blink/Chromium 处理(比如 SIGTERM 意味着"浏览器要关你了,赶紧清理")。如果 Node 抢了信号处理器,Chromium 的关停流程会被打断。

为什么只有渲染进程要关,browser 和 utility 不用?因为 browser 进程的 Node 是"主人",它可以管信号;utility 进程是独立的,也可以自己管。渲染进程是"租客",信号权归房东。

kDisableNodeOptionsEnv(fuse 关闭时) ——

NODE_OPTIONS 环境变量允许注入 Node 的启动参数。这是一个安全风险:如果攻击者能控制环境变量,就能往你的应用里注入 --require /tmp/evil.js。

Electron 有 nodeOptions fuse,默认关闭。关闭时,Node 不读 NODE_OPTIONS。这让"用环境变量劫持 Electron 应用"变成不可能。

fuse 打开时(某些场景需要,比如调试),Node 正常读。

disable_wasm_trap_handler = true ——

	// V8::EnableWebAssemblyTrapHandler can be called only once or it will
	// hard crash. We need to prevent Node.js calling it in the event it has
	// already been called.
	node::per_process::cli_options->disable_wasm_trap_handler = true;

这行直接改 Node 的全局 CLI options,绕过 flag 机制。原因:EnableWebAssemblyTrapHandler 只能调一次,第二次硬崩(不是 CHECK,是直接崩)。

Electron 在 5.5.2 已经调过了(如果 fuse 开着)。所以 Node 不能再调。

这个赋值必须在 InitializeOncePerProcess 之前——因为那个函数会读这个选项。

顺序上的细节:disable_wasm_trap_handler 在第 721 行设置,InitializeOncePerProcess 在第 753 行调用。中间隔了 30 行(process_flags 的构造)。这个顺序是有意的。

5.5.5 ParseNodeCliFlags:只放行 12 个选项

std::vector<std::string> NodeBindings::ParseNodeCliFlags() {
	const auto argv = base::CommandLine::ForCurrentProcess()->argv();
	std::vector<std::string> args;
	// TODO(codebytere): We need to set the first entry in args to the
	// process name owing to src/node_options-inl.h#L286-L290 but this is
	// redundant and so should be refactored upstream.
	args.reserve(argv.size() + 2);
	args.emplace_back("electron");
	// Blink owns this V8 flag in renderers and flips it before Node runs; Node
	// enabling it afterwards would write a frozen flag.
	args.emplace_back("--no-js-source-phase-imports");
	for (const auto& arg : argv) {
	...
	const auto stripped = std::string_view{option}.substr(0, option.find('='));
	// Only allow no-op or a small set of debug/trace related options.
	if (IsAllowedOption(stripped) || stripped == "--")
	args.push_back(option);
	}

args.emplace_back("electron") —— 第一个参数是"进程名"。注释说这是 Node 的 node_options-inl.h 要求的(它在解析参数时期望 argv[0] 是程序名),但这个值是假的(不一定是 electron,可能是应用名)。

TODO 说"应该上游重构"。这个 TODO 从 2018 年存在至今。

--no-js-source-phase-imports —— 注释很精确:

Blink owns this V8 flag in renderers and flips it before Node runs; Node enabling it afterwards would write a frozen flag.

js-source-phase-imports 是一个 V8 flag,控制 ESM 的 "source phase imports"(一种新的模块导入语法)。Blink 在渲染进程里会设置它。

如果 Node 也设置一次,而 V8 的 flag 已经冻结(在渲染进程里,Blink 先初始化),这个写入会失败——或者更糟,会触发 V8 的 "flag frozen" 检查。

所以 Electron 强制传 --no-js-source-phase-imports,让 Node 不要去改这个 flag。

IsAllowedOption 的放行名单 —— 这个函数在同一个文件里,是一个 switch。它只放行十几类选项:--inspect、--inspect-brk、--trace-*、--enable-logging、--v、--no-deprecation 等。

为什么只放行这么少? 因为 Electron 的命令行里混着 Chromium 的开关(--type=renderer、--enable-features=...、--lang=zh-CN)。如果全部传给 Node,Node 会因为"未知选项"报错退出。

这是一个"白名单"而不是"黑名单"的选择——正确,因为 Chromium 的开关是不封闭集合(新版本会加),而 Node 的选项是封闭集合。

--experimental-eventsource(renderer/worker) ——

	// Node's setupEventsource() in lib/internal/process/pre_execution.js
	// deletes globalThis.EventSource when --experimental-eventsource is not
	// set, and unlike its sibling setup functions it does not check
	// noBrowserGlobals. Pass the flag so Blink's EventSource is left alone;
	// Node's own undici EventSource is never installed under kNoBrowserGlobals
	// so there is no conflict.

这段注释是本章最精细的一段,值得逐句读。

背景:Node 从某个版本开始内置了 EventSource(SSE 客户端),但它在实验阶段,需要一个 flag 开启。

问题:Node 的 setupEventsource() 函数在 flag 没开时会删除 globalThis.EventSource。而 Blink 在渲染进程里已经提供了 EventSource(浏览器的标准实现)。

所以:Node 启动时就删掉了 Blink 的 EventSource。页面脚本 new EventSource('/stream') 就报 undefined is not a constructor。

**为什么 Node 的其它 setup 函数没这个问题?**因为它们会检查 noBrowserGlobals(Electron 传的 kNoBrowserGlobals flag),如果设了就不覆盖全局。但 setupEventsource() 漏了这个检查——这是 Node 的一个 bug。

Electron 的 workaround:强制传 --experimental-eventsource。这样 Node 走"已开启"的分支,不删除 EventSource。

那 Node 会不会安装它自己的 EventSource(undici 的实现),覆盖 Blink 的?不会——因为注释说 "Node's own undici EventSource is never installed under kNoBrowserGlobals"。在 kNoBrowserGlobals 下,Node 不安装自己的全局。

所以最终结果是:Blink 的 EventSource 保留,Node 的不安装,两边都满意。

这个 workaround 的脆弱性:它依赖"Node 在 flag 打开时不删除全局"这个行为。如果 Node 改了(比如打开 flag 后无条件安装自己的),这个 workaround 就失效,而且是静默失效——页面里 EventSource 变成 Node 的实现,行为微妙地不同。

5.5.6 CreateEnvironment:五个 env_flags 与 from_snapshot

std::shared_ptr<node::Environment> NodeBindings::CreateEnvironment(
	v8::Isolate* isolate,
	v8::Local<v8::Context> context,
	node::MultiIsolatePlatform* platform,
	size_t max_young_generation_size,
	std::vector<std::string> args,
	std::vector<std::string> exec_args,
	std::optional<base::RepeatingCallback<void()>> on_app_code_ready) {
	const std::string process_type(ProcessType());
	// Electron: when consuming the embedded Node startup snapshot, the caller
	// passed an empty context -- the main context is materialized by
	// node::CreateEnvironment from the snapshot and read back here.
	const bool from_snapshot = context.IsEmpty();

from_snapshot 是理解这段代码的钥匙。

正常情况下,context 是 JavascriptEnvironment 创建的(v8::Context::New)。此时 from_snapshot = false。

但如果 Node 的启动快照被启用了(electron_enable_node_startup_snapshot_generation_in_chromium_s_v8.patch,第 4 章提到过),那么 JavascriptEnvironment 不创建 context——它留给 node::CreateEnvironment 从快照里反序列化。

所以 context.IsEmpty() 是一个"我是从快照启动的吗"的探测。

这个设计的影响贯穿整个函数。看这三段:

	auto snapshot_wrapper =
	from_snapshot ? node::EmbedderSnapshotData::BuiltinSnapshotData()
					: node::EmbedderSnapshotData::Pointer{};
	auto* isolate_data =
	node::CreateIsolateData(isolate, uv_loop_, platform,
							/*allocator=*/nullptr, snapshot_wrapper.get());
	isolate_data->max_young_gen_size = max_young_generation_size;
	if (!from_snapshot) {
	set_up_context(context, isolate_data);
	}

CreateIsolateData 的第五个参数是 snapshot data。从快照启动时传 BuiltinSnapshotData()(指向内嵌的快照),否则传空的 Pointer{}。

set_up_context 做的事是:

  1. 在 context 的 embedder data 槽里存 isolate_data 指针
  2. 如果没有 gin::PerContextData,创建一个 ContextHolder

从快照启动时,context 还不存在,所以这段要推迟到 CreateEnvironment 之后。

然后是 env_flags:

	uint64_t env_flags = node::EnvironmentFlags::kDefaultFlags |
					node::EnvironmentFlags::kHideConsoleWindows |
					node::EnvironmentFlags::kNoGlobalSearchPaths |
					node::EnvironmentFlags::kNoRegisterESMLoader;
	if (browser_env_ == BrowserEnvironment::kRenderer ||
	browser_env_ == BrowserEnvironment::kWorker) {
	env_flags |= node::EnvironmentFlags::kNoBrowserGlobals |
				node::EnvironmentFlags::kNoCreateInspector;
	}

kHideConsoleWindows —— Windows 上,如果 Node 的某个操作要弹控制台窗口(比如 child_process.spawn 一个 console 程序),不要弹。Electron 是 GUI 应用,弹黑框很丑。

kNoGlobalSearchPaths —— 不要往 module.paths 里加全局路径(比如 /usr/lib/node_modules)。Electron 应用不应该 require 全局安装的包——那会导致"我的机器上能跑,用户的机器上不能"。

kNoRegisterESMLoader —— 第 4 章的 chore_expose_importmoduledynamically_and.patch 讲过:Electron 要自己装 ESM handler(混合 Node 和 Blink),所以不让 Node 注册。

kNoBrowserGlobals(渲染/worker) —— 不要覆盖 globalThis 上的 fetch、setTimeout、queueMicrotask、EventSource 等等。因为 Blink 已经提供了它们,而且 Blink 的版本和 DOM 集成(比如 fetch 的 CORS 处理)。

注释里指了源码位置:

	// Check //third_party/electron_node/lib/internal/bootstrap/node.js and
	// //third_party/electron_node/lib/internal/bootstrap/web/* for the list
	// of overrides on globalThis.

kNoCreateInspector(渲染/worker) —— 不要在渲染进程创建 Node inspector。因为 Chromium 的 DevTools 已经接管了调试协议。如果 Node 也开一个 inspector,会有两个调试端点,端口冲突。

注意:--inspect 在渲染进程里仍然可用,但它走的是 Electron 自己的 node_bindings 路径,不是 Node 的默认 inspector。这是第 16 章的内容。

kNoStartDebugSignalHandler(fuse 关闭) —— 不监听 SIGUSR1。SIGUSR1 是 Node 的"打开 inspector"信号。如果 nodeCliInspect fuse 关了,这个信号也不该响应——否则用户可以用 kill -USR1 绕过 fuse。

from_snapshot 的第二处分支:

	std::optional<v8::Context::Scope> snapshot_context_scope;
	if (from_snapshot) {
	context = env->context();
	DCHECK(!context.IsEmpty());
	snapshot_context_scope.emplace(context);
	set_up_context(context, isolate_data);
	}

从快照启动时,env->context() 是刚从快照反序列化出来的。它还没被 Enter(V8 的 Context::Scope 是把 context 压栈,让后续的 v8::Context::GetCurrent() 返回它)。

所以这里临时 Enter 一下(snapshot_context_scope),做 set_up_context,然后作用域结束时自动 Exit。

注释说了:

	// When consuming the snapshot, the main context was deserialized inside
	// node::CreateEnvironment and was not entered yet -- enter it for the
	// rest of this function (process-object setup needs a current context).
	// The persistent context Enter() happens in electron_browser_main_parts.cc
	// after this returns.

"persistent Enter 在 electron_browser_main_parts.cc:343-344 里"——就是 5.5 节列表里的第 [9] 步:

	if (context.IsEmpty()) {
	node_env_->context()->Enter();
	}

注意这里用的是 Enter() 而不是 Context::Scope。Enter() 是持久的——它把 context 设为当前,直到 Exit() 被调用。而 Context::Scope 是 RAII 的,作用域结束就退出。

为什么主进程要持久 Enter?因为整个主进程的 JS 执行都在这个 context 里。之后的 JoinAppCode 里的 v8::Context::Scope context_scope(env->context()) 是"确保在执行 uv 回调时 context 正确"——但从 Enter() 之后,context 已经是当前了,那个 Scope 是冗余的吗?

不是。因为 Context::Scope 在退出时会恢复到"进入之前"的状态。如果之前的状态是"已经 Enter 过",那么 Scope 退出后仍然是 Enter 状态。这是嵌套的正确行为。

env_deleter:一个精心设计的析构顺序

	auto env_deleter = [isolate, isolate_data,
					gin_context_holder = std::move(gin_context_holder),
					context = v8::Global<v8::Context>{isolate, context}](
						node::Environment* nenv) mutable {
	// When `isolate_data` was created above, a pointer to it was kept
	// in context's embedder_data[kElectronContextEmbedderDataIndex].
	// Since we're about to free `isolate_data`, clear that entry
	v8::HandleScope handle_scope{isolate};
	gin_context_holder.reset();
	context.Get(isolate)->SetAlignedPointerInEmbedderData(
		kElectronContextEmbedderDataIndex, nullptr,
		v8::kEmbedderDataTypeTagDefault);
	context.Reset();
	node::FreeEnvironment(nenv);
	node::FreeIsolateData(isolate_data);
	};

这个 deleter 是一个 lambda,被 shared_ptr 调用。它的顺序是:

  1. HandleScope —— 因为接下来要操作 V8 对象
  2. gin_context_holder.reset() —— 销毁 gin 的 ContextHolder(它会清理 PerContextData)
  3. 清空 context 的 embedder data 槽 —— 防止悬垂指针
  4. context.Reset() —— 释放 Global handle
  5. FreeEnvironment(nenv) —— 销毁 Node environment
  6. FreeIsolateData(isolate_data) —— 释放 isolate data

为什么这个顺序不能变?

如果先 FreeIsolateData 再 FreeEnvironment,Node 的 environment 析构时会访问 isolate_data(它有指针),就是 use-after-free。

如果不先清 embedder slot,context 的析构(或者后续的 GC)会读到已释放的 isolate_data。

如果不先 reset gin_context_holder,它的析构会去访问 context——但 context 可能已经被 Reset 了。

这是一个"依赖图必须按拓扑序析构"的经典案例。而这个拓扑序的全部信息,只存在于这个 lambda 的语句顺序里——没有注释说"顺序不能变",但改了就会崩。


5.6 LoadAppPackage:三候选、asar、fuse

	// Find the app and apply its package.json; lib/browser/init.ts loads the
	// entry script from what is left here.
	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:87-135。它做的事:在 resources 目录下找三个候选,读 package.json,应用其中的元数据。

三个候选,一个 fuse

	const bool only_asar = fuses::IsOnlyLoadAppFromAsarEnabled();
	std::vector<base::FilePath::StringViewType> candidates;
	if (only_asar) {
	candidates = {FILE_PATH_LITERAL("app.asar")};
	} else {
	candidates = {FILE_PATH_LITERAL("app.asar"), FILE_PATH_LITERAL("app"),
				FILE_PATH_LITERAL("default_app.asar")};
	}
  • app.asar —— 打包后的应用
  • app/ —— 解包的应用目录(开发时)
  • default_app.asar —— 兜底应用(显示"没有找到应用"的界面)

onlyLoadAppFromAsar fuse 打开时,只允许 app.asar。

为什么需要这个 fuse? 因为 app/ 目录是一个攻击面:如果攻击者能在 resources/ 下创建 app/ 目录,就能用它的代码替代 app.asar 里的代码。打开 fuse 后,app/ 被忽略,攻击面消失。

注意 fuse 打开时的额外检查:

	if (only_asar && !asar::GetOrCreateAsarArchive(path))
	continue;

GetOrCreateAsarArchive 不仅检查文件存在,还打开并验证 asar 归档。如果 asar 损坏或者是伪造的,这一步就失败。

asar 与普通目录的统一读取

	std::string json;
	if (!asar::ReadFileToString(path.Append(FILE_PATH_LITERAL("package.json")),
								&json)) {
	continue;
	}

asar::ReadFileToString 同时支持"从 asar 归档里读"和"从真实目录里读"——它检查路径前缀。所以上面三个候选(两个 asar、一个目录)用同一个函数读。

这是一个很好的抽象:调用方不需要知道路径背后是归档还是目录。

BOM 与 UTF-8 的处理

	// As Node reads it: BOM dropped, bad UTF-8 replaced rather than fatal.
	if (!base::IsStringUTF8AllowingNoncharacters(json))
	json = base::UTF16ToUTF8(base::UTF8ToUTF16(json));
	std::string_view json_view(json);
	if (json_view.starts_with("\xEF\xBB\xBF"))
	json_view.remove_prefix(3);
	std::optional<base::Value> manifest = base::JSONReader::Read(
		json_view, base::JSON_REPLACE_INVALID_CHARACTERS);

三步处理,每一步都是为了"和 Node 的行为一致":

  1. 如果不是合法 UTF-8,先做一次 UTF16 往返:UTF8→UTF16→UTF8。这个过程会把无效的字节序列替换成 U+FFFD(replacement character)。Node 的 fs.readFileSync(path, 'utf8') 就是这么做的。

  2. 去掉 BOM:\xEF\xBB\xBF 是 UTF-8 的 BOM。Windows 上的编辑器(尤其记事本)保存 UTF-8 时会加 BOM。Node 的 JSON.parse 遇到 BOM 会失败,所以 Node 的 require 会先剥掉它。Electron 也要剥。

  3. JSON_REPLACE_INVALID_CHARACTERS:JSON 解析时,遇到无效的转义(比如 \x)不要失败,替换掉。

为什么要和 Node 完全一致? 因为 package.json 会被两处读:Electron 的 C++ 读一遍(拿 name/version/main/esm/v8Flags),Node 的 require 再读一遍(当你的代码 require('./package.json') 时)。

如果两处的解析结果不同(比如一处剥了 BOM、一处没剥),就会出现"Electron 认为 main 是 index.js,但你的代码 require('./package.json').main 是 undefined"这种诡异问题。

esm 的判定

	const std::string* type = dict.FindString("type");
	package.esm =
		(type && *type == "module" && !base::EndsWith(package.main, ".cjs")) ||
		base::EndsWith(package.main, ".mjs");

两条规则,和 Node 的规则一致:

  • "type": "module" 且 main 不是 .cjs → ESM
  • main 是 .mjs → ESM(无论 type 是什么)

!EndsWith(main, ".cjs") 这个例外很重要:Node 允许在 "type": "module" 的包里用 .cjs 后缀放 CommonJS 文件。所以如果 main 是 index.cjs,它仍然是 CJS。

这个判定结果被传给 lib/browser/init.ts:105-108,决定用 runEntryPointWithESMLoader 还是 Module._load。

SetPrivate 而不是 Set

	env_context->Global()
		->SetPrivate(env_context,
					v8::Private::ForApi(
						isolate, gin::StringToSymbol(isolate, "appPackage")),
					gin::ConvertToV8(isolate, app_package))
		.Check();

用 v8::Private(私有符号)而不是普通属性。

为什么? 因为如果是普通属性,globalThis.appPackage 会出现在用户的代码里。用户可以读它、改它、甚至用 Object.keys(globalThis) 发现它。

用 Private,用户代码无法访问——只有知道那个 v8::Private 符号的代码才能读。而那个符号是在 C++ 侧用 "appPackage" 字符串创建的,JS 侧的 getHiddenValue(global, 'appPackage') 用同样的字符串能构造出同一个符号(V8 保证 name 相同的 Private 是同一个)。

这是一个在 C++ 和 JS 之间传"内部数据"的标准做法,第 12 章讲 contextBridge 时会再见到。


5.7 从 C++ 交棒给 JS:LoadEnvironment 与 121 行

5.7.1 LoadEnvironment:执行 init bundle

void NodeBindings::LoadEnvironment(node::Environment* env) {
	electron::util::FeedEnvironmentCodeCache(env);
	// The init bundle is this process's entry script: like Node's own runMain it
	// runs without a v8::TryCatch, so an exception thrown while it loads the app
	// reaches process.on('uncaughtException') through V8's message listener.
	//
	// 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, and refresh the options JS cached meanwhile.
	node::DebugOptions* const debug_options = env->options()->get_debug_options();
	const bool break_first_line = debug_options->break_first_line;
	debug_options->break_first_line = false;
	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(), &params)
				.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 的构造方式 ——

const std::string bundle_id =
	"internal/electron/js2c/" + std::string(ProcessType()) + "_init";

ProcessType() 返回 "browser" / "renderer" / "worker" / "utility"。所以 bundle id 是:

  • internal/electron/js2c/browser_init
  • internal/electron/js2c/renderer_init
  • ……

这就是第 3 章讲的七个 bundle(browser/renderer/worker/webview/isolated_renderer/node/utility)在运行时的命名。

注意 isolated_renderer 不在这个列表里——因为 isolate world 的初始化走另一条路(第 12 章)。

break_first_line 的遮蔽 ——

	const bool break_first_line = debug_options->break_first_line;
	debug_options->break_first_line = false;

--inspect-brk 的语义是"在第一行 JS 停下来,等调试器 attach"。

如果不遮蔽,Node 会在 init bundle 的第一行停下来。但用户期望的是"在我的 main.js 第一行停下来"——因为那才是他的代码。

所以 Electron 临时关掉 break_first_line,让 init bundle 顺利跑完,然后在合适的地方(RefreshCachedNodeOptions 之后)恢复。恢复之后,下一个执行 JS 的地方就是用户的入口脚本,调试器在那里停。

RefreshCachedNodeOptions 为什么要在恢复之前调?因为 Node 的 internal/options 模块会缓存 CLI 选项的值。break_first_line 改了之后,缓存里的值是旧的。要让 --inspect-brk 在用户脚本上生效,必须刷新缓存。

这个函数通过 require('internal/options').refreshOptions() 刷新——用一种很"JS"的方式(直接调 Node 的内部模块)来解决一个 C++ 侧的缓存问题。

gin_helper::EmitEvent(..., "loaded") ——

整个 LoadEnvironment 的最后一行,在 process 对象上发一个 loaded 事件。

这个事件是 lib/browser/init.ts:15 里某个 process.on('loaded') 的触发点吗?不是——init.ts 里没有监听 loaded。

那谁监听?是 Node 自己的 internal/bootstrap,或者是 Electron 的 lib/common/init.ts。

这个事件的实际用途是:给"需要知道 Node 环境已经完全就绪"的代码一个钩子。它是一个"内部信号",不是公开 API。

5.7.2 lib/browser/init.ts:121 行的全部

这是启动链路里 JS 侧的唯一入口。121 行,九个段落,每一段的位置都有理由。

第 1 段:EventEmitter.prototype 注入。

process._linkedBinding('electron_browser_event_emitter').setEventEmitterPrototype(EventEmitter.prototype);

Electron 的所有 C++ 对象(app、BrowserWindow、WebContents)都要能 on() / emit()。emit 在 C++ 里,但 on / once / removeListener 是纯 JS。把这个 prototype 交给 C++,C++ 才能把那些方法装到自己的对象上。

必须最先执行——后面所有 require('electron') 都在创建这类对象。

第 2 段:未捕获异常的兜底。

process.on('uncaughtException', function (error) {
	if (process.listenerCount('uncaughtException') > 1) return;   // 用户也注册了,让位
	Promise.resolve().then(() => {
	const { dialog } = require('electron');
	dialog.showErrorBox('A JavaScript error occurred in the main process', ...);
	});
});

> 1 而不是 > 0,因为这个监听器自己算一个。用户注册了就完全让位。

require('electron') 放在 handler 内部而不是文件顶部,注释解释了这个循环依赖:这个文件本身负责建立 require('electron') 的 hook,在顶层调用会拿到半成品。

第 3 段:process.exit 的劫持。

app.on('quit', (_e, exitCode) => { process.emit('exit', exitCode); });
process.exit = ((code) => {
	if (code !== undefined) process.exitCode = code;
	app.exit(process.exitCode || 0);
});

Node 的 process.exit 立即终止,跳过 before-quit / will-quit。Electron 把它映射到 app.exit,走完整关闭流程。

同时用 app.on('quit') 反向补一个 process.emit('exit'),保住 Node 的 exit 事件语义。两句话合起来的效果是:既优雅关闭,又保留 Node 的退出事件。

第 4 段:三个必须提前加载的模块。

ipc-dispatch、rpc-server、guest-view-manager 都是"require 即注册"的副作用模块。它们必须在 ready 之前就绪,否则早期到达的 IPC 消息会丢。

第 5 段:取回 appPackage。

const appPackage = process._linkedBinding('electron_common_v8_util')
	.getHiddenValue(global, 'appPackage');
if (!appPackage) {
	process.nextTick(() => process.exit(1));
	throw new Error('Unable to find a valid app');
}

这是 5.6 节 SetPrivate 的另一端——用同一个字符串构造同一个 Private 符号。

错误处理里 nextTick + exit 与 throw 并存是有意的:throw 触发 uncaughtException 弹框,nextTick 的 exit 保证"即使用户的 handler 不退出,进程也会退"。

第 6 段:四个"确保 ready 时已就绪"的模块。

protocol、service-worker-main、web-contents、web-frame-main 的 require 后面都跟着注释 to ensure it is populated on app ready。它们要在 ready 事件里做事,而 ready 可能与用户代码在同一 tick 触发——懒加载就晚了。

第 7 段:window-all-closed 的默认退出。

app.on('window-all-closed', () => {
	if (app.listenerCount('window-all-closed') === 1) app.quit();
});

=== 1 表示"只有我"。用户注册了监听器,默认退出就不生效——这就是 macOS 应用为什么要显式写 if (process.platform !== 'darwin') app.quit()。

第 8 段:appCodeLoaded 的取出与 v8Flags 的时机。

const { appCodeLoaded } = process;
delete process.appCodeLoaded;
// Applied only now so that everything above still matched its code cache.
if (appPackage.v8Flags) require('v8').setFlagsFromString(appPackage.v8Flags);

appCodeLoaded 是 C++ 通过 process.SetMethod 塞进来的,用完就 delete——它是内部 API,不该出现在 Object.keys(process) 里。

v8Flags 的时机由注释锁死:**必须在所有框架代码加载完之后。**因为改了 V8 flag 之后,按旧 flag 编译的 code cache 就不匹配了。框架代码有 code cache,用户代码没有——所以"最后应用"是唯一安全的位置。这和第 4 章 V8 salt 是同一类问题。

第 9 段:两条入口路径。

if (appPackage.esm) {
	runEntryPointWithESMLoader(async (cascadedLoader) => {
	try {
	await cascadedLoader.import(main.toString(), undefined, Object.create(null));
	appCodeLoaded!();
	} catch (err) { appCodeLoaded!(); process.emit('uncaughtException', err); }
	});
} else {
	appCodeLoaded!();   // 先通知,再加载
	Module._load(path.join(appPackage.path, appPackage.main), Module, true);
}

CJS 分支先调 appCodeLoaded 再 _load——注释说"doesn't matter as _load is synchronous",但先调有一个实际好处:如果用户代码有语法错误导致 _load 抛异常,C++ 已经收到通知,不会卡在 JoinAppCode 里。

ESM 分支必须在 await 之后调——因为 import() 是异步的,提前通知会让 C++ 在模块图还没加载完时就开始下一阶段。

两个分支的 catch 都用 process.emit('uncaughtException') 而不是 throw——在 async 回调里 throw 会变成未处理的 rejection(只触发 warn-with-error-code),手动 emit 才能走到第 2 段的弹框逻辑。


5.8 线程创建与 Toolkit:PreCreateThreads 到 ToolkitInitialized

PostEarlyInitialization 结束时,用户代码已经跑完了。接下来是"为消息循环做准备"。

5.8.1 PreCreateThreads:在起线程之前

int ElectronBrowserMainParts::PreCreateThreads() {
	if (!views::LayoutProvider::Get()) {
	layout_provider_ = std::make_unique<views::LayoutProvider>();
	}
	...

views::LayoutProvider 是 Views UI 框架的布局参数提供者。它在 Get() 返回 null 时才创建——因为 Chromium 可能已经创建了一个(如果某个组件先初始化了)。

#if BUILDFLAG(IS_WIN)
	// Before the first sandboxed child (the GPU process) is launched.
	CheckSandboxedProcessesCanReadInstallDir();
#endif

这个函数在 Windows 上检查"沙箱进程能不能读安装目录"。

为什么需要这个检查?因为沙箱的 Job Object 会给子进程一组受限的权限。如果安装目录(C:/Program Files\YourApp)的 ACL 不允许"受限令牌"读,GPU 进程就加载不了它需要的 DLL,然后崩溃——而且崩溃信息很难懂("GPU process isn't usable")。

提前检查,就能给出明确的错误。

locale 的三条路径(electron_browser_main_parts.cc:429-492)最值得看。

	// Fetch the system locale for Electron.
#if BUILDFLAG(IS_MAC)
	fake_browser_process_->SetSystemLocale(GetCurrentSystemLocale());
#else
	fake_browser_process_->SetSystemLocale(base::i18n::GetConfiguredLocale());
#endif

macOS 用 GetCurrentSystemLocale()(读 Cocoa 的 NSLocale),其它平台用 base::i18n::GetConfiguredLocale()(读环境变量)。

然后是 macOS 的那段注释:

#if BUILDFLAG(IS_MAC)
	// On macOS, l10n_util::GetApplicationLocale() returns the --lang value
	// verbatim instead of resolving it against the locales that actually ship
	// (Chromium relies on Cocoa having already done that). A tag like "de-DE"
	// therefore fails to find de.lproj and no locale pak is loaded at all,
	// which leaves every localized string empty. Resolve it the same way the
	// other platforms do, and fall back to Cocoa's choice if it can't be
	// resolved.
	if (!locale.empty())
	locale = l10n_util::CheckAndResolveLocale(locale).value_or(std::string());

这段话描述了一个非常具体的故障:在 macOS 上传 --lang=de-DE 会导致所有本地化字符串变成空。

链条是:

  1. GetApplicationLocale("de-DE") 在 macOS 上原样返回 "de-DE"
  2. 资源查找用 de-DE.lproj 去找
  3. 但实际打包的是 de.lproj(Cocoa 的命名约定)
  4. 找不到 → 不加载任何 locale pak
  5. 所有 IDS_* 字符串查不到 → 返回空

Chromium 在 macOS 上不会遇到这个问题,因为它依赖"Cocoa 已经把 locale 规范化过了"——Chrome 的 --lang 从 Cocoa 来,本身就是规范形式。

Electron 的 --lang 可能来自用户在 package.json:86 或者启动参数里随便写,所以必须自己规范化。

Linux 的处理更绕:

#elif BUILDFLAG(IS_LINUX)
	// l10n_util::GetApplicationLocaleInternal uses g_get_language_names(),
	// which keys off of getenv("LC_ALL").
	// We must set this env first to make ui::ResourceBundle accept the custom
	// locale.
	auto env = base::Environment::Create();
	std::optional<std::string> lc_all;
	if (!locale.empty()) {
	lc_all = env->GetVar("LC_ALL");
	env->SetVar("LC_ALL", locale);
	}
#endif

Linux 的 locale 解析走 g_get_language_names()(glib 的函数),它读 LC_ALL 环境变量。

所以要"临时改 LC_ALL → 加载资源 → 恢复 LC_ALL"。注意 lc_all 用 std::optional 保存:区分"原来是空"和"原来有值"。

恢复的代码在 484-492 行,注意 env->UnSetVar("LC_ALL") 那个分支——如果原来是没设的,就 unset 而不是设成空字符串。这个区别很重要:LC_ALL="" 和没有 LC_ALL 在 glib 眼里是不同的(前者表示"用空 locale")。

5.8.2 ToolkitInitialized:GTK 的两个陷阱

void ElectronBrowserMainParts::ToolkitInitialized() {
#if BUILDFLAG(IS_LINUX)
	// GTK3's gtk_init() probes the display for OpenGL and loads the GL driver
	// into this process; nothing here uses GdkGLContext. GDK_GL is read once at
	// init and only by GTK3 (GTK4 renders with GL itself and ignores it).
	auto env = base::Environment::Create();
	constexpr char kGdkGl[] = "GDK_GL";
	const bool restore_gdk_gl = !env->HasVar(kGdkGl);
	if (restore_gdk_gl)
	env->SetVar(kGdkGl, "disable");
	auto* linux_ui = ui::GetDefaultLinuxUi();
	if (restore_gdk_gl)
	env->UnSetVar(kGdkGl);

第一个陷阱:GTK3 在 gtk_init() 时会探测 OpenGL,把 GL 驱动加载进主进程。

后果:一个本不该有 GL 的进程里多了一份 GL 驱动(几十 MB 内存 + 一堆线程)。而且如果驱动有 bug,会污染主进程。

修法:初始化期间临时设 GDK_GL=disable,初始化完就恢复。restore_gdk_gl 这个变量保证"只恢复我们改过的"——如果用户自己设了 GDK_GL,不去动它。

第二个陷阱在 PostEarlyInitialization 里(5.5 节列表第 [7]、[16] 步):Pango 的 FcInit 竞态。

// Pango >= 1.52 calls FcInit() from its own thread while the main thread does
// the same during GTK init, corrupting FontConfig state (pango#784). Doing it
// once beforehand makes both later calls no-ops.
class SystemFontConfigInit : public base::PlatformThread::Delegate {
	public:
	void ThreadMain() override {
	base::PlatformThread::SetName("SystemFontConfigInit");
	if (auto fc_init =
			reinterpret_cast<int (*)()>(SystemFontConfigSymbol("FcInit"))) {
	fc_init();
	}
	}
};

Pango 1.52+ 会从自己的线程调 FcInit(),而主线程在 GTK 初始化时也调。FontConfig 的 FcInit 不是线程安全的(它是"初始化一次"的惰性模式,但检查-初始化之间有竞态窗口),两边同时进来会破坏内部状态。

解法:提前在主线程之外的线程里调一次,让后续两次调用都变成 no-op(因为已经初始化了)。

注意 SystemFontConfigSymbol 用 dlopen("libfontconfig.so.1") + dlsym 而不是直接链接:

// Resolved via dlsym: a direct reference would bind to Chromium's bundled
// FontConfig rather than the system copy GTK and Pango use.

Electron 打包了一份 FontConfig(Chromium 的 third_party)。如果直接调用 FcInit,链接器会绑定到 bundled 的那份——但 GTK 和 Pango 用的是系统的 libfontconfig.so.1。两份不同的 FontConfig 各有各的全局状态,调用 bundled 的 FcInit 对系统那份毫无作用。

dlsym 强制走动态查找,拿到的是系统的符号。

这是一个符号可见性问题:静态链接的第三方库会被优先绑定,要访问"系统版本"必须绕过链接器。


5.9 PreMainMessageLoopRun:ready 在这里发射

这是本章第二个关键函数(electron_browser_main_parts.cc:600-661)。

int ElectronBrowserMainParts::PreMainMessageLoopRun() {
	// Run user's main script before most things get initialized, so we can have
	// a chance to setup everything.
	node_bindings_->PrepareEmbedThread();
	node_bindings_->StartPolling();
	// url::Add*Scheme are not threadsafe, this helps prevent data races.
	url::LockSchemeRegistries();
	...

5.9.1 启动 embed 线程

PrepareEmbedThread()(node_bindings.cc:1068-1094)做两件事:

	if (!embed_thread_prepared_) {
	// Add dummy handle for libuv, otherwise libuv would quit when there is
	// nothing to do.
	uv_async_init(uv_loop_, dummy_uv_handle_.get(), nullptr);
	// Start worker that will interrupt main loop when having uv events.
	uv_sem_init(&embed_sem_, 0);
	embed_thread_prepared_ = true;
	}
	uv_thread_create(&embed_thread_, EmbedThreadRunner, this);

uv_async_init 的"dummy handle" —— libuv 的 uv_run 在没有活跃 handle 时会立即返回(认为"没事可做,退出")。但 Electron 需要一个"永远有事可做"的 loop,否则 uv_run(UV_RUN_NOWAIT) 每次都返回 0,触发 QuitWhenIdle()。

所以注册一个 dummy 的 async handle,让它永远处于"活跃"状态。uv_async_send 可以唤醒它。

embed_thread_ —— 这是 Electron 双事件循环架构的核心。它的循环体(EmbedThreadRunner,第 1192-1213 行):

void NodeBindings::EmbedThreadRunner(void* arg) {
	auto* self = static_cast<NodeBindings*>(arg);
	while (true) {
	// Wait for the main loop to deal with events.
	uv_sem_wait(&self->embed_sem_);
	if (self->embed_closed_)
	break;
	// Wait for something to happen in uv loop.
	self->PollEvents();
	if (self->embed_closed_)
	break;
	// Deal with event in main thread.
	self->WakeupMainThread();
	}
}

三步循环:等信号 → 阻塞 poll → 唤醒主线程。

这个线程存在的唯一理由是:libuv 的 uv_run(UV_RUN_NOWAIT) 不能阻塞。

主线程的 UvRunOnce(第 1143-1179 行)用的是 UV_RUN_NOWAIT——它只处理"已经就绪"的事件,不等待。因为主线程还要跑 Chromium 的消息循环,不能被 uv 的事件阻塞。

但"已经有就绪事件"这件事需要有人去发现。uv__io_poll 是阻塞的(它调 epoll_wait)。所以让 embed 线程去做阻塞 poll,发现有事件时通过 uv_sem_post 唤醒主线程,主线程再 uv_run(NOWAIT) 处理。

这就是第 6 章要展开的"两个事件循环的婚姻"的物理基础。这里只需要记住:主线程从不阻塞在 uv 上,阻塞发生在一个专用的 embed 线程里。

uv_sem 是一个二值信号量,用来做"主线程处理完了,你可以继续 poll"的握手:

	uv_loop_interrupt_suspend(uv_loop_);
	int r = uv_run(uv_loop_, UV_RUN_NOWAIT);
	uv_loop_interrupt_resume(uv_loop_);
	...
	// Tell the worker thread to continue polling.
	uv_sem_post(&embed_sem_);

uv_loop_interrupt_suspend/resume 是一对 Electron 自己加的 API(第 4 章的 feat_add_uv_loop_interrupt_on_io_change_option_to_uv_loop_configure.patch)。注释解释了原因:

	// The embed thread is parked on |embed_sem_| until we post it below and
	// re-reads uv_backend_timeout() before polling, so skip the interrupts.

embed 线程此时正停在 uv_sem_wait 上,还没开始 poll。所以"uv loop 的 io 变了,快去重新计算超时"这种中断是不必要的——它马上就要重新读了。跳过中断省掉一次系统调用。

5.9.2 LockSchemeRegistries

	// url::Add*Scheme are not threadsafe, this helps prevent data races.
	url::LockSchemeRegistries();

对应 5.3.7 节的 ShouldLockSchemeRegistry() 返回 false。

Electron 不让 content 层在早期锁,因为应用需要 protocol.registerSchemesAsPrivileged()。但消息循环一开始,多个线程都会访问 scheme registry,必须锁。

所以在这个"最后一刻"锁上。这是"推迟锁定"策略的落点。

5.9.3 WillFinishLaunching / DidFinishLaunching:ready 的真正发射

#if !BUILDFLAG(IS_MAC)
	// The corresponding call in macOS is in ElectronApplicationDelegate.
	Browser::Get()->WillFinishLaunching();
	Browser::Get()->DidFinishLaunching(base::DictValue());
#endif
	// Notify observers that main thread message loop was initialized.
	Browser::Get()->PreMainMessageLoopRun();

非 macOS 上,DidFinishLaunching 在这里调。macOS 上在 ElectronApplicationDelegate 里调。

为什么 macOS 不同?因为 macOS 的启动流程由 NSApplication 驱动——applicationDidFinishLaunching: 是 Cocoa 的回调,它的时机由 AppKit 决定,不受 Chromium 控制。

这个差异有一个可观测的后果:在 macOS 上,ready 可能在 PreMainMessageLoopRun 之后才发,因为 NSApplication 的 runloop 要先跑起来。

Browser::DidFinishLaunching(browser.cc:241-258):

void Browser::DidFinishLaunching(base::DictValue launch_info) {
	// Make sure the userData directory is created.
	ScopedAllowBlockingForElectron allow_blocking;
	base::FilePath user_data;
	if (base::PathService::Get(chrome::DIR_USER_DATA, &user_data)) {
	base::CreateDirectoryAndGetError(user_data, nullptr);
#if BUILDFLAG(IS_WIN)
	base::SetExtraNoExecuteAllowedPath(chrome::DIR_USER_DATA);
#endif
	}
	is_ready_ = true;
	if (ready_promise_)
	ready_promise_->Resolve();
	for (BrowserObserver& observer : observers_)
	observer.OnFinishLaunching(launch_info.Clone());
}

三件事,顺序有讲究:

第一,创建 userData 目录。 对应 5.3.3 节 PreSandboxStartup 里"只覆盖不创建"的决定。这里才真正创建,因为到这一步,应用的名称和路径都已经通过 app.setName / app.setPath 定型了。

ScopedAllowBlockingForElectron —— Chromium 默认禁止在 UI 线程做阻塞 IO(会 DCHECK 失败)。创建目录是阻塞 IO,所以要显式允许。

SetExtraNoExecuteAllowedPath(Windows)—— 把 userData 加到"允许非可执行区域"列表。Windows 有一个缓解措施:从"下载目录"之类的路径加载的 DLL 会被阻止。userData 里可能放原生模块(.node),要允许加载。

第二,is_ready_ = true 和 resolve promise。

顺序很重要:先设置标志,再 resolve。

因为 WhenReady() 的逻辑是:

v8::Local<v8::Value> Browser::WhenReady(v8::Isolate* isolate) {
	if (!ready_promise_) {
	ready_promise_ = std::make_unique<gin_helper::Promise<void>>(isolate);
	if (is_ready()) {
	ready_promise_->Resolve();
	}
	}
	return ready_promise_->GetHandle();
}

如果 is_ready() 已经是 true,新建的 promise 立刻 resolve(返回一个已完成的 Promise)。

如果顺序反了(先 resolve 再设标志),那么在 DidFinishLaunching 执行到一半时,如果 JS 侧调 WhenReady(),会拿到一个未 resolve 的 promise,然后永远不会被 resolve——因为 ready_promise_ 已经存在,DidFinishLaunching 里的 if (ready_promise_) 会 resolve 它。等等,那样其实也没问题。

真正的理由更微妙:Promise::Resolve() 会触发 JS 侧的 .then 回调在微任务里执行。如果此时 is_ready_ 还是 false,那些回调里调 app.isReady() 会得到 false——用户会看到"进了 ready 回调但 isReady() 是 false"这种矛盾。

所以必须先设标志。

第三,通知 observers。

observers_ 是 BrowserObserver 的列表,包括 App(发 ready 事件)、AutoUpdater、PowerMonitor 等。

App::OnFinishLaunching(electron_api_app.cc:632-640):

void App::OnFinishLaunching(base::DictValue launch_info) {
#if BUILDFLAG(IS_LINUX)
	// Set the application name for audio streams shown in external
	// applications. Only affects pulseaudio currently.
	media::AudioManager::SetGlobalAppName(Browser::Get()->GetName());
#endif
	Emit("ready", base::Value(std::move(launch_info)));
}

Emit("ready", ...) —— 这就是用户代码里 app.on('ready', ...) 的那个事件。而 whenReady() 的 promise 在上一行 ready_promise_->Resolve() 里已经兑现。

所以 ready 事件和 whenReady() 的 promise 是两个不同的机制,但同一时刻触发。

它们的顺序:Resolve() 先(微任务排队),Emit("ready") 后(同步调用监听器)。所以如果你的代码同时用两种方式:

app.on('ready', () => console.log('event'))
app.whenReady().then(() => console.log('promise'))

输出是 event 然后 promise——因为 Emit 是同步的,Resolve 排的微任务要等到当前同步执行完。

5.9.4 回到本章开头的问题

现在可以完整回答 5.0 节的问题了。

为什么 require('electron') 在 main.js 顶层就能拿到 app?

因为 app 对象在 PostEarlyInitialization 的 electron_bindings_->BindTo(isolate, node_env_->process_object()) 之前就已经构造了(ElectronBrowserMainParts 构造函数的第 4 个成员 browser_)。而 require('electron') 走的是 lib/browser/api/exports/electron.ts → lib/browser/api/module-list.ts,那里把 C++ 注册的 electron_browser_app 绑定转成 JS 模块。

也就是说:app 是一个 C++ 对象,在 JS 环境创建之前就存在了。JS 侧只是拿了一个包装。

为什么 app.isReady() 是 false?

因为 is_ready_ 在 Browser::DidFinishLaunching 里才被设成 true,而那个调用发生在 PreMainMessageLoopRun 里——也就是 JoinAppCode 返回之后。

为什么 .then 的回调在你代码之后执行?

因为 whenReady() 返回的 promise 此刻还没被 resolve。它被存进 ready_promise_,等到 DidFinishLaunching 时统一 resolve,然后微任务队列在下一个 checkpoint 执行 .then。

关键点:**这个"之后"不是"下一个 tick",而是"整整一个消息循环阶段之后"。**中间隔着 PreCreateThreads、ToolkitInitialized、PreCreateMainMessageLoop 三个阶段的全部工作。

这也解释了一个常见困惑:为什么在 main.js 顶层 await 一个 setTimeout(0),app.isReady() 仍然是 false?

因为 setTimeout(0) 的定时器要靠 uv loop 跑,而 uv loop 的运行依赖 embed 线程 + 主线程的 UvRunOnce。而 JoinAppCode 的 while 循环恰好在泵 uv——所以 setTimeout 的回调会在 JoinAppCode 里执行,那时候 DidFinishLaunching 还没发生。


5.10 消息循环的启动与 PostCreateMainMessageLoop

void ElectronBrowserMainParts::WillRunMainMessageLoop(
	std::unique_ptr<base::RunLoop>& run_loop) {
	exit_code_ = content::RESULT_CODE_NORMAL_EXIT;
	Browser::Get()->SetMainMessageLoopQuitClosure(
	run_loop->QuitWhenIdleClosure());
}

SetMainMessageLoopQuitClosure 把"怎么退出主循环"这个能力交给 Browser。之后 app.quit() 就能通过这个闭包让 run_loop 退出。

exit_code_ 在这里才被赋值(std::optional<int>)。在这之前 SetExitCode() 会返回 false:

bool ElectronBrowserMainParts::SetExitCode(int code) {
	if (!exit_code_)
	return false;
	content::BrowserMainRunner::SetOverrideResultCode(code);
	*exit_code_ = code;
	return true;
}

所以在 ready 之前调 app.exit(1) 是无效的——exit_code_ 还没初始化。这是一个容易踩的坑。

PostCreateMainMessageLoop(第 670-722 行)是平台大杂烩:

Linux 的 ExitOnSessionLoss ——

// The display server connection or the session bus is gone: exit like
// Chrome's SessionEnding(), with an off-thread watchdog that crashes us if
// exiting hangs on the dead connection.
void ExitOnSessionLoss() {
	class ShutdownWatchdogDelegate : public base::Watchdog::Delegate {
	public:
	void Alarm() override { LOG(FATAL) << "Failed to shutdown."; }
	};
	static base::NoDestructor<ShutdownWatchdogDelegate> delegate;
	static base::NoDestructor<base::Watchdog> watchdog(
	base::Seconds(10), "SessionLossShutdown", /*enabled=*/true,
	delegate.get());
	watchdog->Arm();
	if (Browser* browser = Browser::Get())
	browser->ExitWithCode(content::RESULT_CODE_NORMAL_EXIT);
}

用户注销、或者 SSH 断开导致 X11/Wayland 连接断开时,应用要退出。

但退出过程可能卡住——因为退出路径上有代码在往已经死掉的连接上写数据(比如关闭窗口时通知 WM)。写一个死 socket 会阻塞到超时(可能 30 秒)。

所以启动一个 10 秒的看门狗:如果 10 秒还没退完,LOG(FATAL) 强制崩溃退出。

这是一个"优雅退出"与"必须退出"之间的兜底。base::Watchdog 是一个独立线程的定时器,不受主线程卡死影响。

Linux 的 os_crypt 配置(第 684-711 行)—— 这段必须在 NetworkService 启动之前,因为加密的 cookie 需要密钥,而密钥要在进程间共享。

POSIX 的信号处理器 ——

#if BUILDFLAG(IS_POSIX)
	// Exit in response to SIGINT, SIGTERM, etc.
	InstallShutdownSignalHandlers(
	base::BindOnce(&Browser::Quit, base::Unretained(Browser::Get())),
	content::GetUIThreadTaskRunner({}));
#endif

Ctrl+C、kill、systemd 的 stop,都走这条路。

注意 base::Unretained(Browser::Get()) —— 不持有引用。因为 Browser 的生命周期由 ElectronBrowserMainParts 管,信号处理器不应该延长它。如果信号在 Browser 析构之后到达,这里是 use-after-free——但那种情况下进程已经在退出了,信号的语义本来就是"快退"。


5.11 关闭:PostMainMessageLoopRun 的顺序

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();
	...
}

七个步骤,每一步的顺序都是被依赖关系锁死的。

为什么先关 DownloadManager? 因为 DownloadItem 的回调是 JS 对象(downloadItem.on('done', ...))。如果 Node 先停,那些 JS 回调就成了对已销毁环境的引用,触发时崩溃。

为什么先关 utility process? 注释说得很清楚:要"so that exit events can be emitted"。utility process 的 exit 事件是 JS 层能感知的,需要 Node 还活着。

而且注意那个补充说明:

	// This includes wrappers whose child is still launching; otherwise they
	// would only be torn down with the heap, after Node.js has stopped.

ShutdownAll() 包括"还在启动中的" utility process——否则它们会在堆销毁时才被清理,而那时 Node 已经停了。

node::Stop(..., kDoNotTerminateIsolate) —— 停 Node 但不销毁 isolate。

为什么不销毁?因为 js_env_ 还持有 isolate(js_env_.reset() 在下一行)。isolate 的销毁要走 JavascriptEnvironment 的析构,那里有精确的顺序(先 isolate_holder_.reset() 再 platform_->UnregisterIsolate(isolate),见 5.5.3 节引的代码)。

如果 node::Stop 顺便销毁了 isolate,那个顺序就被破坏了。

set_uv_env(nullptr) 必须在 node_env_.reset() 之前。

因为 env_deleter 里的 FreeEnvironment 会访问 uv loop。如果 uv_env 还指着这个环境,后续的 UvRunOnce(可能被异步投递)就会拿到一个悬垂指针。

set_uv_env(nullptr) 之后,UvRunOnce 开头的 if (!env) return; 会保护住。


5.12 三平台差异速查

阶段LinuxWindowsmacOS
入口main()wWinMainmain() → ElectronMain()
沙箱seccomp + namespace(zygote)Job Object / AppContainerSeatbelt
沙箱初始化时机zygote forkInitializeSandboxInfo → ContentMainSeatbeltExecServer(helper)
日志预初始化PreSandboxStartup(含 zygote)SandboxInitializedPreSandboxStartup
ready 发射点PreMainMessageLoopRunPreMainMessageLoopRunElectronApplicationDelegate
信号处理SIGCHLD + InstallShutdownSignalHandlers无(用 WER)无(用 NSApplication)
特殊GTK/Pango/FontConfig 三重坑crashpad-handler 分支 / SUI / DPIapp shim / framework 定位 / Prefetch

**表格里最需要记住的一行是 ready 的发射点。**macOS 不同,意味着"ready 之前能做多少事"在三个平台上不一样——这是很多跨平台 bug 的来源。


5.13 十个启动问题速查

Q1:app.getPath('userData') 在 ready 前能用吗? 能,但值是"默认推导值"。app.setName() 在 ready 前调用会改变它;ready 之后调用无效。

Q2:为什么 process.exit(1) 在主进程里不立即退出? 因为 lib/browser/init.ts 把它劫持成了 app.exit()(5.7.2 节第 3 段)。要走 Node 语义,用 process.reallyExit() 或者 app.exit() 直接。

Q3:app.exit(1) 在 ready 前调用为什么没效果? 因为 exit_code_ 是 std::optional,在 WillRunMainMessageLoop 才被赋值(5.10 节)。

Q4:为什么改了 package.json 的 main 不生效? LoadAppPackage 在 PostEarlyInitialization 里读,而且读的是 resources/app.asar 或 resources/app/ 下的那份——不是项目根目录的(5.6 节)。

Q5:v8Flags 为什么有时生效有时不生效? 它只在所有框架代码加载完之后才应用(5.7.2 节第 8 段)。如果某个 flag 影响的是框架代码的编译,它来不及。

Q6:为什么 --inspect-brk 停在 main.js 而不是 init.ts? 因为 break_first_line 被临时遮蔽了(5.7.1 节)。

Q7:ready 事件和 whenReady() 谁先? ready 事件先(同步 Emit),whenReady() 的 .then 后(微任务)。

Q8:为什么 mac 上 ready 比 win/linux 晚? 因为 macOS 的 DidFinishLaunching 由 NSApplication 驱动(5.9.3 节)。

Q9:ELECTRON_RUN_AS_NODE=(空值)会进 Node 模式吗? 不会。IsEnvSet 检查 *indicator,空字符串不算设置(5.1.1 节)。

Q10:window-all-closed 不写监听器会怎样? Electron 自动 app.quit();写了监听器就完全由你控制(5.7.2 节第 7 段)。


5.14 本章小结

五条结论。

结论一:启动链路的本质是"两次控制权反转"。

C++ → JS(LoadEnvironment 执行 init bundle),然后 JS → C++(JoinAppCode 阻塞等待)。你的 main.js 就执行在第二次反转之前的那段窗口里。理解这一点,才能理解"为什么 app 存在但 isReady() 是 false"。

结论二:初始化顺序的约束几乎全部来自"谁先占坑"。

  • V8 平台只能 InitializePlatform 一次 → create_v8_platform = false(第 4 章的补丁)
  • EnableWebAssemblyTrapHandler 只能一次 → disable_wasm_trap_handler = true
  • FieldTrialList 必须在 Mojo 之前 → PreBrowserMain 里的顺序
  • WASM trap handler 必须在 isolate 之前 → 否则只是变慢,无报错
  • scheme registry 不能早锁也不能不锁 → ShouldLockSchemeRegistry() = false + 手工晚锁

结论三:ready 不是一个"事件",是一个"状态 + 两个通知机制"。

is_ready_ 是状态,ready_promise_ 和 Emit("ready") 是两个通知。三者在 DidFinishLaunching 里按"先状态、再 promise、最后事件"的顺序处理。

结论四:启动路径上每一个"看起来多余"的判断,都有一次事故在背后。

process.listenerCount(...) > 1、restore_gdk_gl、if (context.IsEmpty())、if (only_asar && !GetOrCreateAsarArchive(path))——这些条件的形状都很奇怪,因为它们是"针对某个具体故障的补丁",不是"通用设计"。

读这类代码的正确方式是:**先假设它有意义,再去找那个意义。**找不到意义再怀疑它是遗留垃圾。

结论五:macOS 是唯一的例外制造者。

ready 的发射点、沙箱的初始化方式、日志的初始化时机、入口函数的分层——四件事上 macOS 都和另外两个平台不同。跨平台 bug 的排查,应该从"这个平台上这条路径是不是不一样"开始。


5.15 练习题

练习 5.1(入门) 在 main.js 里打印 app.isReady(),然后在 app.whenReady() 的第一个 .then 里再打印一次。解释两次的值。再用 setTimeout(() => console.log(app.isReady()), 0) 打印第三次,解释为什么它仍然是 false。

练习 5.2(入门) 运行 ELECTRON_RUN_AS_NODE=1 ./your-app -e "console.log(process.versions.electron, process.type)"。解释 process.type 为什么是 undefined。

练习 5.3(进阶) 找到 electron_browser_main_parts.cc:448 里 PreCreateThreads 对 macOS locale 的处理。如果去掉 l10n_util::CheckAndResolveLocale 那一行,在 macOS 上传 --lang=de-DE 会发生什么?给出可验证的观察方式。

练习 5.4(进阶) NodeBindings::CreateEnvironment 的 env_deleter 有六步。如果把 FreeEnvironment 和 FreeIsolateData 的顺序对调,会在什么场景下崩溃?用 ASAN 构建验证。

练习 5.5(进阶) 阅读 EmbedThreadRunner 和 UvRunOnce,画出"主线程处理一个 uv timer 回调"的完整握手时序(包括 uv_sem 的两次 post/wait)。

练习 5.6(深入) 5.5.5 节说 IsAllowedOption 是白名单。找出它的完整实现,列出所有放行的选项。然后解释:为什么 --max-old-space-size 不在列表里?如果用户想设它,应该怎么做?

练习 5.7(深入) lib/browser/init.ts 第 8 段把 v8Flags 放在最后应用。假设你把它移到文件开头,什么情况下会出现问题?构造一个具体的复现场景。

练习 5.8(深入) process.exit 被劫持成 app.exit。找一个场景,证明这个劫持会导致和 Node 语义不一致的可观测行为(提示:process.on('exit') 里做异步操作)。

练习 5.9(挑战) 写一个最小程序,在 app.whenReady() 之前调用 app.exit(1),观察行为。然后读 SetExitCode 和 WillRunMainMessageLoop,解释为什么行为是这样。再给出一个"确实能在 ready 前退出"的写法。

练习 5.10(挑战) 5.8.2 节的 SystemFontConfigInit 用 dlopen + dlsym 绕过链接器。用 LD_DEBUG=bindings(Linux)或 DYLD_PRINT_BINDINGS(macOS)验证"直接调用会绑定到 bundled 版本"这个说法。


5.16 下一章预告

第 6 章《Node.js 集成:两个事件循环的婚姻》会接住本章留下的三条线:

第一条线:5.9.1 节的 EmbedThreadRunner 三步循环。那一章会把 uv_backend_timeout、uv_loop_interrupt_*、PollEvents() 的派生实现全部展开,回答"为什么需要两个线程才能跑一个事件循环"。

第二条线:5.5.3 节的 node::MultiIsolatePlatform。那一章会讲 RegisterIsolate(isolate, loop) 在渲染进程里怎么用——因为渲染进程可能有多个 isolate(Blink 的、Node 的、worker 的)。

第三条线:5.5.6 节的 kNoBrowserGlobals 和微任务策略(kExplicit vs kScoped)。那一章会解释 MicrotasksRunner 为什么是 TaskObserver,以及为什么渲染进程要在 UvRunOnce 里临时把策略切成 kExplicit。

那三条线合起来,回答一个更大的问题:为什么 Electron 不能直接把 Node 塞进浏览器进程?

5.17 本章源码落点索引

下列位置全部来自本仓库源码树,按实现层归集;每个 路径:行号 指向该文件中与本章论述对应的声明或实现行,可逐条复核。

  • 浏览器进程 C++ 层:electron_browser_main_parts_mac.mm:23 electron_browser_main_parts_posix.cc:30 electron_api_service_worker_context.cc:30 electron_api_service_worker_context.h:22 electron_api_service_worker_main.cc:44 electron_api_service_worker_main.h:27 load_url_promises.cc:27 load_url_promises.h:32
  •  electron_crypto_module_delegate_nss.cc:13 electron_crypto_module_delegate_nss.h:13 electron_download_manager_delegate.cc:50 electron_download_manager_delegate.h:14 electron_preconnect_manager_delegate.cc:9 electron_preconnect_manager_delegate.h:13 electron_speech_recognition_manager_delegate.cc:13 electron_speech_recognition_manager_delegate.h:13
  •  renderer_startup_data.cc:38 renderer_startup_data.h:11 web_view_guest_delegate.cc:22 web_view_guest_delegate.h:19 zoom_level_delegate.cc:34 zoom_level_delegate.h:17 electron_bluetooth_delegate.cc:34 electron_bluetooth_delegate.h:19
  • shell 其余实现:electron_main_delegate_mac.h:13 electron_main_delegate_mac.mm:26 app_shim_main_delegate.h:17 app_shim_main_delegate.mm:41 js2c_bundle_ids.h:49
  • 其他相关位置:strip_framework.py:6 api-ipc-renderer.spec.ts:9 api-service-worker-main.spec.ts:13 api-service-workers.spec.ts:13 build-instructions-windows.md:3 debugging-on-windows.md:19 windows-arm.md:20 windows-store-guide.md:31
  •  windows-taskbar.md:2 verify-chromedriver.py:9
  • JS 门面与运行时:service-worker-main.ts:3 ipc-renderer-internal-utils.ts:3 ipc-renderer-internal.ts:1 ipc-renderer.ts:1
  • 构建配置:bundle.gni:1 bundle.mjs:23 make_locale_dirs.py:15
  • API 文档与类型:ipc-main-service-worker.md:5 ipc-renderer.md:2 service-worker-main.md:5 service-workers.md:5 custom-scheme.md:3 ipc-main-service-worker-event.md:3 ipc-main-service-worker-invoke-event.md:3 ipc-renderer-event.md:3
  •  resolved-endpoint.md:3 resolved-host.md:3 service-worker-info.md:3 shared-worker-info.md:3