《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.h | 1032 | 13 个基类、6 种 Type、约 180 个方法声明、40 个成员 |
| 实现 | electron_api_web_contents.cc | 6184 | 全部行为:导航、销毁、输入、DevTools、打印、脚本注入、IPC |
| macOS 补充 | electron_api_web_contents_mac.mm | 109 | 键盘事件的一条 Objective-C 分支 |
| JS 门面 | web-contents.ts | 471 | _init 里的三个对象、10 个废弃 API 的包装、5 个导出函数 |
头文件 1032 行、实现 6184 行,比例是 1:6。这个比例在 C++ 项目里偏高——说明大部分复杂度在实现里,而不在接口里:接口是几十行一组的转发声明,实现里则是每个 Chromium 回调各自一套状态机。
11.0.1 6184 行是怎么分布的
按功能把行号切成段,会看到一块很不均匀的分布:
| 行区间 | 长度 | 内容 |
|---|---|---|
| 1–800 | 800 | 头文件包含、匿名命名空间的工具函数(DPI、颜色、UserDataLink) |
| 800–1450 | 650 | 三个构造函数、初始化漏斗、析构、Destroy/Close |
| 1450–2300 | 850 | 新窗口 + WebContentsDelegate 的二十余个回调 |
| 2300–3100 | 800 | WebContentsObserver 的三十余个回调 |
| 3100–4330 | 1230 | 导航控制、属性读取、DevTools 开关、静音、打印与 PDF |
| 4330–5145 | 815 | 编辑命令、查找、焦点、输入事件、拖拽、对话框、堆快照 |
| 5145–5350 | 205 | IPC、脚本注入、CSS 注入 |
| 5350–5750 | 400 | ExclusiveAccessContext、DevTools 文件系统、HTML 全屏 |
| 5750–6184 | 434 | FillObjectTemplate、构造函数工厂、查找、绑定注册 |
两个值得注意的地方。
打印是唯一一块被 #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();
}
三件事:
- 每次
Emit都重新取 wrapper。 wrapper 是 V8 对象,会被 GC。取不到(已被回收)就直接return false——事件静默丢弃,不崩。这是 Electron 里"半死对象"能继续被调用的根本原因:所有Emit在 wrapper 消失后变成空操作。 - 每次都新建一个
internal::Event对象。 它在 JS 侧就是一个普通对象,带preventDefault()。Emit的返回值就是"有没有人调过preventDefault"。 - 返回值是
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 一张身份矩阵
把六种类型在关键能力上逐项对照:
| 能力 | window | browserView | webview | offscreen | remote | backgroundPage |
|---|---|---|---|---|---|---|
拥有底层 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)。所以完整的投递链是四站:
webContents.emit('ipc-message', event, channel, ...args)event.senderFrame.ipc.emit(channel, ...)(如果 frame 还在)webContents.ipc.emit(channel, ...)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() | :1418 | JS 的 wc.destroy()、CloseContents | 决定"现在删还是排队删" |
Close(opts) | :1432 | JS 的 wc.close() | 走 Chromium 的 Close(),可能触发 beforeunload |
~WebContents() | :1343 | delete this | 清理引用、发 will-destroy、可能释放底层 |
WebContentsDestroyed() | :3097 | content::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_ | 退出中 | 行为 |
|---|---|---|---|---|
| any | any | any | 是 | 同步 delete this |
| 是 | 是 | 否 | 否 | 同步 delete this |
| 是 | 是 | 是 | 否 | 排队 |
| 是 | 否 | any | 否 | 排队 |
| 否 | any | any | 否 | 排队 |
这张表没有写在任何注释里,是从三个 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 让它失败。 这个模式的好处是"只有一条返回路径",坏处是"失败也要走一遍事件系统"。
十个选项:
| 选项 | 作用 | 落点 |
|---|---|---|
httpReferrer | Referer 头 | params.referrer |
userAgent | 覆盖 UA | 调 SetUserAgent()(持久生效) |
extraHeaders | 额外头 | params.extra_headers |
postData | POST 体 | params.post_data + LOAD_TYPE_HTTP_POST |
baseURLForDataURL | data 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 七站
一次成功导航穿过的回调:
| 站 | 回调 | 位置 | 发出的事件 |
|---|---|---|---|
| 1 | DidStartNavigation | :2746 | did-start-navigation |
| 2 | DidRedirectNavigation(0..N 次) | :2755 | did-redirect-navigation |
| 3 | ReadyToCommitNavigation | :2834 | -ready-to-commit-navigation(内部) |
| 4 | DidFinishNavigation | :2859 | did-frame-navigate / did-navigate / load-commit |
| 5 | DOMContentLoaded | :2531 | dom-ready |
| 6 | DidFinishLoad | :2541 | did-frame-finish-load / did-finish-load |
| 7 | DidStopLoading | :2602 | did-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() 能被三种情况触发:
- 正常加载完:
DidFinishLoad→DidStopLoading。 - 渲染进程崩了:
// :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().
- 用户调
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:页面可见。不可见的页面卡住不算问题——后台标签页本来就该让出 CPUrendererInitialized:渲染器初始化完了。初始化中的"无响应"是正常启动耗时
三个字段也一并传进事件对象,所以处理器能看到"为什么"。
注意用的是 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()));
}
四个信息点,全部在注释里:
- 回调发生时,
RenderProcessHostImpl还在遍历观察者。 同步发事件等于在别人的遍历里插入用户代码。 - 用户代码可能同步
reload()。 那会尝试重启渲染进程,而在"还没通知完"的状态下重启会撞上extensions::RendererStartupHelper里的CHECK——直接崩主进程。 - 所以延后到消息循环下一轮。
- 退出码必须现在取。 因为延后之间可能发生导航,
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_ | DidFinishNavigation | DidStopLoading(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);
}
三个分支,顺序重要:
- guest 转给 embedder。
<webview>里按的键如果在 guest 里没消费,要冒泡到宿主页面——这是 iframe 的语义。 - DevTools 消费。 F8(暂停)、F10、Ctrl+Shift+C 这些快捷键在页面有焦点时也要能用。
- 窗口消费。
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)。
三个限制:
- 只在主 frame 生效(11.3.3 的 #49256),iframe 里的 drag 区域不上报。
- 只在有原生窗口的类型上生效,离屏和 remote 没有 hit test。
- 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,这里补完整因果链:
ShowDevTools()创建一个content::WebContents给前端用,包成api::WebContents,type_ = kRemote。- 前端加载是异步的。加载完之前,JS 侧没有任何人持有这个 wrapper。
- 此时若发生 GC,wrapper 被回收,而 C++ 对象还在(由
InspectableWebContents持有)。 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::Lookup | O(1) |
fromFrame(frame) | FromRenderFrameHost + From | O(1) |
fromDevToolsTargetId(id) | DevToolsAgentHost::GetForId + From | O(1) 哈希 |
getAllWebContents() | 遍历 + 建 N 个 handle | O(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 rejection | MarkAsHandled() | 11.6.2 |
连续两次 loadURL,第一个 promise 被 ERR_ABORTED 拒绝 | promise 绑"下一次导航"而非 URL | 11.6.2 |
loadURL({ userAgent }) 之后所有请求都带那个 UA | 选项调了持久 SetUserAgent | 11.6.1 |
导航回调里调 loadURL 得到 ERR_FAILED | is_safe_to_delete_ 重入保护 | 11.5.5 |
did-navigate 里读 getZoomLevel() 是旧值 | 缩放更新在事件之前,但你的监听器可能更早注册 | 11.6.7 |
页面卡住但 unresponsive 没触发 | shouldIgnore / visible / rendererInitialized 之一为假 | 11.7.1 |
崩溃处理器里 reload() 导致主进程崩 | 同步重载撞 RendererStartupHelper 的 CHECK | 11.7.2 |
alert() 返回 undefined | 只传了一个按钮,返回值是 response === 0 | 11.4.4 |
prompt() 永远返回 null | 不支持 | 11.4.4 |
<webview> 里按 Ctrl+R 没反应 | 键盘事件冒泡到 embedder 后给了菜单 | 11.8.2 |
sendInputEvent({type:'mouseWheel'}) 触发两次滚动 | 发了 phaseBegan + 合成的 phaseEnded | 11.8.1 |
executeJavaScript 在关窗口时抛 "Render frame was disposed" | MainFrameRenderer 三层判空 | 11.9.2 |
did-start-navigation 的返回值拦不住导航 | EmitNavigationEvent 返回 preventDefault 但三个调用点都不用 | 11.6.4 |
sendSync 卡住 500ms 无报错 | 没有监听者,只有一条 warning | 11.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