《Electron 45.2.3 内核解剖》第 11 章 `WebContents` 解剖:6184 行的中枢

0 阅读1小时+

《Electron 45.2.3 内核解剖》第 11 章 WebContents 解剖:6184 行的中枢

第 10 章留下了三条线,都指向同一个类。

WebContentsView 在 WebContents 销毁后变成"视图还在、内容没了"的空壳;"这个 WebContents 属于哪个窗口"有三个答案;<webview> 的 guest 身份是"spread 在 6000 行里的 if 分支"。三条线最后都落到 electron_api_web_contents.cc——Electron 仓库里最长的单个文件之一,6184 行。

这一章要回答的问题不是"它有哪些 API",而是:一个对象凭什么能同时是观察者、委托、输入观察器、对话框管理器、DevTools 宿主、离屏渲染器和 Node 事件发射器,而且这些身份之间没有一层抽象隔开。

答案会落在两句话上。第一句:content::WebContents 本来就是 Chromium 里最长的那根柱子,Electron 没有拆它,只在外面包了一层。第二句:包装层选择用**多重继承 + 一套统一的 Emit**来粘合十三个基类,而不是用组合——这个选择省掉了所有转发样板,代价是所有子系统共享同一个生命周期和同一个 V8 wrapper。

11.0 三层规模与一条主线

先把规模摆出来。这不是为了炫数字,而是因为一个类的复杂度几乎总能从"它有多大、被切成几块"看出来。

层文件行数职责
头文件electron_api_web_contents.h103213 个基类、6 种 Type、约 180 个方法声明、40 个成员
实现electron_api_web_contents.cc6184全部行为:导航、销毁、输入、DevTools、打印、脚本注入、IPC
macOS 补充electron_api_web_contents_mac.mm109键盘事件的一条 Objective-C 分支
JS 门面web-contents.ts471_init 里的三个对象、10 个废弃 API 的包装、5 个导出函数

头文件 1032 行、实现 6184 行,比例是 1:6。这个比例在 C++ 项目里偏高——说明大部分复杂度在实现里,而不在接口里:接口是几十行一组的转发声明,实现里则是每个 Chromium 回调各自一套状态机。

11.0.1 6184 行是怎么分布的

按功能把行号切成段,会看到一块很不均匀的分布:

行区间长度内容
1–800800头文件包含、匿名命名空间的工具函数(DPI、颜色、UserDataLink)
800–1450650三个构造函数、初始化漏斗、析构、Destroy/Close
1450–2300850新窗口 + WebContentsDelegate 的二十余个回调
2300–3100800WebContentsObserver 的三十余个回调
3100–43301230导航控制、属性读取、DevTools 开关、静音、打印与 PDF
4330–5145815编辑命令、查找、焦点、输入事件、拖拽、对话框、堆快照
5145–5350205IPC、脚本注入、CSS 注入
5350–5750400ExclusiveAccessContext、DevTools 文件系统、HTML 全屏
5750–6184434FillObjectTemplate、构造函数工厂、查找、绑定注册

两个值得注意的地方。

打印是唯一一块被 #if 整段包起来的孤岛(:4002-4330)。它 330 行,包含 Print、PrintToPDF、GetPrintersAsync 三个公开方法,以及一整套"取默认打印机 DPI、拼 media size、找 RenderFrameHost、调 PrintViewManagerElectron::PrintNow"的私有流程。关掉 enable_printing 编译后,这块被 8 行桩替代(:4314-4332),三个方法变成返回空 promise。这是 Electron 里少见的"整个功能可以编译掉"的设计,其余功能基本只做运行时降级。

FillObjectTemplate 只有 190 行,却注册了 146 个原型成员(145 个 SetMethod/SetProperty 加 1 个手写的 isDestroyed)。这意味着原型表是声明式的、可扫读的,而行为分散在其余 6000 行里。10.2.5 说过 BaseWindow 有 159 个原型成员,规模同一量级,但 BaseWindow 的几乎全是一行转发,WebContents 的有一半带着状态。

11.0.2 本章的四条主线

6184 行按"一个对象的一生"重排,得到四条主线,也是本章结构:

一、身份(11.1、11.2)。十三个基类和六种 Type 决定了"这个对象能做什么"。这一层是纯声明,但每个基类都对应一组回调,而回调之间没有隔离。

二、出生(11.3、11.4)。四条构造路径、三次 Observe、十几个 WebContentsUserData 挂载、一次 _init。顺序错一位就是崩溃或静默失效。

三、死亡(11.5)。Destroy / Close / 析构 / WebContentsDestroyed 四个函数,加两个 bool 标志位,构成 Electron 里最复杂的销毁协议。

四、活着的部分(11.6–11.11)。导航、崩溃、输入、脚本与 IPC、缩放与 DevTools、注册表。

这四块不是并列的:死亡协议的复杂度直接来自前两块——十三个基类意味着十三个"死之前要做点什么",六个 Type 意味着六套所有权。


11.1 十三个基类

WebContents 的声明是这样的:

electron_api_web_contents.h:129-139

class WebContents final : public ExclusiveAccessContext,
						public gin_helper::DeprecatedWrappable<WebContents>,
						public gin_helper::EventEmitterMixin<WebContents>,
						public gin_helper::Constructible<WebContents>,
						public gin_helper::Pinnable<WebContents>,
						public gin_helper::CleanedUpAtExit,
						public content::WebContentsObserver,
						public content::WebContentsDelegate,
						private content::RenderWidgetHost::InputEventObserver,
						public content::JavaScriptDialogManager,
						public InspectableWebContentsDelegate,
						public InspectableWebContentsViewDelegate,
						public BackgroundThrottlingSource {

十三个基类,按来源可以分三组。

11.1.1 第一组:Electron 自己的五个 gin_helper 基类

这五个决定"这个 C++ 对象在 JS 世界长什么样"。

DeprecatedWrappable<WebContents> 提供 GetWrapper(isolate)——把 C++ 对象映射到 V8 对象。名字里的 "Deprecated" 指的不是"这个基类要废弃",而是"它用的是旧的 gin::DeprecatedWrapperInfo 注册路径":

wrappable.h:80-83

// Copied from https://chromium-review.googlesource.com/c/chromium/src/+/6799157
// Will be removed as part of https://github.com/electron/electron/issues/47922
template <typename T>
class DeprecatedWrappable : public DeprecatedWrappableBase {

上游 Chromium 改了 gin::Wrappable 的 wrapper info 机制,Electron 把这个旧实现抄了一份进来,起名 DeprecatedWrappable,等所有类迁移完再删。electron_api_web_contents.cc:6125-6127 里的 kWrapperInfo 就是这份兼容层:

// :6125-6127
gin::DeprecatedWrapperInfo WebContents::kWrapperInfo = {
	gin::kEmbedderNativeGin};

EventEmitterMixin<WebContents> 提供 Emit(name, args...)。这是整个类的神经系统——50 个事件名、55 处 Emit( 调用都从这里出去。它的实现值得逐行看,因为它解释了本章后面所有的"销毁后为什么没崩":

event_emitter_mixin.h:32-45

	template <typename... Args>
	bool Emit(const std::string_view name, Args&&... args) {
	v8::Isolate* isolate = electron::JavascriptEnvironment::GetIsolate();
	v8::HandleScope handle_scope(isolate);
	v8::Local<v8::Object> wrapper;
	if (!static_cast<T*>(this)->GetWrapper(isolate).ToLocal(&wrapper))
	return false;
	internal::Event* event = internal::Event::New(isolate);
	v8::Local<v8::Object> event_object =
		event->GetWrapper(isolate).ToLocalChecked();
	gin_helper::EmitEvent(isolate, wrapper, name, event_object,
						std::forward<Args>(args)...);
	return event->GetDefaultPrevented();
	}

三件事:

  1. 每次 Emit 都重新取 wrapper。 wrapper 是 V8 对象,会被 GC。取不到(已被回收)就直接 return false——事件静默丢弃,不崩。这是 Electron 里"半死对象"能继续被调用的根本原因:所有 Emit 在 wrapper 消失后变成空操作。
  2. 每次都新建一个 internal::Event 对象。 它在 JS 侧就是一个普通对象,带 preventDefault()。Emit 的返回值就是"有没有人调过 preventDefault"。
  3. 返回值是 bool,含义是"被阻止了"。所以 if (!Emit(...)) 表示"没人阻止",if (Emit(...)) return; 表示"有人阻止了,别继续"。

internal::Event 不是 Node 的 EventEmitter 事件对象。它和 EventEmitterMixin 另一半的组合方式,是把原型链挂到 internal::GetEventEmitterTemplate(isolate) 上:

event_emitter_mixin.h:81-83

	constructor->SetClassName(gin::StringToV8(isolate, class_name));
	constructor->Inherit(internal::GetEventEmitterTemplate(isolate));

所以 webContents 的 JS 原型链上有两层:一层是 WebContents.prototype(146 个方法),一层是 EventEmitter.prototype(on/off/emit/once)。 用户写的 wc.on('did-finish-load') 用的是后者,C++ 的 Emit("did-finish-load") 走到的是前者挂在实例上的 emit。这两条路在 gin_helper::EmitEvent 里会合。

Constructible<WebContents> 提供"用 new 构造"的能力。第 7 章讲过,gin_helper::CreateConstructor 的第三参是父模板,BrowserWindow 就这么把 BaseWindow 设成父类。Constructible 在这里的作用是让 webContents 构造函数可以被调:

web-contents.ts:442-444

export function create(options = {}): Electron.WebContents {
	return new (WebContents as any)(options);
}

因为构造函数是"可以 new 的",WebContents::New 这个静态工厂才有意义(:5954),它内部就是 new WebContents(...) 加一次 InitializeJS。

Pinnable<WebContents> 提供 Pin(isolate) / Unpin()。它整个实现只有两个方法:

pinnable.h:17-30

	// Prevent the object from being garbage collected until Unpin() is called.
	void Pin(v8::Isolate* isolate) {
	v8::HandleScope scope(isolate);
	v8::Local<v8::Value> wrapper;
	if (static_cast<T*>(this)->GetWrapper(isolate).ToLocal(&wrapper)) {
	pinned_.Reset(isolate, wrapper);
	}
	}
	// Allow the object to be garbage collected.
	void Unpin() { pinned_.Reset(); }

语义是"让这个 wrapper 不被 GC":把一个强全局引用存进 pinned_,析构前 Reset() 掉。WebContents 只在两处用它——kRemote 类型(:990)和 kBackgroundPage 类型(:1297)。这两个类型的共同点是"不拥有底层对象",底层活多久它们就得活多久,所以必须绕过 V8 的回收节奏。

CleanedUpAtExit 提供"进程退出时统一清理"。它的注释说明了为什么需要它:

cleaned_up_at_exit.h:13-18

// Objects of this type will be destroyed immediately prior to disposing the V8
// Isolate. This should only be used for gin_helper::Wrappable objects, whose
// lifetime is otherwise managed by V8.
//
// NB. This is only needed because v8::Global objects that have SetWeak
// finalization callbacks do not have their finalization callbacks invoked at
// Isolate teardown.

WebContents 的 WillBeDestroyed 只有一行:

electron_api_web_contents.cc:5944-5945

// :5944-5946
void WebContents::WillBeDestroyed() {
	ClearWeak();
}

ClearWeak() 把弱回调摘掉。如果不摘,Isolate 销毁时那个已经失效的 v8::Global 还会尝试回调,进到已经析构的对象里。 这是"退出清理"的全部内容,也是 CleanedUpAtExit 唯一要解决的问题。

11.1.2 第二组:Chromium 的两个内容层基类

这两个是重头。

content::WebContentsObserver 是"观察者",给的是通知:导航开始、导航结束、frame 创建、frame 销毁、标题变化、favicon 更新、主题色变化、渲染进程死亡。这些回调没有返回值(除了 DidFinishLoad 一类),本质是"事情已经发生了,告诉你一声"。

content::WebContentsDelegate 是"委托",给的是决策权:要不要允许新窗口、要不要允许全屏、键盘事件要不要自己处理、beforeunload 要不要放行、文件选择框弹不弹。这些回调有返回值,返回值就是决策。

同一个对象同时是观察者和委托,看起来矛盾(一个是接收,一个是决定),实际上是 Chromium 的设计:content::WebContents 持有一个 delegate_ 指针和一个 observers_ 列表,delegate_ 只能有一个,observers_ 可以有多个。Electron 把唯一的那一个空位占了,于是所有决策都进了 api::WebContents。

这带来一个具体的后果:api::WebContents 是 content::WebContents 的"唯一委托",所以任何决策都必须经过它,不能旁路。 这就是为什么 shell/browser/ 下几十个 helper 类(权限、文件系统、打印、自动填充)都只能注册成 WebContentsUserData,而不能自己当委托——空位只有一个。

private content::RenderWidgetHost::InputEventObserver 是唯一一个私有继承。私有继承在这里有确切含义:"我用你的接口,但我不把接口传出去"。

electron_api_web_contents.h:639-642

	// content::RenderWidgetHost::InputEventObserver:
	void OnInputEvent(const content::RenderWidgetHost& rfh,
					const blink::WebInputEvent& event,
					input::InputEventSource source) override;

如果公开继承,WebContents* 就能隐式转换成 InputEventObserver*,别人可以拿它去注册到别的 RenderWidgetHost。私有继承让这个转换只在类内部可用。

注册点在一个名字和内容无关的函数里:

electron_api_web_contents.cc:1196-1198

// :1190-1192
	// Nothing to do with ZoomController, but this function gets called in all
	// init cases!
	content::RenderViewHost* host = web_contents->GetRenderViewHost();
	if (host)
	host->GetWidget()->AddInputEventObserver(this);

注释直接承认了这件事:InitZoomController 是个"所有初始化路径都会走"的函数,于是被拿来当注册点。这是一个技术债,而且是有注释的技术债——比没有注释的技术债好,但仍然说明"初始化漏斗"缺少一个明确的 hook。

11.1.3 第三组:四个"功能接口"

剩下四个基类各管一件事:content::JavaScriptDialogManager 让 alert/confirm/prompt 能被接管;InspectableWebContentsDelegate 与 InspectableWebContentsViewDelegate 是 DevTools 的两个回调面(共 15 个方法);ExclusiveAccessContext 是 Chromium 全屏视频的独占访问接口,Electron 实现了 9 个方法但其中 3 个是空实现:

electron_api_web_contents.h:838-843

	void ExitFullscreen() override {}
	void UpdateExclusiveAccessBubble(
	const ExclusiveAccessBubbleParams& params,
	ExclusiveAccessBubbleHideCallback bubble_first_hide_callback) override {}
	void OnExclusiveAccessUserInput() override {}

空实现是"接口存在、功能不做"的明确记录:Chromium 全屏视频会显示"按 Esc 退出全屏"的浮层,Electron 不做,三个浮层相关方法就空着。

BackgroundThrottlingSource 是 Electron 自己的接口,只有一个方法(.h:210-211),作为 NativeWindow 判断是否该节流的输入源之一(第 9 章 9.9)。一个只有一行实现的接口,带来了一对生命周期依赖:SetOwnerWindow 里注册、析构里摘除(:1371-1373)。

11.1.4 多重继承的真实成本

十三个基类,每个都带虚函数表。这会带来两个 C++ 层面的具体问题,值得说清楚,因为它们解释了代码里一些看起来多余的写法。

第一,this 指针偏移。 一个有多个非虚基类的对象,不同基类的子对象在内存里处于不同偏移。把 WebContents* 转成 content::WebContentsDelegate* 时,编译器要做指针调整。这意味着任何跨基类的回调,this 的值都可能不同。

Electron 的应对是所有回调都用成员函数(而不是 lambda 捕获 this),且所有异步回调都过 weak_factory_:

electron_api_web_contents.cc:1426-1428

// :1426-1428
	content::GetUIThreadTaskRunner({})->PostTask(
		FROM_HERE,
		base::BindOnce(&WebContents::DeleteThisIfAlive, GetWeakPtr()));

GetWeakPtr() 返回的 base::WeakPtr<WebContents> 绑定的是主对象的偏移,回调时能正确还原。如果哪里直接 base::Unretained(this),那就有风险——而确实有:

electron_api_web_contents.cc:1101-1105

// :1113-1116
	auto* view = new OffScreenWebContentsView(
		false, offscreen_use_shared_texture_,
		offscreen_shared_texture_pixel_format_,
		offscreen_device_scale_factor_,
		base::BindRepeating(&WebContents::OnPaint, base::Unretained(this)));

OnPaint 用 base::Unretained(this) 绑进 OffScreenWebContentsView。这要求 OffScreenWebContentsView 的生命周期严格短于 WebContents——它确实是(由 content::WebContents 持有,而 content::WebContents 由 api::WebContents 持有)。这类约束没有类型系统保护,只能靠注释和代码审查。

第二,析构顺序。 十三基类的析构按声明逆序执行。~WebContents 函数体跑完后,先析构 BackgroundThrottlingSource,最后析构 ExclusiveAccessContext。函数体里能安全用的只有还没被析构的部分——但函数体里往往要用 web_contents(),而它来自 content::WebContentsObserver(第 7 个基类,倒数第 7 个析构)。这就解释了为什么析构函数前半段全是 if (web_contents()) 检查:

electron_api_web_contents.cc:1364-1368

// :1355-1361
	if (web_contents()) {
	auto* permission_manager = static_cast<ElectronPermissionManager*>(
		web_contents()->GetBrowserContext()->GetPermissionControllerDelegate());
	if (permission_manager)
	permission_manager->CancelPendingRequests(web_contents());
	}

web_contents() 返回的指针不会因为基类析构而变空——它是 WebContentsObserver 里的一个裸指针,析构 Observer 基类只是不通知了,指针值还在。所以 if (web_contents()) 检查的不是"基类是否已析构",而是"当初构造时有没有传进来"。 对于 kRemote 之外的三种构造路径,这个指针永远非空;检查是为了覆盖 !inspectable_web_contents_ 那条早退路径。

这一点很容易被误读。有人看到 if (web_contents()) 会以为这是防御性编程,实际上它是一条特定路径的必要条件,而那条路径在 11.5.3 会展开。

11.1.5 为什么不能拆

一个自然的想法是:6184 行太长,应该拆成 NavigationController、InputController、DevToolsController 几个类,WebContents 只做转发。

Electron 没这么做,原因不在"懒",而在**Emit 的一体性**。

假设拆出 NavigationController,它要发 did-navigate 事件。但它没有 V8 wrapper,Emit 的第一个参数 this 就不成立。可行的替代是把 api::WebContents* 传进去让它转发——那就是转发样板,正是多重继承省掉的东西。

更根本的是事件顺序。DidFinishNavigation 里三件事必须按固定顺序做:

electron_api_web_contents.cc:2901-2906

// :2887-2903(节选)
	Emit("did-frame-navigate", url, http_response_code, http_status_text,
		is_main_frame, frame_process_id, frame_routing_id);
	if (is_main_frame) {
		// Ensure zoom is updated before JS handlers see the event.
		if (auto* zc = GetZoomController())
		zc->ProcessNavigationZoom(navigation_handle);
		Emit("did-navigate", url, http_response_code, http_status_text);
	}

注释写得很直白:缩放必须在 JS 处理器看到事件之前更新。这是一个跨子系统的顺序依赖——导航要给缩放让路。如果导航和缩放分属两个类,"谁先谁后"就得靠一个显式的编排层来保证,而编排层本身又是一层转发。

所以 6184 行不是没重构,是重构的收益抵不过跨子系统顺序约束的成本。 这个判断对不对可以争论,但它是这个文件长成这样的直接原因,而不是"没人管"。


11.2 六种 Type:一个类的六个身份

如果十三个基类回答"能做什么",Type 回答"是谁"。

electron_api_web_contents.h:143-153

	enum class Type {
	kBackgroundPage,  // An extension background page.
	kBrowserWindow,   // Used by BrowserWindow.
	kBrowserView,     // Used by the JS implementation of BrowserView for
					// backwards compatibility. Otherwise identical to
					// kBrowserWindow.
	kRemote,          // Thin wrap around an existing WebContents.
	kWebView,         // Used by <webview>.
	kOffScreen,       // Used for offscreen rendering
	};

六个值,注释已经把最关键的信息写完了:kBrowserView "otherwise identical to kBrowserWindow",kRemote 是"thin wrap"。这两句注释是整段枚举里信息量最大的部分。

11.2.1 字符串映射与 getType()

Type 对 JS 暴露成字符串,映射在 Converter 里:

electron_api_web_contents.cc:349-356

// :344-375(节选)
	switch (val) {
	case Type::kBackgroundPage:
		type = "backgroundPage";
		break;
	case Type::kBrowserWindow:
		type = "window";
		break;
	case Type::kBrowserView:
		type = "browserView";
		break;
	case Type::kRemote:
		type = "remote";
		break;
	case Type::kWebView:
		type = "webview";
		break;
	case Type::kOffScreen:
		type = "offscreen";
		break;

注意 kBrowserWindow 映射成 "window" 而不是 "browserWindow"。这是一个无法修改的历史命名:getType() 从 2016 年就返回 'window',改了就破坏兼容。同理 kOffScreen 返回 "offscreen"(全小写),和另外五个的驼峰风格不一致。

这段 switch 没有 default 分支的返回值——default: break; 之后 type 仍是空 string_view。如果将来加了新的 Type 而忘了改这里,JS 会拿到空字符串而不是报错。枚举与字符串映射之间没有编译期约束,这是 11.2.6 那张矩阵要手工维护的根本原因。

11.2.2 四条构造路径

Type 不是构造参数——它在构造之前就被决定了,而且四条路径决定方式完全不同。

路径一:New(isolate, options),给 webContents.create() 用。type_ 从 options 里读:

// :1043-1044
	// Get type
	options.Get("type", &type_);

默认值是头文件里的成员初始化:

// .h:910-911
	// The type of current WebContents.
	Type type_ = Type::kBrowserWindow;

默认是 kBrowserWindow。 所以 webContents.create({}) 造出来的是一个 'window' 类型的 WebContents——虽然它不属于任何窗口。这是"类型描述的是创建意图,不是当前归属"的第一个证据。

路径二:CreateAndTake(isolate, unique_ptr, type),给 BrowserWindow 和 WebContentsView 用。type 是显式参数:

electron_api_web_contents.cc:1005-1010

// :1005-1010
WebContents::WebContents(v8::Isolate* isolate,
						std::unique_ptr<content::WebContents> web_contents,
						Type type)
	: content::WebContentsObserver(web_contents.get()),
	type_(type),
	id_(GetAllWebContents().Add(this))

构造函数第一行就 DCHECK 拒绝 kRemote:

electron_api_web_contents.cc:1016-1017

// :1013-1014
	DCHECK(type != Type::kRemote)
	<< "Can't take ownership of a remote WebContents";

kRemote 的定义是"不拥有",所以它不能走"接管所有权"的路径。 这条 DCHECK 把两个概念绑在了一起:所有权和类型。11.5 会看到这个绑定在 Destroy 里又一次出现。

路径三:裸 content::WebContents*,给"别人创建的 WebContents"用。三条 id_ 初始化里最简单的一条:

electron_api_web_contents.cc:953-957

// :953-957
WebContents::WebContents(v8::Isolate* isolate,
						content::WebContents* web_contents)
	: content::WebContentsObserver(web_contents),
	type_(Type::kRemote),
	id_(GetAllWebContents().Add(this))

这条路径硬编码 kRemote,没有参数。它的使用者是 FromOrCreate(:6017)和扩展系统的 InitWithExtensionView(其间会改 type_)。

路径四:CreateFromWebPreferences,给 BrowserWindow 的 webPreferences.webContents 选项用。这条路最特殊——它可能根本不构造新对象:

// :6034-6039
	gin_helper::Handle<WebContents> web_contents;
	if (web_preferences.GetHidden("webContents", &web_contents) &&
	!web_contents.IsEmpty()) {
	// Set webPreferences from options if using an existing webContents.

如果传了 webContents,就把新的 preferences 应用到这个已存在的对象上(:6040-6071),包括 SetFromDictionary、SetIgnoreMenuShortcuts、SetBackgroundColor、zoom factor、zoom mode。五件事,全部是"改现有对象"而不是"造新对象"。

这条路径的存在是为了 .d.ts 里一个冷门用法:

const wc = new WebContents()
const win = new BrowserWindow({ webPreferences: { webContents: wc } })

它让一个 WebContents 能"搬进"新窗口。代价是构造函数的语义变成"要么造、要么改",而返回值是同一个类型。

11.2.3 kRemote:不拥有、Pin 住、从 UserData 找回来

kRemote 是六种里唯一"不拥有底层对象"的。这决定了三件事。

第一,它必须被 Pin。 注释解释了为什么:

// :975-985(节选)
	// Nothing owns a remote api::WebContents on the JS side, so its wrapper is
	// only kept alive by whoever happens to hold a reference to it. Some callers
	// create it and only pick it back up later (e.g. the DevTools WebContents is
	// created in InspectableWebContents::ShowDevTools and next looked up in
	// DevToolsOpened once the frontend has loaded); if a GC runs in between the
	// wrapper is collected while the C++ object is still reachable via
	// From(), and FromOrCreate() then hands back an empty handle.
	if (type_ == Type::kRemote)
	Pin(isolate);

这段话讲的是一个真实的竞态:DevTools 的 WebContents 被创建后,前端加载完才会去查它。中间如果发生 GC,wrapper 被回收,From() 拿到的是一个 C++ 对象但 GetWrapper() 返回空。Pin 把 wrapper 钉在 v8::Global 里,绕过 GC。

第二,它的析构不销毁底层对象。 因为 kRemote 走的构造路径没有接管 unique_ptr,inspectable_web_contents_ 是空的:

// :1376-1379
	if (!inspectable_web_contents_) {
	WebContentsDestroyed();
	return;
	}

这是析构函数的第二个早退点(第一个是 11.5.3 会讲的 !inspectable_web_contents_)。对 kRemote 来说,inspectable_web_contents_ 从来没被创建过——裸指针构造函数里没有 InitWithWebContents。所以析构时直接跳到 WebContentsDestroyed(),清理注册表、清空 wrapper 里的指针、摘掉 guest_delegate_、解除 Observe、发 destroyed。

第三,它能从 content::WebContents 反查回来。 靠的是 UserData 里挂的一个弱指针:

// :804-810
struct UserDataLink : public base::SupportsUserData::Data {
	explicit UserDataLink(base::WeakPtr<WebContents> contents)
	: web_contents(contents) {}
	base::WeakPtr<WebContents> web_contents;
};
const void* kElectronApiWebContentsKey = &kElectronApiWebContentsKey;
// :6009-6015
WebContents* WebContents::From(content::WebContents* web_contents) {
	if (!web_contents)
	return nullptr;
	auto* data = static_cast<UserDataLink*>(
	web_contents->GetUserData(kElectronApiWebContentsKey));
	return data ? data->web_contents.get() : nullptr;
}

kElectronApiWebContentsKey = &kElectronApiWebContentsKey 是一个经典技巧:用一个自己的地址当 key。它保证在所有 void* key 里唯一,且不需要定义字符串常量(避免 ODR 问题)。

这个 key 在四条构造路径里被设置了四次(:1000、:1280、以及 extension 路径)。四次手写、没有统一的 SetUserData 封装——因为 UserDataLink 必须在 GetWeakPtr() 之后才能构造,而 GetWeakPtr() 依赖 weak_factory_ 成员初始化完成,weak_factory_ 又声明在最后。这个约束让"统一封装"变得别扭,于是就成了手工的四处。

11.2.4 kOffScreen:构造时就要换 view

离屏在构造阶段就改变创建参数——它需要一个自定义 view:

// :1128-1141(节选)
	} else if (IsOffScreen()) {
	// webPreferences does not have a transparent option, so if the window needs
	// to be transparent, that will be set at electron_api_browser_window.cc#L57
	// and we then need to pull it back out and check it here.
	std::string background_color_str;
	options.GetHidden(options::kBackgroundColor, &background_color_str);
	SkColor bc = ParseCSSColor(background_color_str).value_or(SK_ColorWHITE);
	bool transparent = bc == SK_ColorTRANSPARENT;
	...
	auto* view = new OffScreenWebContentsView(transparent, ...);

透明度是从 backgroundColor 反推的。 注释解释了原因:webPreferences 没有 transparent 选项,窗口层的 transparent: true 在 electron_api_browser_window.cc 里被改写成 backgroundColor: '#00000000' 塞进 preferences,离屏这层再从颜色里解出来。一条跨文件的隐式协议,两端都没有类型约束(第 10 章 10.3.2 是它的上游)。

另外,IsOffScreen() 读的是成员而不是 type:

// :4694-4696
bool WebContents::IsOffScreen() const {
	return offscreen_;
}

offscreen_ 在 InitWithWebContents 里从 preferences 读(:1333-1334)。所以 offscreen_ 与 type_ == kOffScreen 是两份可能不一致的状态:构造时一起设,但 IsOffScreen() 用后者、is_guest() 用前者。分工是刻意的——type_ 描述"谁创建的我",offscreen_ 描述"我怎么渲染"。

11.2.5 kWebView:构造函数里就要 embedder

// :1088-1097(节选)
	if (is_guest()) {
	scoped_refptr<content::SiteInstance> site_instance =
		content::SiteInstance::CreateForURL(browser_context,
											GURL("chrome-guest://fake-host"));
	content::WebContents::CreateParams params{browser_context, site_instance};
	guest_delegate_ =
		std::make_unique<WebViewGuestDelegate>(embedder_->web_contents(), this);
	params.guest_delegate = guest_delegate_.get();

两件事。chrome-guest://fake-host 是假 URL,唯一作用是让 SiteInstance 有个"看起来像 URL"的东西,从而让进程分配逻辑正常走;真正的 URL 由后面的 loadURL 带来。

embedder_ 可能已经是 nullptr。 options.Get("embedder", &embedder_) 在 :1075,JS 层不传(手写 new WebContents({type:'webview'}))就是空指针解引用,没有 CHECK。这是一条不做防御的路径,因为唯一调用者总传 embedder(guest-view-manager.ts:205)。不防御是有意的:<webview> 的创建路径被 JS 层锁死,多一层检查只会让"内部 bug"变成"静默降级"。

11.2.6 一张身份矩阵

把六种类型在关键能力上逐项对照:

能力windowbrowserViewwebviewoffscreenremotebackgroundPage
拥有底层 content::WebContents✓✓✗(embedder 拥有)✓✗✗(ExtensionHost 拥有)
需要 embedder✗✗✓(硬性)✗(除非 embedder 也离屏)✗✗
Pin 住 wrapper✗✗✗✗✓✓
可否决 beforeunload✓✓✗✓✗✗
走"新窗口"回调✓✓✗(转给 embedder)✗✗✗
支持离屏渲染✗✗✗✓✗✗
参与 guest_delegate_✗✗✓✗✗✗
默认 delete_view_ 语义——————

这张表的每一行都能在代码里找到一处对应的 if。六种类型、八项能力、四十八个格子,没有一个是配置驱动的——全部是手写分支。 这就是 10.9.5 说"<webview> 的身份是 spread 在 6000 行里的 if 分支"的准确含义,也解释了为什么加第七种类型会很难:四十八个格子里有几格要改,得靠人肉推演。

kBrowserWindow 与 kBrowserView 的区别只有一处——后者参与 BeforeUnloadFired 的"可否决"判断(:1811-1813),其余 6184 行里没有任何行为差别。枚举注释里的 "Otherwise identical" 是准确的:这个类型存在的唯一理由是让 getType() 能区分"我被 BrowserView 包着",好让上层 JS 做兼容。

is_guest() 一共 13 个调用点,全部在这张表里能对上:

// :1090  构造:走 guest 的 CreateParams
// :1208  InitWithSessionAndOptions 的第三个参数
// :1267  构造后:从 embedder 的 relay 抄 owner_window
// :1302  InitWithExtensionView 传给 InitWithWebContents
// :1391  析构:not_owned_by_this
// :1423  Destroy:同步删除的三个条件之一
// :2703  DraggableRegionsChanged:guest 不走窗口的 provider
// :2923  DidFinishNavigation:只有 guest 发 'load-commit'
// :4474  Focus:guest 要先把焦点给 embedder
// :4942  SetBackgroundColor:guest 默认透明
// :5029  ResyncViewFocus:guest 不重设焦点
// :5417  ShouldFocusPageAfterCrash:guest 崩了不抢焦点
// :5740  UpdateHtmlApiFullscreen:guest 不退窗口全屏

十三个点,每个都是"guest 的行为要跟谁走"的一个决策。没有一处是集中的——这是本章后面所有失败模式的结构性来源。

11.3 四条构造路径与两次 Observe

WebContents 的构造不是一个函数,是一条链:JS 构造函数 → 三个 C++ 构造函数之一 → InitWithSessionAndOptions → InitWithWebContents → InspectableWebContents 构造 → InitializeJS。六层,每层都有"这里必须完成"的不变量。

11.3.1 主构造函数读的九个选项

new WebContents(options) 走的构造函数在 :1024,开头 40 行是纯读选项:

// :1032-1073(节选)
	options.Get("backgroundThrottling", &background_throttling_);
	options.Get("type", &type_);
	options.Get("transparent", &guest_transparent_);
	v8::Local<v8::Value> use_offscreen;
	if (options.Get(options::kOffscreen, &use_offscreen)) {
	if (use_offscreen->IsBoolean()) {
	bool b = false;
	if (options.Get(options::kOffscreen, &b) && b) {
		type_ = Type::kOffScreen;
	}
	} else if (use_offscreen->IsObject()) {
	type_ = Type::kOffScreen;
	...
	}
	}
	...
	options.Get("embedder", &embedder_);
	options.Get("devTools", &enable_devtools_);
	const bool initially_shown = options.ValueOrDefault(options::kShow, true);

九个选项,四个坑。

坑一:offscreen 有两种形态。 布尔 true 和对象都接受:

new WebContents({ offscreen: true })
new WebContents({ offscreen: { useSharedTexture: true, sharedTexturePixelFormat: 'argb' } })

布尔形态只设 type_ = kOffScreen;对象形态还额外读三个子字段(:1050-1056)。但布尔形态下离屏的具体参数是默认值——offscreen_device_scale_factor_ 保持 1.0(头文件注释:"Use 1.0f for consistent behavior")。

坑二:transparent 是 guest 专用的。 变量名 guest_transparent_ 说明了一切。它对非 guest 无效,只影响 SetBackgroundColor 的默认值(:4942)。

坑三:show 的默认值是 true,但只有非离屏路径用它。 initially_shown 只被用了两次(:1136 传给 params.initially_hidden),而离屏路径完全不用——离屏没有"可见"概念。

坑四:type 在 offscreen 之后被覆盖。 顺序是:先读 type,再判 offscreen。所以:

new WebContents({ type: 'remote', offscreen: true })  // 结果是 kOffScreen

这不算 bug——remote 加 offscreen 没有意义——但它说明选项之间存在隐式优先级,而且没有文档。

11.3.2 InitWithSessionAndOptions 的十二个动作

这个函数 84 行,做的事比名字多得多:

// :1201-1282,按出现顺序
//  1. Observe(owned_web_contents.get())                        :1206
//  2. InitWithWebContents(...)                                 :1207
//  3. inspectable_web_contents_->GetView()->SetDelegate(this)  :1210
//  4. 拼 accept_languages 写进 RendererPreferences             :1214-1228
//  5. Linux/Win 的字体渲染参数                                  :1230-1239
//  6. 光标闪烁间隔                                             :1241-1243
//  7. WebContentsPreferences::GetOrCreateForWebContents        :1249
//  8. NotifyPreferencesChanged()                               :1253
//  9. InitZoomController()                                     :1255
// 10. 扩展观察者 + ScriptExecutor(编译期开关)                 :1257-1261
// 11. AutofillDriverFactory::CreateForWebContents              :1263
// 12. SetUserAgent()                                           :1265
// 13. guest:从 embedder 的 relay 抄 owner_window              :1268-1276
// 14. SetUserData(kElectronApiWebContentsKey, UserDataLink)    :1280

十四步。其中第 4、5、6 步是**"把操作系统环境灌进 Chromium"**,和 Electron 的 API 完全无关:

// :1221-1228
	std::string accept_languages =
	g_browser_process->GetApplicationLocale() + ",";
	for (auto const& language : electron::GetPreferredLanguages()) {
	if (language == g_browser_process->GetApplicationLocale())
	continue;
	accept_languages += language + ",";
	}
	accept_languages.pop_back();
	prefs->accept_languages = accept_languages;

这段代码做的是:把 app.getLocale() 排第一,把 app.getPreferredSystemLanguages() 依次追加,用逗号连接。

逗号分隔的 accept_languages 会影响三件事:HTTP 的 Accept-Language 头、navigator.languages、以及 CJK 回退字体选择。第三条是注释里明确写的(:1219-1221):"accept_languages effects HTTP header, navigator.languages, and CJK fallback font selection"。

这意味着一个中文应用如果 app.getLocale() 返回 en-US,页面里的中文会用日文字体渲染——因为 Chromium 按 accept_languages 顺序找第一个有字形的字体,而 en-US 排在 zh-CN 前面时,日文回退链可能先命中。这是"一个字符串数组决定字形"的典型案例,而且表现是"字能显示但不好看",很难归因。

第 5 步更微妙:

// :1230-1239
#if BUILDFLAG(IS_LINUX) || BUILDFLAG(IS_WIN)
	// Update font settings.
	static const gfx::FontRenderParams params(
	gfx::GetFontRenderParams(gfx::FontRenderParamsQuery(), nullptr));
	prefs->should_antialias_text = params.antialiasing;
	...
#endif

static 意味着只读一次。如果用户在应用运行期间改了系统字体渲染设置(Windows 的 ClearType 开关),所有已经创建的 WebContents 不会更新,新建的也不会——因为 static 已经初始化过了。这是一个刻意的性能折中,代价是"设置改了要重启应用"。

11.3.3 InitWithWebContents 的七个挂载

这个函数只有 35 行,但它是"把 Chromium 对象变成 Electron 对象"的唯一入口:

// :1307-1341,全部动作
	browser_context_ = browser_context;                            // :1314
	web_contents->SetDelegate(this);                               // :1315
	WebContentsPermissionHelper::CreateForWebContents(...)         // :1318
	FileSystemAccessWebContentsHelper::CreateForWebContents(...)   // :1319
	ReconcileCaretBrowsingCount(...)                               // :1321
	web_contents->SetSupportsDraggableRegions(true);               // :1326
	PrintViewManagerElectron::CreateForWebContents(...)            // :1329(编译期)
	printing::CreateCompositeClientIfNeeded(...)                   // :1330(编译期)
	offscreen_ = web_preferences && web_preferences->IsOffscreen(); // :1334
	inspectable_web_contents_ = std::make_unique<InspectableWebContents>(...)  // :1338
	inspectable_web_contents_->SetDelegate(this);                  // :1340

十一个动作里,SetDelegate(this) 出现两次——一次给 content::WebContents,一次给 InspectableWebContents。这是两个不同的委托位:前者决定"网页要开新窗口时问谁",后者决定"DevTools 要存文件时问谁"。

四个 CreateForWebContents 都是 Chromium 的 WebContentsUserData 模式——把 helper 对象挂在 content::WebContents 的 user data 表上,用类型做 key。这个模式的好处是不用改 content::WebContents 就能扩展;坏处是生命周期绑定是隐式的,helper 的析构顺序由 user data 表决定,不由创建顺序决定。

SetSupportsDraggableRegions(true) 上面有一条很具体的注释:

// :1324-1326
	// TODO: This works for main frames, but does not work for child frames.
	// See: https://github.com/electron/electron/issues/49256
	web_contents->SetSupportsDraggableRegions(true);

拖拽区域只在主 frame 生效,iframe 里的 -webkit-app-region: drag 不工作。 这是一个 2026 年仍挂着 TODO 的限制,编号 #49256。它不是 Electron 的 bug——是 Chromium 的 DraggableRegionsChanged 只从主 frame 上报。

11.3.4 两次 Observe 与一次解绑

Observe() 是 content::WebContentsObserver 的注册函数:

// :1206
	Observe(owned_web_contents.get());
// :1300(扩展路径)
	Observe(web_contents);
// :3124(WebContentsDestroyed 末尾)
	Observe(nullptr);

只有三处。第三次是解绑,而且它在 WebContentsDestroyed 的最后一行附近——比 Emit("destroyed") 早一行:

// :3118-3127
	// Tell WebViewGuestDelegate that the WebContents has been destroyed.
	if (guest_delegate_)
	guest_delegate_->WillDestroy();
	Observe(nullptr);
	load_url_promises_.DidStopLoading();
	Emit("destroyed");

顺序值得注意:先解绑,再发 destroyed。 如果反序,destroyed 的监听者里如果有人触发了导航(比如在一个 destroyed 处理器里 loadURL),Chromium 会通过还在的观察关系回调进来,而这个对象的 web_contents() 已经空指针了。

load_url_promises_.DidStopLoading() 在 Emit("destroyed") 之前——它把所有待决的 loadURL() promise 拒绝掉:

load_url_promises.h:53-54

	// Also 'destroyed'.
	void DidStopLoading();

注释里的 "Also 'destroyed'" 说明这个函数被两处调用:DidStopLoading()(:2616)和 WebContentsDestroyed()(:3125)。同一个函数服务两个语义不同的事件,因为它们对 promise 的影响相同:加载结束了(不管因为什么),待决的 promise 该失败了。

11.3.5 InitializeJS:三步与两个顺序

// :5963-6001(节选)
	base::WeakPtr<WebContents> weak_this = GetWeakPtr();
	if (!GetWrapper(isolate).ToLocal(&wrapper))
	return;
	// An own data property, so it stays readable after the WebContents is
	// destroyed.
	wrapper->DefineOwnProperty(isolate->GetCurrentContext(),
							gin::StringToSymbol(isolate, "id"),
							v8::Integer::New(isolate, ID()),
							static_cast<v8::PropertyAttribute>(
								v8::ReadOnly | v8::DontEnum | v8::DontDelete))
	.Check();
	...
	{
	v8::TryCatch try_catch(isolate);
	gin_helper::CallMethod(isolate, this, "_init");
	if (try_catch.HasCaught())
	node::errors::TriggerUncaughtException(isolate, try_catch);
	}
	v8::Local<v8::Object> app;
	if (!weak_this || !App::Get()->GetWrapper(isolate).ToLocal(&app))
	return;
	...
	gin_helper::EmitEvent(isolate, app, "web-contents-created", event, wrapper);

三步:定义 id → 调 _init → 发 web-contents-created。

第一步为什么不用 SetProperty。 注释写得很清楚:id 是自有数据属性,不是原型上的 getter。如果是 getter,读它要调 C++,对象销毁后就崩;做成自有属性,值复制进 V8 堆,对象死了也能读。三个标志位各有用途:ReadOnly 防改(否则 wc.id = 999 破坏注册表)、DontEnum 让 JSON.stringify 看不见它、DontDelete 防 delete。

对比 BaseWindow 的 id:第 9 章讲过它是原型上的 getter(SetProperty<&BaseWindow::ID>("id")),所以 BaseWindow 销毁后读 id 会走 C++,WebContents 不会。两个类的 id 语义不同、实现也不同,是历史演化的结果而不是设计。

第二步 _init 里可能抛异常。 用 v8::TryCatch + TriggerUncaughtException 把异常转成真正的未捕获异常,而不是静默吞掉。抛了异常第三步仍然会跑(trigger 之后没有 return),因为 web-contents-created 必须发。

第三步 App::Get() 可能为空。 app 还没初始化时(扩展的 background page 在早期创建),GetWrapper() 拿不到,函数直接 return,事件不发。一个静默跳过,没有日志。

两个隐式顺序约束:id 必须在 _init 之前(用户覆盖的 _init 可能读 this.id);web-contents-created 必须在 _init 之后——正好和 BrowserWindow 的 browser-window-created 相反(第 10 章 10.3.4)。原因不同:web-contents-created 的监听者需要拿到已完整初始化的 WebContents(有 ipc、有 navigationHistory),而这些都在 _init 里建。

11.3.6 构造期可以死的两个点

_init 是 JS 原型方法,可以被用户覆盖:

const orig = WebContents.prototype._init
WebContents.prototype._init = function () {
	orig.call(this)
	this.destroy()          // 在 _init 里销毁自己
}

InitializeJS 因此记录了弱引用并在 _init 之后检查:

// :5988-5989
	v8::Local<v8::Object> app;
	if (!weak_this || !App::Get()->GetWrapper(isolate).ToLocal(&app))
	return;

if (!weak_this) 就是"我在 _init 里被销毁了"的检测,检测到就跳过 web-contents-created。这是全文件少数几处真正的防御性检查。

第二个点是工厂函数里的空隙:

// :5954-5960
gin_helper::Handle<WebContents> WebContents::New(
	v8::Isolate* isolate, const gin_helper::Dictionary& options) {
	gin_helper::Handle<WebContents> handle =
	gin_helper::CreateHandle(isolate, new WebContents(isolate, options));
	handle->InitializeJS(isolate);
	return handle;
}

new WebContents(...) 跑完到 InitializeJS 之间,JS 侧还没初始化——但没有任何 JS 能碰到这个对象(wrapper 刚建、还没暴露),所以安全。这个安全性依赖"构造函数不把 this 传出去"这条纪律,而构造函数确实没传。


11.4 JS 层:471 行里的三个对象与五个导出

web-contents.ts:206-212 只有 471 行,比第 10 章的 browser-window.ts(233 行)多一倍,但它承担的事完全不同:browser-window.ts 主要是转发,web-contents.ts:206-212 则真的创建对象。

11.4.1 _init 的第一件事:给每个 WebContents 造一个 ipc

web-contents.ts:206-216

WebContents.prototype._init = function () {
	this._windowOpenHandler = null;
	const ipc = new IpcMainImpl();
	Object.defineProperty(this, 'ipc', {
	get() {
	return ipc;
	},
	enumerable: true
	});

IpcMainImpl 是 events.EventEmitter 的子类(ipc-main-impl.ts),带一个 _invokeHandlers Map。整个类只有 30 行。

关键在 const ipc = new IpcMainImpl() 这行的位置:它在 _init 的闭包里,不在 this 上。 属性是一个 getter,闭包捕获 ipc。这样做的效果是:

  • 每次读 wc.ipc 拿到同一个对象(闭包里的那个)
  • 这个对象不在 wc 的自有属性里,所以 Object.keys(wc) 看不到它
  • 用户改不掉(getter 没有 setter,非严格模式下赋值静默失败)

为什么每个 WebContents 要有自己的 ipc?因为 IPC 消息需要"只从这个 WebContents 来的"监听器。ipcMain 是全局的,wc.ipc 是"这个页面的 ipcMain"。

投递顺序在 C++ 里:

electron_api_ipc_dispatch.cc:524-527

// The emitters a non-internal frame IPC is delivered to after the
// WebContents itself, in dispatch order: the sending frame's ipc (looked up
// by frame tree node so a frame that is mid-swap still receives it), the
// WebContents' ipc, then ipcMain.

三站:frame 的 ipc → WebContents 的 ipc → ipcMain。 但注意 CollectFrameTargets 的实现顺序是先 frame 后 wc:

electron_api_ipc_dispatch.cc:547-549

	v8::Local<v8::Object> wc_ipc;
	if (IpcOf(context, sender).ToLocal(&wc_ipc))
	out->push_back(wc_ipc);
	out->push_back(GetRegistry().ipc_main.Get(isolate));

而 sender_wrapper(WebContents 自身)的 ipc-message 事件在更早的地方单独发(:623-632)。所以完整的投递链是四站:

  1. webContents.emit('ipc-message', event, channel, ...args)
  2. event.senderFrame.ipc.emit(channel, ...)(如果 frame 还在)
  3. webContents.ipc.emit(channel, ...)
  4. ipcMain.emit(channel, ...)

第 2 站是后查的,注释解释了原因:

// :636-639
	// Looked up after the WebContents listeners ran, as before, so an ipc
	// emitter one of them creates (e.g. event.senderFrame.ipc) still receives
	// this message.

"先发 WebContents,再查 frame" 是因为 WebContents 的监听者可能在处理过程中创建 frame 的 ipc 对象。如果先查,那个新建的 ipc 就漏了这条消息。

11.4.2 navigationHistory:一个纯 JS 门面

web-contents.ts:219-224

// lib/browser/api/web-contents.ts:219-252(节选)
	Object.defineProperty(this, 'navigationHistory', {
	value: {
	canGoBack: this._canGoBack.bind(this),
	canGoForward: this._canGoForward.bind(this),
	...
	length: this._historyLength.bind(this),
	restore: ({ index, entries }: ...) => { ... }

这个对象在 _init 里一次性建好,所有方法都 bind 好了 this:

const { goBack } = wc.navigationHistory
goBack()   // 能用,因为已经 bind 过
const { goBack: g2 } = wc
g2()       // TypeError:原型方法解构后 this 丢失

C++ 原型名带下划线(_canGoBack、_historyLength),用户可见名不带。三层重命名:C++ 的 CanGoBack → 原型 _canGoBack → 用户 navigationHistory.canGoBack。

length 是函数而不是 getter,所以必须写 navigationHistory.length()。这是 API 的不一致——Array.prototype.length 是属性,这里却是方法,而文档写的是方法形式,用户极易漏括号。

11.4.3 窗口打开:两段与一个"更早的钩子"

window.open() 走两段。

第一段 -will-add-new-contents(web-contents.ts:261):让 setWindowOpenHandler 能取消创建、并改写 webPreferences。改写时有两个窗口选项被单独摘出来塞进 preferences:

// :287-290
			// Allow setting of backgroundColor as a webPreference even though
			// it's technically a BrowserWindowConstructorOptions option because
			// we need to access it in the renderer at init time.

因为渲染进程初始化时要读它们(首帧背景色、是否透明),而那时窗口对象还没建好。 第 10 章 10.3.2 是同一个问题的上游。

第二段 -add-new-contents(:316):WebContents 已创建,调 openGuestWindow。它先清空暂存状态再用(:336-341),因为 openGuestWindow 可能同步触发嵌套的窗口打开。

两段不能合并,因为取消必须发生在创建之前。 但这里有一个命名上的错位值得记下:-will-add-new-contents 这个名字暗示"还没创建",实际它从 WebContentsCreatedWithFullParams 发出(.cc:1474),此时 content::WebContents 已经创建,只是还没开始导航。

// .cc:1474-1480(节选)
void WebContents::WebContentsCreatedWithFullParams(
	content::WebContents* source_contents,
	int opener_render_process_id,
	int opener_render_frame_id,
	const content::mojom::CreateNewWindowParams& params,
	content::WebContents* new_contents) override {

它比 AddNewContents 早一步,而 AddNewContents 拿到的是已经创建好、可以直接导航的 unique_ptr。所以"取消"的真正代价是这个 content::WebContents 已经被构造了——只是还没起渲染进程。如果 Electron 用 AddNewContents,取消就要销毁一个刚创建的 WebContents,多花 30–90ms 起一个进程再杀掉。

11.4.4 JS 对话框是一个 dialog.showMessageBox

这是本章最出人意料的一段。

alert() / confirm() 在 Electron 里不是原生对话框,是用 dialog.showMessageBox 模拟的:

// lib/browser/api/web-contents.ts:372-420(节选)
	this.on('-run-dialog', async (info, callback) => {
	const origin = info.frame.origin === 'file://' ? info.frame.url : info.frame.origin;
	if ((originCounts.get(origin) ?? 0) < 0) return callback(false, '');
	const prefs = this.getLastWebPreferences();
	if (!prefs || prefs.disableDialogs) return callback(false, '');
	// We don't support prompt() for some reason :)
	if (info.dialogType === 'prompt') return callback(false, '');
	...
	const options: MessageBoxOptions = {
	message: info.messageText,
	checkboxLabel: checkbox,
	signal: abortController.signal,
	...(info.dialogType === 'confirm'
		? { buttons: ['OK', 'Cancel'], defaultId: 0, cancelId: 1 }
		: { buttons: ['OK'], defaultId: -1, cancelId: 0 })
	};

五个事实:

一、prompt() 永远返回 null。 注释写的是 "We don't support prompt() for some reason :)"——带着一个笑脸的"不知道为什么"。这是 Electron 里少见的坦率注释,也说明这个限制已经存在很久且没人想修。

二、disableDialogs 和 safeDialogs 是 webPreferences 的选项。 safeDialogs: true 时第二次及以后的对话框会带一个"阻止此页面再创建对话框"的复选框:

// :387-390
	const checkbox =
	originCounts.get(origin)! > 1 && prefs.safeDialogs
		? prefs.safeDialogsMessage || 'Prevent this app from creating additional dialogs'
		: '';

三、按 origin 计数,勾选后设为 -1。 originCounts.set(origin, -1)(:414),而函数开头检查 < 0 就拒绝(:374)。用 -1 当"永久拒绝"的哨兵值,而不是一个独立的 Set。

四、onbeforeunload 不走这条路。 RunBeforeUnloadDialog 是 JavaScriptDialogManager 的另一个方法,它发的是 will-prevent-unload 事件,由用户自己决定。

五、对话框的父子关系靠 getOwnerBrowserWindow()。 离屏时没有父窗口,退化成无父对话框:

// :400-402
	const promise =
	parent && !prefs.offscreen ? dialog.showMessageBox(parent, options) : dialog.showMessageBox(options);

11.4.5 console-message 的观察者

这一段是 JS 层唯一"按需开启"的机制:

web-contents.ts:427-437

	(this as NodeJS.EventEmitter).on('newListener', (eventName: string | symbol, listener: (...args: any[]) => void) => {
	if (eventName === 'console-message') {
	if (listener.length > 1) consoleMessageDeprecated();
	if (!this.isDestroyed()) this._setConsoleMessageObserved(true);
	}
	});
	this.on('removeListener' as any, (eventName: string | symbol) => {
	if (eventName === 'console-message' && !this.isDestroyed() && this.listenerCount('console-message') === 0) {
	this._setConsoleMessageObserved(false);
	}
	});

newListener / removeListener 是 Node EventEmitter 的两个内建事件。这里用它们做引用计数:有监听者就告诉 C++"有人关心控制台消息",没有就关掉。

C++ 侧只是一个 bool:

// .h:925-926
	// Kept by JS while 'console-message' has listeners.
	bool console_message_observed_ = false;

这个 bool 在 OnDidAddMessageToConsole 里被用到。为什么要这么做? 因为每一条 console.log 都要跨进程发一次 IPC,而大多数应用不监听 console-message。关掉能省掉全部开销。

这是一个"用 JS 的监听者表驱动 C++ 行为"的模式,全文件只有这一处。 它的问题在于依赖 newListener 的时序:once() 会先触发 newListener 再注册,removeAllListeners() 会触发一批 removeListener,两者都能正确计数——但如果用户直接改 _events 对象(Node 内部结构),计数就错了。

11.4.6 导出面只有六个,其中一个是重复实现

// lib/browser/api/web-contents.ts:442-471(节选)
export function create(options = {}): Electron.WebContents { ... }
export function fromId(id: number) { return binding.fromId(id); }
export function fromFrame(frame) { return binding.fromFrame(frame); }
export function fromDevToolsTargetId(targetId) { return binding.fromDevToolsTargetId(targetId); }
export function getFocusedWebContents() { ... }
export function getAllWebContents() { return binding.getAllWebContents(); }

C++ 的 Initialize 只注册五个(:6179-6183):构造函数、fromId、fromFrame、fromDevToolsTargetId、getAllWebContents。getFocusedWebContents 是纯 JS 的,但 C++ 侧也有一个同名静态方法(:6116),两段逻辑一模一样:

// C++: :6116-6127
WebContents* WebContents::GetFocusedWebContents() {
	WebContents* focused = nullptr;
	for (WebContents* contents : GetWebContentsList()) {
	if (!contents->IsFocused()) continue;
	if (!focused) focused = contents;
	if (contents->type() == Type::kWebView) return contents;
	}
	return focused;
}
// JS: :458-468
	for (const contents of binding.getAllWebContents()) {
	if (!contents.isFocused()) continue;
	if (focused == null) focused = contents;
	if (contents.getType() === 'webview') return contents;
	}

差别只有"遍历 IDMap"和"遍历绑定数组"。C++ 版的实际使用者只有 NativeWindow 的内部调用。同一逻辑两份实现,改一处忘另一处不会报错——11.11 把这类"重复记账"集中列出。

create() 用 new (WebContents as any)(options):.d.ts 里 WebContents 的构造函数是私有的("not meant to be instantiated directly"),运行时能 new、类型上不能,这个矛盾用 as any 抹平。


11.5 销毁协议:四个函数、两个 bool、一条状态线

WebContents 的销毁是 Electron 里最复杂的一段代码。它复杂不是因为行数(不到 200 行),而是因为有四个入口、两条早退路径、三种所有权、五个中间状态。

先把四个入口摆清楚:

函数位置谁来调做什么
Destroy():1418JS 的 wc.destroy()、CloseContents决定"现在删还是排队删"
Close(opts):1432JS 的 wc.close()走 Chromium 的 Close(),可能触发 beforeunload
~WebContents():1343delete this清理引用、发 will-destroy、可能释放底层
WebContentsDestroyed():3097content::WebContents 死亡时、析构里清理注册表、摘 wrapper 指针、发 destroyed

11.5.1 Destroy 的三分支

// :1418-1430
void WebContents::Destroy() {
	// The content::WebContents should be destroyed asynchronously when possible
	// as user may choose to destroy WebContents during an event of it.
	if (Browser::Get()->is_shutting_down()) {
	DeleteThisIfAlive();
	} else if (is_guest() && is_safe_to_delete_ && !is_emitting_event_) {
	DeleteThisIfAlive();
	} else {
	content::GetUIThreadTaskRunner({})->PostTask(
		FROM_HERE,
		base::BindOnce(&WebContents::DeleteThisIfAlive, GetWeakPtr()));
	}
}

分支一:应用正在退出,同步删。 退出时消息循环很快就不转了,排队的任务永远不执行。"退出路径"和"正常路径"分家的典型写法。

分支二:guest 且不在导航回调里且不在发事件,同步删。 为什么只有 guest 能同步删? 因为 guest 的底层 content::WebContents 不归它所有(属于 embedder frame),删掉 api::WebContents 不会连带删 Chromium 对象,不存在"删到一半被 Chromium 回调"的风险。窗口和离屏没有这个前提。

分支三:其余全部排队删。 用户可能在事件处理器里调 destroy(),那时栈上还有一堆 Chromium 的帧,同步删会把它们的 this 变成野指针。

DeleteThisIfAlive 名字里的"IfAlive"值得展开:

// :1405-1416
void WebContents::DeleteThisIfAlive() {
	// It is possible that the FirstWeakCallback has been called but the
	// SecondWeakCallback has not, in this case the garbage collection of
	// WebContents has already started and we should not |delete this|.
	// Calling |GetWrapper| can detect this corner case.
	...
	if (!GetWrapper(isolate).ToLocal(&wrapper))
	return;
	delete this;
}

这是整个文件里最微妙的一个函数。 V8 的弱回调分两阶段:FirstPass(即将回收,可复活)和 SecondPass(真的回收)。如果 GC 已走 FirstPass,对象处于"弱引用已失效但 wrapper 还没消失"的中间态,此时 delete this 会二次释放。

用 GetWrapper() 能否成功当作"我还没被 GC 盯上"的探针——这个技巧在注释里被明确记录。

11.5.2 Close 与 waitForBeforeUnload

// :1432-1443
void WebContents::Close(std::optional<gin_helper::Dictionary> options) {
	bool dispatch_beforeunload = false;
	if (options)
	options->Get("waitForBeforeUnload", &dispatch_beforeunload);
	if (dispatch_beforeunload &&
	web_contents()->NeedToFireBeforeUnloadOrUnloadEvents()) {
	NotifyUserActivation();
	web_contents()->DispatchBeforeUnload(false /* auto_cancel */);
	} else {
	web_contents()->Close();
	}
}

close({ waitForBeforeUnload: true }) 是 2023 年才加的选项。它存在的理由是 Chromium 的 Close() 在某些情况下不触发 beforeunload:

web_contents()->Close();      // 可能跳过 beforeunload
web_contents()->DispatchBeforeUnload(false);   // 强制走一遍

NotifyUserActivation() 是前置条件——Chromium 只在页面有用户激活时才允许 beforeunload 弹框。没激活就派发,浏览器会静默忽略。

false /* auto_cancel */ 的意思是"不要自动取消"。传 true 的话,如果没有 beforeunload 处理器,导航立即继续;传 false 则等一轮消息循环。Electron 用 false 是为了让 will-prevent-unload 事件有机会发出。

11.5.3 析构函数的八步

// :1343-1403,逐步
// 1. ReconcileCaretBrowsingCount(false)                       :1349
// 2. 清两个 DevTools delegate                                 :1359-1362
// 3. 取消待决的权限请求                                        :1364-1369
// 4. 从 owner_window 的节流源列表里摘掉自己                     :1371-1373
// 5. 摘掉输入事件观察者                                        :1374-1378
// 6. 如果没有 inspectable_web_contents_ 就早退                  :1380-1383
// 7. Emit("will-destroy")                                     :1387
// 8. 如果不拥有底层就 ReleaseWebContents + WebContentsDestroyed :1391-1400

第 1 步必须在最前面,注释写明了原因:

// :1344-1348
	// Release this instance's contribution to the process-wide caret browsing
	// refcount. Runs before any of the early returns below so a WebContents
	// destroyed with caret browsing on cannot leak a count and pin the platform
	// state on forever. Note that WebContentsDestroyed() releases it too and
	// normally gets there first.

caret browsing 有一个进程级引用计数 g_caret_browsing_count(:471):开一个加一,关一个减一,归零时把 Chromium 的平台状态关掉。如果第 6 步早退前没减,计数永远不下来,光标浏览永远开着。

ReconcileCaretBrowsingCount 本身幂等(:3620-3626):caret_browsing_counted_ 记录"我这个对象算没算过",所以调两次也只减一次。幂等是必需的——WebContentsDestroyed() 也会调(:3099),而两个函数的调用顺序不确定。

第 2 步的注释是本章唯一一处"曾经崩溃过"的直接证据:

// :1351-1358(节选)
	// A queued DevTools embedder-message IPC (e.g. "loadCompleted") can be
	// dispatched after this WebContents has begun teardown. ... a late callback
	// would dereference this freed WebContents (a use-after-free seen as a
	// SIGSEGV probing owner_window_). Clear both delegates up front so any such
	// late callback becomes a no-op instead of touching freed memory.

"a SIGSEGV probing owner_window_" ——崩溃点被记下来了。一个已排队的 IPC 在析构开始后才派发,走到 base::Unretained(this)绑的回调里,访问了已释放的owner_window_`。

修法是"提前清空委托"而不是"取消已排队的 IPC"——后者做不到。清空把"野指针访问"降级成"空指针检查"。

第 8 步是所有权分界:

// :1389-1400(节选)
	bool not_owned_by_this = is_guest() && attached_;
#if BUILDFLAG(ENABLE_ELECTRON_EXTENSIONS)
	// And background pages are owned by extensions::ExtensionHost.
	if (type_ == Type::kBackgroundPage)
	not_owned_by_this = true;
#endif
	if (not_owned_by_this) {
	inspectable_web_contents_->ReleaseWebContents();
	WebContentsDestroyed();
	}
	// InspectableWebContents will be automatically destroyed.
  • is_guest() && attached_:content::WebContents 由 embedder frame 释放,这里只 ReleaseWebContents() 放弃所有权,再手动调 WebContentsDestroyed()。
  • kBackgroundPage:由 ExtensionHost 释放,同样只放引用。
  • 其余:inspectable_web_contents_ 的析构会删掉 content::WebContents,后者析构触发 WebContentsDestroyed()——不需要手动调。

最后一行注释是这个函数的收尾。inspectable_web_contents_ 是成员,函数体跑完后自动析构;它的析构删 content::WebContents,后者的析构调 WebContentsObserver::WebContentsDestroyed(),也就是 :3097。所以正常路径下 WebContentsDestroyed() 是在 ~WebContents 函数体结束之后才跑的——此时 this 已处于析构后状态。

这段代码能工作,纯粹因为 WebContentsDestroyed() 只碰"还没被析构的基类成员"和 V8 对象。一个很窄的正确性窗口。

11.5.4 WebContentsDestroyed 的九步

// :3097-3127,逐步
// 1. ReconcileCaretBrowsingCount(false)                :3099
// 2. WebFrameMain::DestroyAllForWebContents()          :3104
// 3. Unpin()                                           :3107
// 4. 从 GetAllWebContents 注册表移除                    :3110-3111
// 5. wrapper 的 internal field[0] 置空                  :3112-3119
// 6. guest_delegate_->WillDestroy()                    :3122-3123
// 7. Observe(nullptr)                                  :3124
// 8. load_url_promises_.DidStopLoading()               :3125
// 9. Emit("destroyed")                                 :3126

第 2 步要手动清 frame,注释写明了原因:

// :3101-3103
	// For a content::WebContents we do not own (guest, background page), frames
	// outlive us but no longer get lifecycle notifications; dispose them now.

正常情况下 frame 随 content::WebContents 一起死,WebFrameMain 收到通知自己清理。但 guest 和 background page 的 content::WebContents 活得比 api::WebContents 长——那些 frame 从此收不到通知,变成永不清理的 JS 对象。

第 5 步是"把 wrapper 和 C++ 对象断开":

// :3112-3119
	v8::Local<v8::Object> wrapper;
	if (!GetWrapper(isolate).ToLocal(&wrapper))
	return;
	wrapper->SetAlignedPointerInInternalField(0, nullptr,
											v8::kEmbedderDataTypeTagDefault);

internal field[0] 是 gin 存 C++ 指针的槽位。置空后,任何还在引用这个 wrapper 的 JS 调 wc.getURL() 都会拿到 nullptr 并由 gin 抛 TypeError,而不是野指针崩溃。

但这里有一个早退:GetWrapper() 失败时直接 return,第 6 到 9 步全部跳过,包括 Emit("destroyed")。正常路径不会发生(~WebContents 触发时 wrapper 还有引用),但 kRemote 被 GC 回收的路径上 destroyed 可能不发。一条合法的事件丢失路径,没有任何日志。

11.5.5 两个 bool 的真实语义

is_safe_to_delete_ 的名字是误导的。它的实际含义是"我不在导航回调里",只在三个导航中间站被设为 false:

// :2748  DidStartNavigation / :2757  DidRedirectNavigation
// :2836  ReadyToCommitNavigation
	base::AutoReset<bool> resetter(&is_safe_to_delete_, false);

读它的地方只有两处:Destroy() 的分支二(:1423)和 LoadURL 的重入检查:

// :3324-3334
	// It's not safe to start a new navigation or otherwise discard the current
	// one while the call that started it is still on the stack. See
	// http://crbug.com/347742.
	if (!is_safe_to_delete_ || ctrl_impl.in_navigate_to_pending_entry()) {
	EmitDidFailLoad(net::ERR_FAILED, net::ErrorToShortString(net::ERR_FAILED),
					url, true);
	return promise;
	}

两个条件:我在导航回调里,或 Chromium 正在导航到一个 pending entry。 任一成立就用 ERR_FAILED 让 promise 失败。

注意它是 EmitDidFailLoad(发事件让 promise 失败)而不是静默返回。用户拿到一个 rejected promise 加一个 did-fail-load,错误码是 ERR_FAILED——和"URL 无效"的 ERR_INVALID_URL 不同,但和"其它任何失败"相同,想区分只能靠堆栈推断。

is_emitting_event_ 的含义是"我正在发一个用户可能借机销毁对象的事件",设为 true 的地方都是 Emit 之前(:2878、:1820、:1827)。头文件注释:

// .h:1006-1009
	// Set to true while dispatching JS events via Emit(). When true, Destroy()
	// defers guest WebContents deletion to prevent use-after-free when a JS
	// handler calls webContents.destroy() mid-emission.

它只影响 guest 的同步删除——非 guest 本来就排队删。

两个 bool 加 is_guest() 和"是否退出中",构成 Destroy() 的完整决策表:

is_guest()is_safe_to_delete_is_emitting_event_退出中行为
anyanyany是同步 delete this
是是否否同步 delete this
是是是否排队
是否any否排队
否anyany否排队

这张表没有写在任何注释里,是从三个 if 反推出来的。

11.5.6 为什么 guest 走另一条销毁路

把 guest 单独拎出来,是因为它在三个地方的所有权都不一样。

构造时,guest 的 content::WebContents 用 CreateParams 带 guest_delegate 创建,params.guest_delegate = guest_delegate_.get()(:1094)。这一行把 guest 的生命周期交给了 embedder frame。

析构时,如果 attached_ 为真,ReleaseWebContents() 只放弃所有权不删对象(:1398)。attached_ 在 AttachToIframe 时设真:

// shell/browser/api/electron_api_web_contents.cc:4677-4692(节选)
void WebContents::AttachToIframe(content::WebContents* embedder_web_contents,
								std::string embedder_frame_token) {
	auto token = base::Token::FromString(embedder_frame_token);
	...
	guest_delegate_->AttachToIframe(embedder_web_contents, frame_token);

销毁时,guest_delegate_->WillDestroy()(:3122)通知 delegate:"我这个 API 层要没了,你把引用清一清"。

三处配合的结果是:api::WebContents(JS 侧对象)可以死得比 content::WebContents(Chromium 对象)早。 这个顺序在所有其他类型里都是反的。

而 attached_ 这个 bool 只在这两个地方用——AttachToIframe 设真、析构里读。没有地方设回 false,因为 detach 之后对象就该死了。

11.5.7 一条状态线

把上面所有内容压成一条时间线,用来诊断"我的 WebContents 到底死到哪一步了":

[t0] 正常
	↓ Destroy() 或 CloseContents() 或底层 content::WebContents 死亡
[t1] 已排队删除(is_emitting_event_ 或非 guest 或 is_safe_to_delete_ 为假)
	↓ 消息循环跑一轮
[t2] DeleteThisIfAlive → delete this
	↓
[t3] ~WebContents 函数体:will-destroy 发出,delegate 清空
	↓
[t4] inspectable_web_contents_ 析构 → content::WebContents 析构
	↓
[t5] WebContentsDestroyed():从注册表移除、wrapper 指针置空、destroyed 发出
	↓
[t6] wrapper 被 GC(可能在 t5 之前,如果被 Pin 则永不)

五个状态:正常、排队中、析构中(will-destroy 已发)、已解绑(wrapper 指针为 null、destroyed 已发)、已被 GC。

可以观察到的信号:will-destroy 在 t3,destroyed 在 t5,isDestroyed() 返回 true 在 t4 之后(它检查的是 inspectable_web_contents_ 是否为 null)。will-destroy 和 destroyed 之间的那段时间,对象"半死"——webContents() 还在,但 inspectable_web_contents_ 正在析构。


11.6 导航:一条 URL 的七站

导航是 WebContents 最忙的部分。一次 loadURL 会依次穿过七个回调。

11.6.1 LoadURL 的十个选项与三个拒绝

// :3271-3342
v8::Local<v8::Promise> WebContents::LoadURL(gin::Arguments* args,
											const std::string& url_string) {
	v8::Local<v8::Promise> promise =
	load_url_promises_.Add(args->isolate(), url_string);
	auto options = gin_helper::Dictionary::CreateEmpty(args->isolate());
	args->GetNext(&options);

第一行就创建 promise,之后所有失败路径都靠 EmitDidFailLoad 让它失败。 这个模式的好处是"只有一条返回路径",坏处是"失败也要走一遍事件系统"。

十个选项:

选项作用落点
httpReferrerReferer 头params.referrer
userAgent覆盖 UA调 SetUserAgent()(持久生效)
extraHeaders额外头params.extra_headers
postDataPOST 体params.post_data + LOAD_TYPE_HTTP_POST
baseURLForDataURLdata URL 的基地址params.base_url_for_data_url + LOAD_TYPE_DATA
reloadIgnoringCache绕过缓存params.reload_type

userAgent 是唯一一个有副作用的选项——它调 SetUserAgent(),改的是 WebContents 的持久 UA,不是这一条请求的 UA。所以:

wc.loadURL('https://a.com', { userAgent: 'X' })
wc.loadURL('https://b.com')   // 还是 X

这是文档里没有的。 loadURL 的 userAgent 选项被描述成"per-request",实际实现是全局。

三个拒绝路径:

// 拒绝一:URL 无效                        :3279-3284
	GURL url(url_string);
	if (!url.is_valid() || url.spec().size() > url::kMaxURLChars) {
	EmitDidFailLoad(net::ERR_INVALID_URL, ...);
	return promise;
	}
// 拒绝二:重入(在导航回调里调用)          :3328-3334
// 拒绝三:renderer teardown 中 → 排队       :3336-3341

第三个不是拒绝,是延后:

// :3336-3341
	if (in_renderer_teardown_) {
	content::GetUIThreadTaskRunner({})->PostTask(
		FROM_HERE, base::BindOnce(&WebContents::LoadURLWithParams, GetWeakPtr(),
								std::move(params)));
	return promise;
	}

in_renderer_teardown_ 是怎么来的? 在 DidStopLoading 里:

// :2609-2619
	const bool in_renderer_teardown =
	std::exchange(navigation_discarded_by_process_gone_, false) ||
	!web_contents()
		->GetPrimaryMainFrame()
		->GetProcess()
		->IsInitializedAndNotDead();
	base::AutoReset<bool> defer(&in_renderer_teardown_, in_renderer_teardown);

两个来源:一是"这次加载停止是因为渲染进程死了"(标志位在 DidFinishNavigation 里设),二是"主 frame 的进程还没初始化或已死"。

这个标志覆盖的时间窗口是 Emit("did-stop-loading") 的整个调用栈。 在这期间发起的所有导航都被排队到消息循环之后——因为 Chromium 正在拆 frame host,此时替换它会让 Chromium 崩。

11.6.2 LoadURLPromises:一个 promise 配一次导航

loadURL() 返回的 promise 由一个独立的小类管(头文件 88 行、实现 162 行)。先看创建:

load_url_promises.cc:34-43

v8::Local<v8::Promise> LoadURLPromises::Add(v8::Isolate* isolate,
											std::string_view url) {
	pending_.push_back(std::make_unique<Pending>(isolate, url));
	v8::Local<v8::Promise> handle = pending_.back()->promise.GetHandle();
	// As `promise.catch(() => {})` did: no unhandled-rejection report, and no
	// pause-on-uncaught in an attached debugger.
	handle->MarkAsHandled();
	handle->MarkAsSilent();
	return handle;
}

MarkAsHandled() / MarkAsSilent() 替代了旧写法 promise.catch(() => {}):即使用户不 await 也不 .catch(),loadURL() 失败也不会报 unhandled rejection。

wc.loadURL('https://nonexistent.invalid')   // 什么都不做
// 控制台没有 "Unhandled promise rejection",只有一行 "Failed to load URL..."

Electron 主动把这个错误标记成"已处理",Node 的 unhandled rejection 检测看不到它。要抓失败只能 try/catch 或监听 did-fail-load。一个为了减少噪音而牺牲错误可见性的取舍,没有文档说明。

再看结算规则,它和直觉完全不同:promise 不与 URL 绑定。

// load_url_promises.cc:75-97(节选)
void LoadURLPromises::DidStartNavigation(std::string_view url,
										bool is_same_document,
										bool is_main_frame) {
	if (!is_main_frame)
	return;
	for (auto it = pending_.begin(); it != pending_.end();) {
	Pending& p = **it;
	if (p.navigation_started && !is_same_document) {
	// Another navigation replaced this one. Same-document navigations
	// (pushState, location.hash) do not count, so a page may route while it
	// loads.
	p.error = LoadError{kErrAborted, "ERR_ABORTED", std::string(url)};
	it = Take(it, false, &settle);
	continue;
	}
	p.navigation_started = true;
	++it;
	}

url 参数只用来填错误信息,从来不和 p.url 比较。规则是:每条 pending 标 navigation_started = true;如果它已经标过、又来了非 same-document 的主 frame 导航,说明新导航取代了它,用 ERR_ABORTED 拒绝。

所以 loadURL 的 promise 语义是"下一次主 frame 导航"。

const p1 = wc.loadURL('https://a.com')
const p2 = wc.loadURL('https://b.com')
// p1 被 ERR_ABORTED 拒绝;p2 在 b.com 加载完成时解析

这符合 Chromium 的实际行为(后一次取消前一次),但和"一个 URL 一个 promise"的直觉不同。Pending::url 字段只用于错误信息,不用于匹配——一个"字段存在但不用"的例子。

is_same_document 被排除在"取代"之外,注释说明了原因:页面内路由(pushState、location.hash)不该让正在加载的 promise 失败,否则"加载中做 SPA 路由"的页面会让 loadURL 永远 reject。

失败分两类:

// load_url_promises.cc:58-71(节选)
	// A failure before any navigation started is final; otherwise wait for
	// did-finish-load / did-stop-loading to report it.
	if (!p.navigation_started)
	it = Take(it, false, &settle);
	else
	++it;
  • 导航还没开始时失败 → 立即 reject,"URL 就没走通"。
  • 导航已开始时失败 → 只记下错误,继续等。已开始的导航可能重试、可能重定向后成功。

这就是 Pending::error 字段的意义:它是一个"待定错误",不是最终结果。

两个错误常量是硬编码的:

load_url_promises.cc:22-23

constexpr int kErrAborted = -3;
constexpr int kErrFailed = -2;

恰好等于 net::ERR_ABORTED 和 net::ERR_FAILED,但代码没 include net/base/net_error_list.h。所以在 did-fail-load 里看到的 errorCode 是 -3,和 net::ERR_ABORTED 可比。用硬编码常量换掉一个头文件依赖,代价是"假设 Chromium 不改这两个值"。

最后,"搬出去再结算"是为了防重入:

load_url_promises.h:75-81

	// Moves |*it| out of pending_ onto |settle|, to be resolved or rejected
	// with its error.
	PendingList::iterator Take(PendingList::iterator it, bool resolve, ...);

结算 promise 会同步跑微任务,微任务里的用户代码可能再调 loadURL() 往 pending_ 里加东西——遍历中修改容器会让迭代器失效。先搬走、再结算。

11.6.3 七站

一次成功导航穿过的回调:

站回调位置发出的事件
1DidStartNavigation:2746did-start-navigation
2DidRedirectNavigation(0..N 次):2755did-redirect-navigation
3ReadyToCommitNavigation:2834-ready-to-commit-navigation(内部)
4DidFinishNavigation:2859did-frame-navigate / did-navigate / load-commit
5DOMContentLoaded:2531dom-ready
6DidFinishLoad:2541did-frame-finish-load / did-finish-load
7DidStopLoading:2602did-stop-loading

第 3 站发的是内部事件(名字带 - 前缀):ready-to-commit 是 Chromium 的概念,Electron 不公开,它唯一的可见影响是 webFrameMain 的一些属性在这时才可用。

第 4 站内部有四个分支:

// :2885-2930(结构)
	if (!navigation_handle->IsErrorPage()) {
	if (is_same_document) {
	load_url_promises_.DidNavigateInPage();
	Emit("did-navigate-in-page", ...);
	} else {
	Emit("did-frame-navigate", ...);
	if (is_main_frame) {
		if (auto* zc = GetZoomController())
		zc->ProcessNavigationZoom(navigation_handle);
		Emit("did-navigate", ...);
	}
	}
	...
	if (is_guest())
	Emit("load-commit", url, is_main_frame);
	} else {
	Emit("did-fail-provisional-load", ...);

did-frame-navigate(:2901)一定先于 did-navigate(:2907):主 frame 导航时用户会收到两个事件,前者带 frame 信息,后者不带。

is_guest() 那行是 13 个调用点里唯一"多发一个事件"的。load-commit 的语义和 did-navigate 几乎重复,但 <webview> 需要它——<webview> 的 JS API 继承了一批 Chromium 的事件名,load-commit 是其中之一。

11.6.4 事件的两种形态

同样是导航事件,did-start-navigation 和 did-navigate 的参数完全不同。

前者带完整事件对象:

// :2658-2669
	gin_helper::Dictionary dict(isolate, event_object);
	dict.Set("url", url);
	dict.Set("isSameDocument", is_same_document);
	dict.Set("isMainFrame", is_main_frame);
	dict.Set("processId", frame_process_id);
	dict.Set("routingId", frame_routing_id);
	dict.SetGetter("frame", frame_host);
	dict.SetGetter("initiator", initiator_frame_host);
	EmitWithoutEvent(event_name, event_object, url, is_same_document,
				is_main_frame, frame_process_id, frame_routing_id);

两个字段是 getter(frame / initiator),因为它们是 WebFrameMain 对象,构造代价高,只在被读时才做。

用 EmitWithoutEvent 而不是 Emit,是因为事件对象已经手工建好(带六个字段),Emit 会再建一个空的。代价是 EmitWithoutEvent 不返回 preventDefault,所以这三个导航事件无法被取消。函数声明了 bool 返回值(.h:453-455),但三个调用点没有一个用它——算出来就扔了。

接口暗示了能力,实现没有。 想拦截导航要走 will-navigate(另一个事件,在 NavigationThrottle 里)。

后者只有位置参数:

// :2907-2908
		Emit("did-navigate", url, http_response_code, http_status_text);

四个参数,没有事件对象。处理器拿不到 frame、processId,要那些信息得自己从 event.sender.mainFrame 取。

同一个类、同一类语义,两种形态并存——did-navigate 是 2013 年的,did-start-navigation 跟着 Chromium 的 NavigationHandle 重构在 2022 年加的。新事件用新形态,老事件不改。

11.6.5 失败的三层

失败事件发在哪一层,取决于失败发生在哪一步。

第一层,provisional load 失败(没提交就失败,比如 DNS 解析不了):

// :2929-2930
	Emit("did-fail-provisional-load", code, description, url, is_main_frame,
		frame_process_id, frame_routing_id);

第二层,load 失败(已提交,资源加载失败):

// :2932-2940
	// Do not emit "did-fail-load" for canceled requests.
	if (code != net::ERR_ABORTED) {
	util::EmitWarning(
		base::StrCat({"Failed to load URL: ", url.possibly_invalid_spec(),
						" with error: ", description}),
		"electron");
	EmitDidFailLoad(code, description, url, is_main_frame, frame_process_id,
					frame_routing_id);
	}

ERR_ABORTED 被特殊处理——它是"用户主动取消",不算失败。否则用户每点一次"停止"都会收到一个错误事件。

同时还发一条 warning 到控制台。这是 Electron 的贴心设计:加载失败默认打印 Failed to load URL: ... with error: ...,不写任何错误处理也能看见。

第三层,媒体文档的 ERR_ABORTED 被彻底吞掉:

// :2563-2571
	// See DocumentLoader::StartLoadingResponse() - when we navigate to a media
	// resource the original request for the media resource, which resulted in a
	// committed navigation, is simply discarded. The media element created
	// inside the MediaDocument then makes *another new* request for the same
	// media resource.
	bool is_media_document =
	media::IsSupportedMediaMimeType(web_contents()->GetContentsMimeType());
	if (error_code == net::ERR_ABORTED && is_media_document)
	return;

直接 loadURL('https://x.com/video.mp4') 时 Chromium 会建一个 MediaDocument,丢弃原始请求,改由 <video> 元素重新请求,那个丢弃报 ERR_ABORTED。

三层路径的共同点是"错误码是唯一分类依据",而 ERR_ABORTED 有两种截然不同的含义(用户取消 / Chromium 内部丢弃)。代码靠"是不是媒体文档"区分——一个依赖 MIME 类型的启发式,对返回 application/octet-stream 的视频服务器会失效。

11.6.6 加载结束的三条路

did-stop-loading 只有一个发出点,但 DidStopLoading() 能被三种情况触发:

  1. 正常加载完:DidFinishLoad → DidStopLoading。
  2. 渲染进程崩了:
// :2605-2610
	// Loading also stops when a renderer dies mid-load, reported from inside
	// RenderFrameHostImpl::RenderProcessGone. A navigation started by the app
	// while handling this event (or the loadURL() rejection it causes) would
	// replace the frame host content is still tearing down, so navigations are
	// posted until the emit returns; see PostNavigationInRendererTeardown().
  1. 用户调 stop():WebContents::Stop()(:3443)直接转发给 web_contents()->Stop()。

三者的区别只体现在 in_renderer_teardown_ 上——只有第二种为真。所以在 did-stop-loading 的监听者看来,"崩溃"和"正常结束"完全一样,除了 render-process-gone 会先发。

11.6.7 缩放必须跑在 did-navigate 之前

再看 11.6.3 那段代码里夹在两个 Emit 之间的三行:

// :2903-2908
	if (is_main_frame) {
		// Ensure zoom is updated before JS handlers see the event.
		if (auto* zc = GetZoomController())
		zc->ProcessNavigationZoom(navigation_handle);
		Emit("did-navigate", url, http_response_code, http_status_text);
	}

位置不能动。 如果放到 did-navigate 之后,用户在处理器里读 getZoomLevel() 会拿到上一个页面的值。

这就是 11.1.5 说的"跨子系统顺序约束"的最小样本:一条注释、一个 if、一次调用,却决定了"导航和缩放能不能拆成两个类"。

11.7 崩溃与无响应:一个定时器、两次延后

"渲染进程死了"在 Electron 里是一等事件,因为渲染进程是沙箱里的、不可信的、会 OOM 的。相关代码 60 行,但有三处"刻意的延后"。

11.7.1 RendererUnresponsive 的电源检查

Chromium 有一个 hang monitor:页面的主线程超过一定时间不处理输入,就报"无响应"。kHungRendererDelay 是这个阈值。Electron 收到回调后做的第一件事是怀疑这个判断:

// :2014-2029
void WebContents::RendererUnresponsive(
	content::WebContents* source,
	content::RenderWidgetHost* render_widget_host,
	base::RepeatingClosure hang_monitor_restarter) {
	// The hang monitor's timer keeps counting through system sleep on Windows,
	// so a timeout that lands while suspended or right after waking says nothing
	// about the renderer; give it a full delay from the wake instead.
	const base::TimeTicks last_resume =
	base::PowerMonitor::GetInstance()->GetLastSystemResumeTime();
	if (last_resume.is_max() ||
	(!last_resume.is_null() &&
	base::TimeTicks::Now() - last_resume < input::kHungRendererDelay)) {
	hang_monitor_restarter.Run();
	return;
	}

Windows 上系统睡眠期间定时器继续走。 合盖两小时再打开,定时器超时值早就过了,Chromium 会立刻报"页面无响应"。这不是页面的错。

处理方式是重新开始计时(hang_monitor_restarter.Run())并直接返回。三种情况:

  • last_resume.is_max():还没有过 resume 记录(比如刚启动),无法判断,重试
  • is_null():resume 时间未设置,不重试(继续往下判)
  • Now() - last_resume < delay:刚唤醒不到一个延迟周期,重试

这段代码只解决 Windows 的问题,但没加 #if。 在 macOS 和 Linux 上 GetLastSystemResumeTime() 一样能用,逻辑一样成立,所以没有平台分支——这是一个"问题来自 Windows,修法是跨平台"的例子。

然后是三段过滤:

// :2040-2052
	auto* web_contents_impl = static_cast<content::WebContentsImpl*>(source);
	bool should_ignore = web_contents_impl->ShouldIgnoreUnresponsiveRenderer();
	dict.Set("shouldIgnore", should_ignore);
	bool visible = source->GetVisibility() == content::Visibility::VISIBLE;
	dict.Set("visible", visible);
	...
	const bool renderer_initialized = rwh_impl->renderer_initialized();
	dict.Set("rendererInitialized", renderer_initialized);
	if (!should_ignore && visible && renderer_initialized)
	EmitWithoutEvent("unresponsive", event_object);

三个条件全部为真才发事件:

  • shouldIgnore:Chromium 认为这个无响应是预期的(比如页面正在被调试器暂停)
  • visible:页面可见。不可见的页面卡住不算问题——后台标签页本来就该让出 CPU
  • rendererInitialized:渲染器初始化完了。初始化中的"无响应"是正常启动耗时

三个字段也一并传进事件对象,所以处理器能看到"为什么"。

注意用的是 EmitWithoutEvent——事件对象已经建好了(带三个字段),不需要 Emit 再建一个空的。这和 EmitNavigationEvent 是同一个模式。

unresponsive 没有对应的"可以阻止"语义吗? 有——EmitWithoutEvent 不返回 preventDefault,但 unresponsive 本来也不需要阻止。它只是通知。

11.7.2 崩溃为什么必须 PostTask

// :2433-2444
void WebContents::PrimaryMainFrameRenderProcessGone(
	base::TerminationStatus status) {
	// This fires while RenderProcessHostImpl is still notifying observers of the
	// process death. Emit asynchronously so app code (e.g. a synchronous
	// reload() in the handler) can't re-launch the renderer from inside that
	// loop, which trips a CHECK in extensions::RendererStartupHelper. The exit
	// code is captured now because a navigation in the interim could reset it.
	content::GetUIThreadTaskRunner({})->PostTask(
	FROM_HERE, base::BindOnce(&WebContents::EmitRenderProcessGone,
								weak_factory_.GetWeakPtr(), status,
								web_contents()->GetCrashedErrorCode()));
}

四个信息点,全部在注释里:

  1. 回调发生时,RenderProcessHostImpl 还在遍历观察者。 同步发事件等于在别人的遍历里插入用户代码。
  2. 用户代码可能同步 reload()。 那会尝试重启渲染进程,而在"还没通知完"的状态下重启会撞上 extensions::RendererStartupHelper 里的 CHECK——直接崩主进程。
  3. 所以延后到消息循环下一轮。
  4. 退出码必须现在取。 因为延后之间可能发生导航,GetCrashedErrorCode() 会被重置。

第 4 点是这类"延后执行"里最容易忘的事:延后意味着状态可能变化,必须在入队时捕获快照。 这里捕获的两个值(status、exit_code)都是值语义,没有悬垂风险。

11.7.3 双发:先 app 后 webContents

// :2446-2492(节选)
	node::CallbackScope callback_scope{isolate, wrapper,
									node::async_context{0, 0}};
	gin_helper::EmitEvent(isolate, app, "render-process-gone", event, wrapper,
						details);
	...
	gin_helper::EmitEvent(isolate, wrapper, "render-process-gone", event,
						details);

同一个事件发两次:先给 app,再给 webContents。注释解释了顺序理由:

// :2470-2475
	// app first: it always was the WebContents' first listener. One callback
	// scope around both emits so that ticks and microtasks run once, after
	// both, as when one emit nested the other. The WebContents' own listeners
	// run off the saved wrapper even if an app listener destroyed it, as the
	// rest of an emit in progress did; nothing of |this| is used from here.

三个设计点:

一、app 先。 因为历史上 app 的监听器是"WebContents 的第一个监听器"——早期实现是把 app 的处理器转发成 WebContents 的事件,转发意味着 app 先跑。

二、一个 CallbackScope 包住两次 emit。 node::CallbackScope 决定 process.nextTick 和 microtask 在什么时候跑。包住两次,微任务就在两次都发完之后跑一次。如果各自包一个,app 的监听器里产生的微任务会在 webContents 的监听器之前执行——顺序变了。

三、用 wrapper 而不是 this。 注释:"The WebContents' own listeners run off the saved wrapper even if an app listener destroyed it"。app 的监听器里可能调 wc.destroy(),此时 this 已经释放。但 wrapper 是 V8 对象(已被 v8::Local 持有),还能用来 EmitEvent。

这是全文件里唯一一处"销毁后继续用 wrapper 发事件"的地方。 安全性来自 EmitEvent 只碰 wrapper、不碰 C++ 对象——但事件的参数里有 details(一个 gin Dictionary),它也没有引用 this。

还有一段只在开了日志时运行:

// :2478-2488
	if (base::Environment::Create()->HasVar("ELECTRON_ENABLE_LOGGING") ||
	base::CommandLine::ForCurrentProcess()->HasSwitch("enable-logging")) {
	...
	gin_helper::CallMethod(
		isolate, console.As<v8::Object>(), "info",
		base::StrCat({"Renderer process ",
						gin::V8ToString(isolate, gin::ConvertToV8(isolate, status)),
						" - see https://www.electronjs.org/docs/tutorial/"
						"application-debugging for potential debugging "
						"information."}));

崩溃时控制台会打一行带文档链接的提示。 这是 --enable-logging 下唯一一条"主动教学"的消息。

11.7.4 崩后导航的两个限制

渲染进程崩了之后,应用最常见的反应是 reload()。这条路径被两个机制保护。

第一,DidFinishNavigation 记录"这次导航被丢弃":

// :2864-2870
	if (navigation_handle->GetNavigationDiscardReason() ==
	content::NavigationDiscardReason::kRenderProcessGone) {
	// The frame whose process died may not be the primary main frame (a
	// speculative frame host, for one), so tell DidStopLoading explicitly.
	navigation_discarded_by_process_gone_ = true;
	}

注释说明了为什么需要这个显式标志:死掉的进程可能不是主 frame 的(可能是 speculative frame host),所以不能靠"主 frame 的进程是否活着"来判断。

第二,DidStopLoading 用它打开 in_renderer_teardown_:

// :2609-2619(已在 11.6.1 引用)
	const bool in_renderer_teardown =
	std::exchange(navigation_discarded_by_process_gone_, false) ||
	!web_contents()->GetPrimaryMainFrame()->GetProcess()
		->IsInitializedAndNotDead();
	base::AutoReset<bool> defer(&in_renderer_teardown_, in_renderer_teardown);

std::exchange(..., false) 是"读一次就清"。所以这个标志只影响紧随其后的那一次 did-stop-loading,不会一直挂着。

两个标志的分工:

标志设置点清除点作用
navigation_discarded_by_process_gone_DidFinishNavigationDidStopLoading(exchange)传递"这次是崩溃导致的"
in_renderer_teardown_DidStopLoading函数返回(AutoReset)覆盖 Emit 的调用栈

这是"一个事件级的标志 + 一个栈级的标志"配合的典型结构。 前者跨函数传递,后者用 RAII 限定作用域。

11.7.5 崩溃后的四个"不"

is_guest() 在崩溃路径上用了一次,值得单独看:

// :5414-5418
bool WebContents::ShouldFocusPageAfterCrash(content::WebContents* source) {
	if (is_guest())
	return false;
	...
}

guest 崩了不抢焦点。 因为 guest 是嵌在页面里的,抢焦点会让用户以为整个窗口激活了,而实际只是内嵌的一个 iframe 崩了。

其余三个"不":

  • 不自动重载:Electron 不重试,交给应用。
  • 不销毁对象:api::WebContents 还活着,reload() 能用。这是 content::WebContents 在进程死后能重建渲染进程的能力。
  • 不移除 WebFrameMain:webFrameMain 对象还在,但它的 render_frame_host 已经失效。

11.8 输入、焦点与拖拽

输入这块的代码不多(约 200 行),但有一条清晰的层次:原生事件 → Chromium 事件 → JS 事件 → 页面,每层都能截。

11.8.1 SendInputEvent 的三条分支与一个坑

// :4496-4556,结构
	if (blink::WebInputEvent::IsMouseEventType(type)) { ... }
	else if (blink::WebInputEvent::IsKeyboardEventType(type)) { ... }
	else if (type == blink::WebInputEvent::Type::kMouseWheel) { ... }
	isolate->ThrowException(... "Invalid event object");

三条分支,加上"都不匹配就抛异常"。没有静默忽略——这是好的,因为 sendInputEvent({ type: 'foo' }) 应该立刻报错。

键盘分支有一个向后兼容的转换:

// :4521-4524
	// For backwards compatibility, convert `kKeyDown` to `kRawKeyDown`.
	if (keyboard_event.GetType() == blink::WebKeyboardEvent::Type::kKeyDown)
		keyboard_event.SetType(blink::WebKeyboardEvent::Type::kRawKeyDown);
	rwh->ForwardKeyboardEvent(keyboard_event);

Chromium 有三种键盘事件类型:kRawKeyDown(物理按下)、kKeyDown(字符产生)、kChar(文本输入)。JS 侧的 sendInputEvent({ type: 'keyDown' }) 被转成 kRawKeyDown。

为什么? 因为 kKeyDown 会让 Chromium 走"字符产生"路径,可能触发重复输入。而 sendInputEvent 的语义是"模拟一次按键",应该是 raw 的。这个转换是 2015 年为修一个 bug 加的,注释只写了"for backwards compatibility",没说兼容什么。

滚轮分支是最长的一段,因为它要发两个事件:

// :4534-4548
		// Chromium expects phase info in wheel events (and applies a
		// DCHECK to verify it). See: https://crbug.com/756524.
		mouse_wheel_event.phase = blink::WebMouseWheelEvent::kPhaseBegan;
		mouse_wheel_event.dispatch_type =
			blink::WebInputEvent::DispatchType::kBlocking;
		rwh->ForwardWheelEvent(mouse_wheel_event);
		// Send a synthetic wheel event with phaseEnded to finish scrolling.
		mouse_wheel_event.has_synthetic_phase = true;
		mouse_wheel_event.delta_x = 0;
		mouse_wheel_event.delta_y = 0;
		mouse_wheel_event.phase = blink::WebMouseWheelEvent::kPhaseEnded;
		mouse_wheel_event.dispatch_type =
			blink::WebInputEvent::DispatchType::kEventNonBlocking;
		rwh->ForwardWheelEvent(mouse_wheel_event);

一个 sendInputEvent({type:'mouseWheel'}) 会变成两个 Chromium 事件。

原因:Chromium 的滚轮事件是带阶段的手势流(phaseBegan → phaseChanged → phaseEnded)。一个孤立的 kPhaseNone 事件会命中 DCHECK(crbug.com/756524)。所以 Electron 造一个 phaseBegan 加一个合成的 phaseEnded,把"单次滚动"包装成一个完整手势。

第二个事件的三个改动都有意义:delta 归零(结束事件不该再滚)、has_synthetic_phase = true(告诉 Chromium"这是我造的,不是真手势")、kEventNonBlocking(结束事件不该阻塞合成器)。

离屏路径不分两段——SendMouseWheelEvent 直接发一个。因为离屏没有合成器手势流,DCHECK 不适用。

11.8.2 三层拦截

一个按键从系统到页面,Electron 有三层机会截住它。

第一层 PreHandleKeyboardEvent,在 Chromium 处理之前:

// :1893-1915(结构)
content::KeyboardEventProcessingResult WebContents::PreHandleKeyboardEvent(
	content::WebContents* source,
	const input::NativeWebKeyboardEvent& event) {
	if (exclusive_access_manager_.HandleUserKeyEvent(event))
	return content::KeyboardEventProcessingResult::HANDLED;
	if (event.GetType() == blink::WebInputEvent::Type::kRawKeyDown ||
	event.GetType() == blink::WebInputEvent::Type::kKeyUp) {
	...

这一段先给全屏独占访问(Esc 退出全屏),再判类型只处理 kRawKeyDown 和 kKeyUp——kChar 被跳过,因为字符输入不该被拦截。

然后发 before-input-event:

// 大约 :1905-1912
	if (Emit("before-input-event", event_object))
	return content::KeyboardEventProcessingResult::HANDLED_PREVENT_DEFAULT;

返回值有三种:NOT_HANDLED(继续)、HANDLED(拦掉,页面收不到)、HANDLED_PREVENT_DEFAULT(拦掉,但页面仍收到一个 preventDefault 过的事件)。第三种的用途是"我想改默认行为但保留事件"。

第二层 HandleKeyboardEvent,在 Chromium 处理之后(页面没消费):

// :1849-1869
bool WebContents::HandleKeyboardEvent(
	content::WebContents* source,
	const input::NativeWebKeyboardEvent& event) {
	if (type_ == Type::kWebView && embedder_) {
	// Send the unhandled keyboard events back to the embedder.
	return embedder_->HandleKeyboardEvent(source, event);
	}
	// Let DevTools consume shortcuts it has registered for (e.g. F8 to pause)
	// even though the inspected page has focus.
	if (inspectable_web_contents_ &&
	inspectable_web_contents_->ForwardKeyboardEvent(event)) {
	return true;
	}
	return PlatformHandleKeyboardEvent(source, event);
}

三个分支,顺序重要:

  1. guest 转给 embedder。 <webview> 里按的键如果在 guest 里没消费,要冒泡到宿主页面——这是 iframe 的语义。
  2. DevTools 消费。 F8(暂停)、F10、Ctrl+Shift+C 这些快捷键在页面有焦点时也要能用。
  3. 窗口消费。 PlatformHandleKeyboardEvent 把事件交给 owner_window()->HandleKeyboardEvent,也就是菜单快捷键。

这就是"为什么我的页面收不到 Ctrl+R"的答案——它被第三层吃掉了。要禁用:

wc.setIgnoreMenuShortcuts(true)

它设的是 ignore_menu_shortcuts_,在 PlatformHandleKeyboardEvent 开头检查:

// :1871-1885(节选)
	if (ShouldIgnoreMenuShortcutsFor(source))
	return false;

ShouldIgnoreMenuShortcutsFor 是个静态函数(:3980),除了读 ignore_menu_shortcuts_ 还检查 webPreferences 里有没有别的来源。

第三层是 before-mouse-event:

// :1887-1891
bool WebContents::PreHandleMouseEvent(content::WebContents* source,
									const blink::WebMouseEvent& event) {
	// |true| means that the event should be prevented.
	return Emit("before-mouse-event", event);
}

注意这里的 Emit 返回值语义和键盘不同:鼠标是 true = 阻止,键盘是三种枚举。同一个类里两个"before-*"事件的返回值含义不一样,一个 bool 一个 enum。

11.8.3 焦点:命令与通知是两件事

// :4464-4494(结构)
void WebContents::Focus() { ... }
// :2521-2524
void WebContents::OnWebContentsFocused(
	content::RenderWidgetHost* render_widget_host) {
	Emit("focus");
}

Focus() 是命令(我要焦点),OnWebContentsFocused 是通知(我拿到了)。两者不是一对一:Focus() 之后可能拿不到(窗口没激活),OnWebContentsFocused 也可能不是 Focus() 引起的(用户点击)。

这是"命令与状态"分得最干净的一对:如果你的代码依赖 Focus() 之后立刻 isFocused() === true,那就是把命令当成了状态。

Focus() 里还有两个分支,一个平台差异、一个类型差异:

// :4464-4478
void WebContents::Focus() {
	// Focusing on WebContents does not automatically focus the window on macOS
	// and Linux, do it manually to match the behavior on Windows.
#if BUILDFLAG(IS_MAC) || BUILDFLAG(IS_LINUX)
	if (owner_window())
	owner_window()->Focus(true);
#endif
	// WebView uses WebContentsViewChildFrame, which doesn't have a Focus impl
	// and triggers a fatal NOTREACHED.
	if (is_guest())
	return;
	web_contents()->Focus();
}

平台差异:macOS 和 Linux 上焦点网页不会自动带上窗口,所以先手动 focus 窗口,对齐 Windows 的行为。

类型差异:guest 直接 return——<webview> 用的是 WebContentsViewChildFrame,它没有 Focus 实现,调下去会触发 NOTREACHED。这是一条"宁可不做事也不能崩"的分支,而不是"转发给 embedder":guest 的聚焦由 embedder 的视图层负责,api::WebContents 不参与。

还有一处隐式聚焦:

// :2841-2845
	// Don't focus content in an inactive window.
	if (!owner_window())
	return;
	if (!owner_window()->IsActive())
	return;

导航提交时默认聚焦内容,但只在窗口已激活时——避免"后台窗口加载完抢焦点"。

11.8.4 拖拽区域:一条只走主 frame 的路

DraggableRegionsChanged(:2698)把 CSS 的 -webkit-app-region: drag 区域从渲染进程传到主进程,存进 draggable_region_(.h:1020),再由 draggable_region()(:2740)交给窗口的 NonClientHitTest(第 9 章 9.8)。

三个限制:

  1. 只在主 frame 生效(11.3.3 的 #49256),iframe 里的 drag 区域不上报。
  2. 只在有原生窗口的类型上生效,离屏和 remote 没有 hit test。
  3. guest 不走窗口的 provider:
// :2703
	if (inspectable_web_contents_ && !is_guest() && !IsOffScreen())

三个条件:有 DevTools 宿主(说明完整初始化过)、非 guest、非离屏。guest 的拖拽由 embedder 处理,因为它画在 embedder 的页面里。


11.9 脚本注入与 IPC

11.9.1 executeJavaScript 的三段

// :5217-5256
v8::Local<v8::Promise> WebContents::ExecuteJavaScriptInRenderer(
	v8::Isolate* isolate,
	int world_id,
	const std::vector<gin_helper::Dictionary>& sources,
	bool has_user_gesture) {
	gin_helper::Promise<v8::Local<v8::Value>> promise(isolate);
	v8::Local<v8::Promise> handle = promise.GetHandle();
	std::vector<mojom::ScriptSourcePtr> script_sources;
	...
	if (auto* renderer = MainFrameRenderer(isolate, promise)) {
	if (has_user_gesture) {
	static_cast<content::RenderFrameHostImpl*>(
		web_contents()->GetPrimaryMainFrame())
		->UpdateUserActivationState(
			blink::mojom::UserActivationUpdateType::kNotifyActivation,
			blink::mojom::UserActivationNotificationType::kWebScriptExec);
	}
	renderer->ExecuteJavaScript(
		world_id, std::move(script_sources), has_user_gesture,
		WebFrameMain::BindPromiseToReply(std::move(promise)));
	}
	return handle;
}

三段,第三段有一个很细的点。

第一段:sources 是数组。 不是单个字符串。这是为了让 executeJavaScript 支持"多段脚本按顺序执行,共享作用域"——JS 层把单个字符串包装成数组的第一项。每项有 code 和 url 两个字段,url 用于 DevTools 里的堆栈显示。

第二段:userGesture 要在浏览器侧先激活。 注释写得非常具体:

// :5237-5245
	// Activate the frame in the browser before the script runs, as
	// RenderFrameHostImpl::ExecuteJavaScriptForTests() does. The renderer
	// reports the activation too, but on the frame's channel-associated
	// interfaces, so a request the script makes on its own Mojo pipe (such
	// as FileSystemFileHandle.createWritable()) can reach the browser first
	// and be refused for lacking user activation.

这是一个真实的竞态:渲染进程会自己上报"我被用户激活了",但那个上报走的是 frame 的通道关联接口(channel-associated interface),而脚本自己发起的请求(比如 FileSystemFileHandle.createWritable())走的是独立 Mojo 管道。两条管道没有顺序保证,所以独立管道上的请求可能先到浏览器,被以"缺少用户激活"拒绝。

修法是"浏览器侧先激活"——在发脚本之前就把激活状态设好。这样无论哪个请求先到,都能看到已激活。

第三段:BindPromiseToReply。 把 promise 绑定到 Mojo 回调,同时处理"frame 消失":

// :5201-5211
base::OnceClosure AckCallback(gin_helper::Promise<void> promise) {
	auto [on_reply, on_drop] = base::SplitOnceCallback(base::BindOnce(
	[](gin_helper::Promise<void> promise, bool replied) {
		if (replied) promise.Resolve();
		else promise.RejectWithErrorMessage(WebFrameMain::kFrameDisposedError);
	},
	std::move(promise)));
	return mojo::WrapCallbackWithDropHandler(
	base::BindOnce(std::move(on_reply), true),
	base::BindOnce(std::move(on_drop), false));
}

WrapCallbackWithDropHandler 是 Mojo 的机制:如果接收端消失了,回调不会执行,而是执行 drop handler。这样 promise 一定会结算(要么 resolve、要么 reject),不会永久 pending。

这是"跨进程 promise 必须处理对端消失"的标准写法,Electron 里只有 AckCallback 这一处显式用了它。

11.9.2 MainFrameRenderer:没有 frame 就拒绝

// :5184-5196
mojom::ElectronFrame* WebContents::MainFrameRenderer(
	v8::Isolate* isolate,
	gin_helper::PromiseBase& promise) {
	content::RenderFrameHost* rfh = web_contents()->GetPrimaryMainFrame();
	WebFrameMain* frame = rfh ? WebFrameMain::From(isolate, rfh) : nullptr;
	mojom::ElectronFrame* api = frame ? frame->GetFrameApi() : nullptr;
	if (!api) {
	promise.RejectWithErrorMessage(
		"Render frame was disposed before WebFrameMain could be accessed");
	}
	return api;
}

三层判空:rfh → frame → api。任何一层为空都拒绝 promise,返回错误信息 "Render frame was disposed before WebFrameMain could be accessed"。

这条错误信息在用户报告里出现频率很高,通常是"窗口正在关的时候调 executeJavaScript"。它不是崩溃,是一个 rejected promise。

GetFrameApi() 返回的是 mojom::ElectronFrame*——一个 Mojo 远程接口。所以 executeJavaScript 是纯 Mojo 调用,不经过 legacy IPC。

11.9.3 send 与 postMessage 的分歧

// :5167-5182
void WebContents::SendImpl(bool internal, gin::Arguments* args) {
	v8::Isolate* isolate = args->isolate();
	std::string channel;
	electron::SerializedValue message;
	if (!ReadIPCSendArguments(args, "webContents", &channel, &message))
	return;
	content::RenderFrameHost* const rfh = web_contents()->GetPrimaryMainFrame();
	WebFrameMain* const frame = rfh ? WebFrameMain::From(isolate, rfh) : nullptr;
	if (!frame) {
	gin_helper::ErrorThrower(isolate).ThrowTypeError(
		"webContents has no main frame to send to");
	return;
	}
	frame->DeliverMessage(isolate, internal, "webContents", channel,
						std::move(message));
}

send 和 postMessage 走同一个 frame 对象,但语义不同:

  • send(DeliverMessage)是 Electron 自己的通道,能被 ipcRenderer.on 收到,有序、可靠、走 Mojo。
  • postMessage(frame->PostMessage)是结构化克隆 + transferable,走 Chromium 的 postMessage 通道。

postMessage 没有 frame 时抛的是不同的错误:

// :5153-5157
	if (!frame) {
	gin_helper::ErrorThrower(isolate).ThrowTypeError(
		"webContents has no main frame to post to");
	return;
	}

"send to" 和 "post to" 两条不同的错误信息,只有介词不同。这是一个刻意的小细节——错误信息要能区分是哪条 API 失败的。

两者都只发给主 frame。 子 frame 要靠 frame.send() 或 webFrameMain 上的方法。这是 webContents.send 文档里"Send an asynchronous message to the renderer process via channel"没写明的一半。

11.9.4 insertCSS 与 insertText

// :5258-5296
v8::Local<v8::Promise> WebContents::InsertCSS(gin::Arguments* args,
											const std::string& css) {

insertCSS 返回一个 key(字符串),removeInsertedCSS(key) 用它删除。key 是 Chromium 生成的,用户不能自选。

insertText 更简单:把文本插到焦点位置。它和 sendInputEvent({type:'char'}) 的区别是:前者走 IME 路径(能触发 input 事件、能被 composition 处理),后者走原始按键路径。

三个都返回 promise,都通过 MainFrameRenderer 拿 frame——所以 frame 消失时都会 reject。

11.9.5 IPC 的四站投递

11.4.1 已经讲过顺序,这里补上"C++ 侧怎么发"。

Emit 的四个目标都是 JS 对象,从 C++ 拿到它们要靠属性读取:

electron_api_ipc_dispatch.cc:111-118

// The `ipc` emitter of |holder| (a WebContents, WebFrameMain or
// ServiceWorkerMain), or an empty handle if it has none.
v8::Local<v8::Object> IpcOf(v8::Local<v8::Context> context,
							v8::Local<v8::Object> holder) {
	v8::Local<v8::Value> ipc = GetProperty(context, holder, "ipc");
	if (ipc->IsObject())
	return ipc.As<v8::Object>();
	return {};
}

C++ 通过读 JS 属性 "ipc" 来找发射器。 这就是为什么 wc.ipc 是一个 getter 而不是普通字段——只要属性存在且返回对象,C++ 就能用。注入方式可以是任意的:Electron 用 IpcMainImpl,用户理论上可以覆盖 wc.ipc 成自己的对象。

GetRegistry().ipc_main 是启动时从 JS 拿到的:

ipc-dispatch.ts:7

process._linkedBinding('electron_browser_ipc_dispatch').setup({ ipcMain, ipcMainInternal });

ipcMain 是从 JS 传给 C++ 的,不是 C++ 自己造的。这是 lib/browser/init.ts 里"先跑 JS、再让 C++ 拿到"的顺序的一部分。

11.9.6 sendSync 无监听者的警告

// :646-655
	if (sync && !handled) {
	v8::Local<v8::String> warning = gin::StringToV8(
		isolate, base::StrCat({"WebContents #", base::NumberToString(sender_id),
							" called ipcRenderer.sendSync() with '", channel,
							"' channel without listeners."}));
	Console(context, "warn", {warning});
	}

这是 Electron 里唯一一条"主动告诉用户你写错了"的 IPC 消息。 因为 sendSync 没有监听者时会同步阻塞等待一个永远不会来的回复——不是死锁(Chromium 会超时),但会卡 500ms 以上,且没有任何错误。

警告里带了 WebContents 的 id,用户可以直接定位是哪个页面。

为什么只有 sendSync 有警告? 因为异步 send 没有监听者只是消息丢了,无副作用;invoke 没有 handler 会 reject(有错误返回);只有 sendSync 是"静默卡住"。

11.10 缩放与 DevTools:两个"寄生"子系统

这两个子系统有同一个特征:它们不改变 WebContents 的接口,而是给底层 content::WebContents 再挂一个对象。

11.10.1 缩放:四种模式、两套 setter

四种模式的差别只在"谁记账":

模式缩放生效记账范围跨导航保持
default是按 origin(全局)是(origin 级)
isolated是按 WebContents是(显式设 persist)
manual否按 WebContents是(显式设 persist)
disabled否不记账—

manual 的关键是"事件照发、页面不动":

web_contents_zoom_controller.h:36-39

	// Overrides the automatic handling of zoom changes. The |onZoomChange|
	// event will still be dispatched, but the page will not actually be zoomed.
	ZOOM_MODE_MANUAL,

zoom-changed 仍然触发,用户可以自己实现缩放(比如改 CSS transform)。这是唯一一个"Electron 只通知、不执行"的缩放模式。

WebContents 上的四个方法都是一行转发(:4774、:4778、:4782、4793),真正有意思的是控制器上两套大小写不同的 setter:

web_contents_zoom_controller.h:97-104

	// Lightweight setter for the zoom mode without going through SetZoomMode(),
	// which manipulates HostZoomMap and requires an initialized RenderFrameHost.
	// Used during initialization before the first navigation commits.
	void set_zoom_mode(ZoomMode mode) { zoom_mode_ = mode; }
	// Lightweight setter for the tracked zoom level without going through
	// HostZoomMap. Used during initialization when RFH is not yet available.
	void set_zoom_level(double level) { zoom_level_ = level; }

SetZoomMode() 重(写 HostZoomMap,要 RenderFrameHost),set_zoom_mode() 轻(只写成员)。用大小写区分语义在 C++ 里很少见,通常用 SetXInternal。这里靠"小写开头 = 内部轻量"的约定。

为什么需要轻量版? 因为构造时 RenderFrameHost 还不存在:

// :1176-1186(节选)
	// Set mode and persist flag directly on the controller rather than going
	// through SetZoomMode(), which manipulates HostZoomMap temporary zoom
	// levels and requires a fully initialized RenderFrameHost.
	// The mode will take full effect once the first navigation commits.
	zoom_controller->SetPersistZoomMode(persist);
	zoom_controller->set_zoom_mode(*mode);

new WebContents({ zoomMode: 'isolated', zoomFactor: 1.5 }) 时两个值只能先存着,等第一次导航提交后才生效。

persist 的默认值取决于调用者,这是本节最容易漏的一点:

// :4807-4812
	// When set via the Electron JS API, persist isolated/manual modes across
	// navigations. The extensions API calls SetZoomMode on the controller
	// directly and won't set this flag, preserving Chromium's default behavior.
	GetZoomController()->SetPersistZoomMode(
	*zoom_mode == WebContentsZoomController::ZOOM_MODE_ISOLATED ||
	*zoom_mode == WebContentsZoomController::ZOOM_MODE_MANUAL);

同一个 SetZoomMode,从 JS 调设 persist,从扩展 API 调不设。 因为 SetPersistZoomMode 写在 api::WebContents 的包装方法里,不在控制器里。行为差异藏在包装层:两条路径看起来一样,语义不同,差异只在注释里。

setZoomFactor 用 epsilon() 而不是 0.0 做下界(:4784)——因为 blink::ZoomFactorToZoomLevel(0) 会算出 -inf,之后所有 zoom 计算都变成 NaN。

11.10.2 DevTools:寄生在 WebContents 里的另一个 WebContents

OpenDevTools 只有 28 行,背后是 1404 行的 InspectableWebContents。

// :3782-3810(节选)
void WebContents::OpenDevTools(gin::Arguments* args) {
	if (type_ == Type::kRemote)
	return;
	if (!enable_devtools_)
	return;
	std::string state;
	if (type_ == Type::kWebView || type_ == Type::kBackgroundPage ||
	!owner_window()) {
	state = "detach";
	}
	bool activate = true;
	std::string title;
	if (args && args->Length() == 1) {
	...
	options.Get("mode", &state);
	}
	DCHECK(inspectable_web_contents_);
	inspectable_web_contents_->SetDockState(state);

四道门,每个都有理由。

kRemote 直接返回:它不拥有 content::WebContents,没有 InspectableWebContents。

enable_devtools_ 为假直接返回:这个 bool 从 options.Get("devTools", ...) 读(:1071),默认 true。它是"能不能开"的唯一闸门,而且只能在构造时设——没有 setDevToolsEnabled()。

kWebView / kBackgroundPage / 无 owner_window 默认 detach:这三种都没有可 dock 的窗口。

但默认值可以被覆盖:state 先设成 "detach",紧接着 options.Get("mode", &state) 覆盖它。所以 wc.openDevTools({ mode: 'right' }) 对 <webview> 也会"成功"——SetDockState("right") 之后 InspectableWebContents 发现没有宿主视图,静默退回 detach。"默认"和"强制"在这里是两条赋值语句的区别。

DCHECK 是唯一的断言:如果将来加了第七种 Type 而漏了判断,debug 构建崩在这里,release 构建空指针解引用。

15 个 delegate 回调里,最重的一组是文件系统索引(:5473-5683,约 200 行):DevTools 的 Sources 面板要搜索整个 workspace,得把目录树索引起来,索引在后台线程跑,结果通过 devtools-search-query 一类事件回传。DevToolsSaveToFile 用一个 URL → FilePath 的 map 记账(.h:987),只增不减——一个每项几十字节的慢性泄漏,从来没被清理过,注释也没说为什么。

11.10.3 为什么 DevTools 的 WebContents 必须被 Pin

11.2.3 提过 Pin,这里补完整因果链:

  1. ShowDevTools() 创建一个 content::WebContents 给前端用,包成 api::WebContents,type_ = kRemote。
  2. 前端加载是异步的。加载完之前,JS 侧没有任何人持有这个 wrapper。
  3. 此时若发生 GC,wrapper 被回收,而 C++ 对象还在(由 InspectableWebContents 持有)。
  4. DevToolsOpened() 里要拿 devToolsWebContents:From() 能找到 C++ 对象,GetWrapper() 返回空 → 一个空 handle。

Pin(isolate)(:990)把 wrapper 钉住,第 3 步不会发生;Unpin() 在 WebContentsDestroyed()(:3107)。这是"V8 wrapper 生命周期与 C++ 对象生命周期不一致"的唯一一处显式补偿。

11.11 注册表与查找:三份记账

WebContents 被三个地方记着,三者之间没有同步机制。

11.11.1 三份记账

第一份,base::IDMap:

// :757-759
base::IDMap<WebContents*>& GetAllWebContents() {
	static base::NoDestructor<base::IDMap<WebContents*>> s_all_web_contents;
	return *s_all_web_contents;
}

全局单例,用 base::NoDestructor 包住——静态析构顺序不确定,而 WebContents 的析构可能在静态析构之后跑(V8 的 GC 时机)。

id_ 在三个构造函数的初始化列表里各拿一次(:957、:1010、:1026),全部写成 id_(GetAllWebContents().Add(this))。Add 返回的 id 从 1 开始递增、永不复用——这是 fromId 能安全用于日志的原因:一个 id 只对应一个 WebContents,哪怕它已经死了。

移除时先查再删:

// :3110-3111
	if (GetAllWebContents().Lookup(id_))
	GetAllWebContents().Remove(id_);

先 Lookup 再 Remove,因为 Remove 一个不存在的 id 会 CHECK 失败。

第二份,UserDataLink(11.2.3 讲过):content::WebContents 的 user data 表里挂一个 WeakPtr。这是唯一一份"跟着 content::WebContents 走"的记账,所以 guest 的 api::WebContents 死了而 content::WebContents 还活着时,From() 返回空——WeakPtr 失效了,但 data 对象还在。

From() 返回 nullptr 有两种原因:从来没挂过(kRemote 之外的路径都会挂)、或挂过但已失效。调用方无法区分,也不需要区分。

第三份不是存储,是一个视图:

// :6159-6168(节选)
std::vector<gin_helper::Handle<WebContents>> GetAllWebContentsAsV8(
	v8::Isolate* isolate) {
	std::vector<gin_helper::Handle<WebContents>> list;
	for (auto iter = base::IDMap<WebContents*>::iterator(&GetAllWebContents());
	!iter.IsAtEnd(); iter.Advance()) {
	list.push_back(gin_helper::CreateHandle(isolate, iter.GetCurrentValue()));
	}

每次调用重新遍历 IDMap。所以 webContents.getAllWebContents() 返回的是快照,不反映后续变化。

11.11.2 四个查找函数

函数实现成本
fromId(id)IDMap::LookupO(1)
fromFrame(frame)FromRenderFrameHost + FromO(1)
fromDevToolsTargetId(id)DevToolsAgentHost::GetForId + FromO(1) 哈希
getAllWebContents()遍历 + 建 N 个 handleO(N)

fromDevToolsTargetId 是唯一依赖外部注册表的一个:

// :6146-6150(节选)
gin_helper::Handle<WebContents> WebContentsFromDevToolsTargetID(
	v8::Isolate* isolate, std::string target_id) {
	auto agent_host = content::DevToolsAgentHost::GetForId(target_id);
	WebContents* contents =
	agent_host ? WebContents::From(agent_host->GetWebContents()) : nullptr;

DevToolsAgentHost 的 id 由 DevTools 协议分配(形如 "1A2B3C..."),和 id_ 完全无关,而且是懒创建的。所以 fromDevToolsTargetId 对没开过 DevTools 的 WebContents 永远返回空——文档里没写这个前提。

11.11.3 唯一的裂缝

三份记账正常对齐,因为构造时三步在同一个栈里、销毁时三步在一个函数里。但销毁那三步有一个早退:

// :3112-3115
	if (!GetWrapper(isolate).ToLocal(&wrapper))
	return;

GetWrapper() 失败时函数直接返回——此时 id_ 已经从 IDMap 移除(:3110-3111 在前),但 wrapper 里的 C++ 指针没被置空。结果是:一个已销毁的 api::WebContents,它的 wrapper 里留着悬垂指针。

这个窗口极难触发(要 GC 先回收 wrapper、析构才跑),而且触发时"正确做法"也不存在——GetWrapper() 失败意味着拿不到 wrapper 去改它。但它是三份记账里唯一没有保护的地方,代价是"持有旧 wrapper 的代码会在不可预期的时刻崩溃"。


11.12 失败模式手册

按"你看到了什么"索引:

现象原因定位
wc.loadURL() 失败但没有 unhandled rejectionMarkAsHandled()11.6.2
连续两次 loadURL,第一个 promise 被 ERR_ABORTED 拒绝promise 绑"下一次导航"而非 URL11.6.2
loadURL({ userAgent }) 之后所有请求都带那个 UA选项调了持久 SetUserAgent11.6.1
导航回调里调 loadURL 得到 ERR_FAILEDis_safe_to_delete_ 重入保护11.5.5
did-navigate 里读 getZoomLevel() 是旧值缩放更新在事件之前,但你的监听器可能更早注册11.6.7
页面卡住但 unresponsive 没触发shouldIgnore / visible / rendererInitialized 之一为假11.7.1
崩溃处理器里 reload() 导致主进程崩同步重载撞 RendererStartupHelper 的 CHECK11.7.2
alert() 返回 undefined只传了一个按钮,返回值是 response === 011.4.4
prompt() 永远返回 null不支持11.4.4
<webview> 里按 Ctrl+R 没反应键盘事件冒泡到 embedder 后给了菜单11.8.2
sendInputEvent({type:'mouseWheel'}) 触发两次滚动发了 phaseBegan + 合成的 phaseEnded11.8.1
executeJavaScript 在关窗口时抛 "Render frame was disposed"MainFrameRenderer 三层判空11.9.2
did-start-navigation 的返回值拦不住导航EmitNavigationEvent 返回 preventDefault 但三个调用点都不用11.6.4
sendSync 卡住 500ms 无报错没有监听者,只有一条 warning11.9.6
destroyed 事件偶尔不发WebContentsDestroyed 在 GetWrapper 失败时早退11.5.4

三条最值得记的:

"loadURL 的 promise 语义是下一次导航" 最反直觉。它导致"两个 loadURL 竞争"时第一个被 abort,也导致"页面自己跳转"会结算你的 promise。

"executeJavaScript 的 userGesture 要在浏览器侧先激活" 最隐蔽。不设的话,脚本里 FileSystemFileHandle.createWritable() 这类调用会被拒,而错误看起来是"权限问题"而不是"激活时序问题"。

"sendSync 无监听者只 warning" 最容易被忽略:终端里一行 warn 淹没在日志里,表现是"界面卡一下"。


11.13 性能账本

操作量级主要成本
new WebContents(options)30–90 ms渲染进程启动 + content::WebContents::Create
loadURL() 到 did-navigate网络往返 + 30–200 ms渲染进程导航提交
executeJavaScript() 往返0.3–2 ms一次 Mojo 往返 + 渲染进程执行
wc.ipc.emit 一次投递< 0.05 ms四次 Emit(其中一次可能跳过)
openDevTools()100–400 ms再起一个渲染进程 + 建 DevTools 窗口

两条推论:

一、构造成本几乎全在渲染进程上。 两个 Init 加起来 4ms 左右,其余 30–90ms 是 Chromium 起进程、建 frame 树。所以"延迟创建"省的是大头,"优化初始化"省的是零头。

二、Emit 的成本是"取 wrapper + 建 Event 对象 + 调 JS"。 高频事件单次 10–50 微秒,一次页面加载可能发上百次、累计几毫秒。不是瓶颈,但这是"console-message 要按需开启"的量化依据——控制台消息可能每帧几十条。


11.14 练习题

11.1(入门) 打印 wc.constructor.name、wc.getType()、Object.getPrototypeOf(wc).constructor.name,解释三者的关系,以及为什么 getType() 返回 'window' 而不是 'browserWindow'(11.2.1)。

11.2(入门) 在 WebContentsView 上执行 view.webContents.destroy(),再在 setTimeout(0) 里读 view.webContents。解释为什么是 null,以及 destroyed 与 null 的先后顺序(11.5.7)。

11.3(初级) 连续调两次 wc.loadURL(),用 .then/.catch 打印两次的结果,解释第一个为什么被 ERR_ABORTED 拒绝(11.6.2)。再把第二次改成 wc.loadURL('https://a.com/#x'),观察第一个是否还被拒绝。

11.4(初级) 写一个页面,在 did-navigate 里读 wc.getZoomLevel(),然后把代码移到 did-start-navigation 里再读一次,比较两个值,解释差异(11.6.7)。

11.5(进阶) 构造让 wc.openDevTools() 静默失败的场景:设 webPreferences.devTools: false,再调 openDevTools(),确认没有任何报错。解释 DCHECK 在 release 构建里为什么不起作用(11.10.2)。

11.6(进阶) 用 wc.ipc.handle('x', fn) 注册一个 handler,然后从渲染进程 ipcRenderer.invoke('x'),确认能收到。再把注册改到 ipcMain.handle,比较两种写法在"多个 WebContents 有同名 channel"时的行为差异(11.4.1)。

11.7(进阶) 在 before-input-event 里对 keyDown 调 event.preventDefault(),观察页面是否还能收到按键。然后换成返回 HANDLED_PREVENT_DEFAULT 的语义(用 Emit 的返回值),比较两种"阻止"的差别(11.8.2)。

11.8(深入) 阅读 load_url_promises.cc:110 的 DidStopLoading,列出它在什么情况下会 reject 一条 promise,以及为什么要有"如果 did-finish-load 已经结算过就跳过"的判断(11.6.2)。

11.10(挑战) 给 WebContents 加一个 getBoundWindow():返回 owner_window_ 对应的 JS 对象,窗口已销毁时返回 null。参考 GetOwnerBrowserWindow(:4853)与 NativeWindowRelay(第 10 章 10.7)。


11.15 下一章预告

第 12 章《渲染进程初始化:从 preload 到 contextIsolation》接住本章留下的三条线。

线一:11.3.3 说 MaybeSendRendererStartupData 在 ReadyToCommitNavigation 里把 preload 列表推给渲染进程(:2764、:2806)。第 12 章会讲这条推送的完整协议:为什么在 CommitNavigation 之前、process.env 怎么过去、沙箱与非沙箱的差别。

线二:11.4.1 的 IPC 四站投递里,第 1 站是 webContents.emit('ipc-message')。但渲染进程怎么发出这个消息?第 12 章会讲 ipcRenderer 的实现、ipcRenderer.send 到 webContents.emit 的完整链路,以及为什么 ipcRenderer 在 contextIsolation: true 时必须被隔离。

线三:11.9.1 说 executeJavaScript 的 world_id 区分执行环境。第 12 章讲四个 world(main / isolated / preload / devtools)的创建时机与隔离边界。

一句话预告第 12 章的立论:渲染进程的初始化不是一个函数,是一次跨进程的握手——主进程在导航提交前把"你该有什么"推过去,渲染进程在第一个脚本执行前装好,而这中间任何一步时序变化都会让 preload 里拿不到 require。

11.16 本章源码落点索引

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

  • 浏览器进程 C++ 层:electron_api_web_contents_impl.cc:19 electron_api_web_contents_view.cc:38 electron_api_web_contents_view.h:17 inspectable_web_contents_delegate.h:12 inspectable_web_contents_view.cc:37 inspectable_web_contents_view.h:18 inspectable_web_contents_view_delegate.cc:10 inspectable_web_contents_view_delegate.h:15
  •  electron_api_browser_window.h:14 child_web_contents_tracker.cc:13 child_web_contents_tracker.h:16 electron_web_contents_utility_handler_impl.cc:23 electron_web_contents_utility_handler_impl.h:15 extended_web_contents_observer.h:13 web_contents_permission_helper.cc:35 web_contents_permission_helper.h:20
  •  web_contents_preferences.cc:41 web_contents_preferences.h:22 web_contents_zoom_controller.cc:27 web_contents_zoom_observer.h:15 electron_api_event_emitter.cc:17 electron_api_event_emitter.h:10 electron_api_ipc_dispatch.h:15 electron_api_web_view_manager.cc:19
  •  electron_extension_web_contents_observer.cc:10 electron_extension_web_contents_observer.h:14 file_system_access_web_contents_helper.cc:11 file_system_access_web_contents_helper.h:11 osr_web_contents_view.cc:18 osr_web_contents_view.h:20 osr_web_contents_view_mac.mm:9 inspectable_web_contents.cc:111
  •  inspectable_web_contents.h:28 web_view_manager.cc:12 web_view_manager.h:14 print_view_manager_electron.cc:55 print_view_manager_electron.h:21 electron_api_base_window.cc:69 electron_api_base_window.h:28 electron_api_base_window_mac.mm:15
  •  native_window.cc:55 native_window.h:29 native_window_mac.h:22 native_window_mac.mm:52 native_window_mac_remote.h:25 native_window_mac_remote.mm:46 native_window_observer.h:19
  • shell 其余实现:event_emitter.h:19 event_emitter_caller.cc:11 event_emitter_caller.h:25 event_emitter_template.cc:15 event_emitter_template.h:9 node_event_emitter.cc:58 node_event_emitter.h:26 web_contents_utility.mojom:8
  •  destroyable.cc:20 destroyable.h:13 gin_embedders.h:19 options_reader.cc:16 options_reader.h:33 promise.cc:21 promise.h:23
  • API 文档与类型:browser-window-options.md:3 browser-window.md:5 web-contents-view.md:5 web-contents.md:5
  • JS 门面与运行时:guest-view-internal.ts:5 base-window.ts:4 guest-window-manager.ts:13
  • 其他相关位置:api-browser-window-ignore-mouse-events.spec.ts:27 api-browser-window-posted-click.spec.ts:16