《Electron 45.2.3 内核解剖》第 14 章 IPC 架构:从 mojom 到 invoke

2 阅读1小时+

《Electron 45.2.3 内核解剖》第 14 章 IPC 架构:从 mojom 到 invoke

第 13 章把像素送到了屏幕上。这一章换一条轴:两个进程之间怎么说话。

这个题目看起来平淡——ipcRenderer.send 一个函数,ipcMain.on 一个函数,中间还能有什么。但真去读实现会发现,Electron 的 IPC 不是"一条通道",而是七条方向、语义、失败方式都不同的路,共用一层序列化、一层 mojom 接口、一套事件派发。它们中有的是单向的、有的要等回复、有的会阻塞整个渲染进程;有的和导航同序、有的完全不管导航;有的把消息交给四个 emitter 依次过一遍、有的只交给一个。文档把这七条路统称为 "IPC",于是所有"为什么我的 IPC 有时候收不到"的问题都被归到同一个模糊的名字下面。

本章的主线:Electron 的 IPC 是七条共用同一套底层设施的路,每条路上的每一站都有自己的守卫条件;"收不到消息"几乎从来不是传输坏了,而是某一站的守卫没通过——而它大多不报错。


14.0 本章的地形:七个入口、两条管道、一层派发

先把代码摆出来。这一章的代码分布在四个地方:渲染进程的 shell/renderer/api/(发送端)、主进程的 shell/browser/(接收端与反向发送端)、shell/common/(序列化与 mojom 定义)、lib/(两侧的 JS 包装)。

区域文件行数职责
mojom 契约api.mojom:100128ElectronApiIPC / ElectronRenderer / ElectronFrame 三个接口
序列化common/v8_util.cc401V8 → 字节 / 字节 → V8,含 Blink 信封
序列化载体common/serialized_value.h / .cc48 / 31一块 BigBuffer 加一个长度
渲染侧发送electron_api_ipc_renderer.cc533ipcRenderer 与 ipcRendererInternal 两个对象
渲染侧接收electron_ipc_native.cc101把字节变成 emit(channel, event, ...args)
主进程接收electron_api_ipc_handler_impl.cc196ElectronApiIPC 的 frame 版实现
主进程接收(SW)electron_api_sw_ipc_handler_impl.cc229ElectronApiIPC 的 service worker 版实现
派发electron_api_ipc_dispatch.cc / .h909 / 83把消息送给四个 emitter,纯 C++ 无 JS 中转
事件对象electron_api_ipc_event.cc:175 / .h380 / 131event 上的 sender / senderFrame / returnValue
回复通道reply_channel.cc / .h101 / 71把 Promise 的 settle 变成一条 mojo 回复
反向发送electron_api_web_frame_main.cc991frame.send / frame.postMessage / frame.executeJavaScript
端口message_port.cc / .h368 / 104MessagePortMain 与 disentangle

JS 侧薄得几乎不存在,这是这一代实现的一个显著特征:

文件行数内容
ipc-dispatch.ts:1-77把 ipcMain 和 ipcMainInternal 交给 C++
ipc-main-impl.ts:535IpcMainImpl:handle / handleOnce / _invokeHandlers
ipc-main-internal-utils.ts:511handleSync:把 async handler 的结果塞进 returnValue
ipc-renderer-internal.ts1process._linkedBinding('electron_renderer_ipc').ipcRendererInternal
ipc-renderer-internal-utils.ts:311invokeSync:拆 [error, result] 二元组
ipc-messages.ts14九个内部通道名

ipc-dispatch.ts:1-3 只有七行,值得整段抄下来,因为它标出了这一代实现的分界线:

import { ipcMainInternal } from '@electron/internal/browser/ipc-main-internal';
import { ipcMain } from 'electron/main';
// IPC from renderers and service workers is delivered to its listeners by
// api::ipc_dispatch; it only needs these JS-side objects.
process._linkedBinding('electron_browser_ipc_dispatch').setup({ ipcMain, ipcMainInternal });

"it only needs these JS-side objects" ——派发逻辑整个搬进了 C++(electron_api_ipc_dispatch.cc,909 行),JS 只剩两个 EventEmitter 实例被 C++ 持有。这是本章最值得先记住的一件事:老版本 Electron 的 IPC 派发是一段 JS(在 web-contents.ts 里,用 webContents.emit('ipc-message', ...) 一串 emit 手工扇出),现在这段逻辑是 v8::Function::Call 逐个调用 emitter 的 emit 属性。

七个入口

从调用者的角度,能触发一条 IPC 的公开 API 有七个,它们两两不对称:

#调用点方向mojom 方法有回复阻塞调用者
1ipcRenderer.send渲染 → 主ElectronApiIPC::Message无否
2ipcRenderer.sendSync渲染 → 主ElectronApiIPC::MessageSync([Sync])有是
3ipcRenderer.invoke渲染 → 主ElectronApiIPC::Invoke有(Promise)否
4ipcRenderer.postMessage渲染 → 主ElectronApiIPC::ReceivePostMessage无否
5ipcRenderer.sendToHost渲染 → 宿主ElectronApiIPC::MessageHost无否
6webContents.send / frame.send主 → 渲染ElectronRenderer::Message无否
7webContents.postMessage / frame.postMessage主 → 渲染ElectronRenderer::ReceivePostMessage无否

只有一条有回复,且它是同步的。 invoke 的"回复"并不是一个独立的 mojom 方法——它是 Invoke 的返回值(mojom 里的 => (SerializedValue result)),也就是说它借用了 mojom 的请求-应答机制,而不是自己造一套。

一条消息的七站

以 ipcRenderer.send('foo', {a: 1}) 为例,完整路径是:

渲染进程主线程
	① ipcRenderer.send                    ← proto 上的 C++ 函数(不是 JS 类)
	② IPCBase::SendMessage                → SerializeV8Value → BigBuffer
	③ ElectronApiIPC::Message (associated mojo)
		↓ 进程边界(frame 的 associated channel)
主进程 UI 线程
	④ ElectronApiIPCHandlerImpl::Message   → DeserializeV8Value → V8 值
	⑤ ipc_dispatch::Message                → 建 event、装 returnValue/reply
	⑥ emit ×4                              → webContents → frame.ipc → webContents.ipc → ipcMain
	⑦ NotifySessionObservers               → 有监听器时补发 '-ipc-message'

七站里有四站是"可能静默返回"的:②(序列化失败,抛异常)、③(连接断了,无操作)、④(MakeIPCEvent 返回空,或 IsReady() 为假)、⑥(某个 listener 抛异常,直接 return,后面的 emitter 收不到)。本章后面每一节都会回到这张表,指出具体是哪一站在什么条件下放弃。


14.1 五类对象、两种身份

14.1.1 渲染侧的 ipcRenderer 是 C++ 造出来的 EventEmitter

require('electron').ipcRenderer 看起来像一个 JS 类的实例,实际上不是。它由 process._linkedBinding('electron_renderer_ipc') 的 Initialize(electron_api_ipc_renderer.cc:521-529)现场拼出来:

void Initialize(v8::Local<v8::Object> exports, ... v8::Local<v8::Context> context, ...) {
	if (IsWorkerThread())
	CreateEmitters<IPCServiceWorker>(context, exports);
	else
	CreateEmitters<IPCRenderFrame>(context, exports);
}

一个 Initialize 分两支:主线程上造 frame 版,worker 线程上造 service worker 版。两者的差别只在传输对象(T)不同——IPCRenderFrame 拿 RenderFrame 的 associated interface,IPCServiceWorker 拿 worker 的。ipcRenderer 这个名字在 service worker 线程里也存在,只是背后连的是 worker 的通道。

service worker 版有一道硬前置:IPCServiceWorker 的构造函数里有 DCHECK(service_worker_data),而它是从 electron::preload_realm::GetServiceWorkerData(isolate->GetCurrentContext()) 取的。所以这条分支不是"任意 worker 线程",而是"跑过 Electron preload 的 service worker 线程"——普通 Web Worker 没有这个东西。

CreateEmitters(:501-519)做四件事:

electron_api_ipc_renderer.cc:508-515

	v8::Local<v8::Object> ipc_renderer =
	CreateEmitter<T>(context, transport, /*internal=*/false);
	v8::Local<v8::Object> ipc_renderer_internal =
	CreateEmitter<T>(context, transport, /*internal=*/true);
	dict.Set("ipcRenderer", ipc_renderer);
	dict.Set("ipcRendererInternal", ipc_renderer_internal);
	// ipc_native::EmitIPCEvent() delivers incoming messages to these.
	gin_helper::Dictionary(isolate, context->Global())
	.SetHidden("ipcNative", exports);

两个 emitter 共享同一个 transport。 这不是省内存,是正确性要求:internal 只是一个布尔参数,它随每次调用一起过去(mojom 的 Message(bool internal, ...)),传输层不需要知道谁是 internal。于是"internal 通道"在传输层根本不存在,它只是消息上的一个 bit。

第四件事是本章第一个隐藏机制:整个 exports 对象被挂到 context->Global() 的一个私有属性上,键名 "ipcNative"。 反向投递(主进程 → 渲染进程)时,electron_ipc_native.cc:21 用同一个键名把它取回来:

constexpr std::string_view kIpcKey = "ipcNative";
v8::Local<v8::Object> GetIpcObject(v8::Isolate* isolate, const v8::Local<v8::Context>& context) {
	auto binding_key = gin::StringToV8(isolate, kIpcKey);
	auto private_binding_key = v8::Private::ForApi(isolate, binding_key);
	auto global_object = context->Global();
	auto value = global_object->GetPrivate(context, private_binding_key).ToLocalChecked();
	// Nothing in this context listens for IPC (no preload script ran here).
	if (value.IsEmpty() || !value->IsObject())
	return {};
	return value.As<v8::Object>();
}

v8::Private::ForApi 造的是一个跨 context 稳定、但 JS 代码无法枚举的符号。用它的理由有两个:一是页面脚本 Object.getOwnPropertyNames(window) 看不到它(安全);二是同一个名字在不同 context 里指向同一个 private symbol,于是 ipcNative 这件事在两个 world 之间是可寻址的。

写入侧的 SetHidden 走的也是同一条路(dictionary.h:258-261):

	[[nodiscard]] v8::Local<v8::Private> MakeHiddenKey(const std::string_view key) const {
	return v8::Private::ForApi(isolate(), MakeKey(key));
	}

两侧都调 ForApi 才是这个方案能成立的原因。 如果一边用 v8::Private::New(每次生成唯一符号),另一边永远取不到——ForApi 的语义正是"按名字生成一个在该 isolate 内唯一且可重复获取的私有符号"。

那句注释是本章最有用的一句诊断提示:返回空意味着"这个 context 里没有 preload 跑过"。 主进程发来的消息到了渲染进程,如果落在了错误的 world(第 12 章的四个 world),GetIpcObject 就返回空,消息被静默丢弃,一行日志都没有。后面 14.8.1 会专门算这个账。

14.1.2 ipcRendererInternal 少了两个方法

两个 emitter 的形状并不完全一样。CreateEmitter(:461-499)里:

electron_api_ipc_renderer.cc:491-496

	method("send", EmitterMethods<T>::Send, 1);
	method("sendSync", EmitterMethods<T>::SendSync, 1);
	method("invoke", EmitterMethods<T>::Invoke, 1);
	if (!internal) {
	method("sendToHost", EmitterMethods<T>::SendToHost, 1);
	method("postMessage", EmitterMethods<T>::PostMessage, 3);
	}

internal 版只有 send / sendSync / invoke。少掉的两个都有明确的理由:sendToHost 是给 <webview> guest 用的(guest 的宿主是另一个 WebContents,内部通道不该有这个概念);postMessage 会携带 MessagePort,而 internal 通道的接收方是 Electron 自己的 rpc-server.ts:8-13,它不需要端口。

注意 method 这个 lambda 的实现(:481-490)——它把函数装在 proto 上而不是实例上:

electron_api_ipc_renderer.cc:477-480

	v8::Local<v8::Object> emitter = gin_helper::NewNodeEventEmitter(context);
	v8::Local<v8::Object> proto = v8::Object::New(isolate);
	proto->SetPrototype(context, emitter->GetPrototype()).Check();
	emitter->SetPrototype(context, proto).Check();

先建一个 native EventEmitter,再造一个空对象,把空对象的原型指向 EventEmitter 的原型,然后把空对象设成 emitter 的原型。结果是一条三层的原型链:emitter → proto(放方法)→ EventEmitter.prototype(放 on/emit)。

为什么绕这么一圈?注释给了答案:"mirroring the old class IpcRenderer extends EventEmitter so the methods stay off the instance (contextBridge copies own properties only)"。老实现是一个 JS 类,send 这些方法在 IpcRenderer.prototype 上,不在实例上;如果新实现把方法装成实例的自有属性,那么任何"按自有属性遍历"的消费者(contextBridge 的复制逻辑、Object.assign、{...obj})看到的东西就和以前不一样了——原来只能看到一个 EventEmitter,现在会多出五个函数。这一层重构的目标是形状完全不变,所以方法必须待在原型上。

于是还有第二层保险:Unpack(:320-343)把 transport 和 internal 存在**函数对象的 data(internal fields)**里,而不是靠 this:

electron_api_ipc_renderer.cc:326-329

	v8::Local<v8::Object> data = info.Data().As<v8::Object>();
	*internal = data->GetInternalField(kInternal).As<v8::Value>()->IsTrue();
	if (!gin::ConvertFromV8(isolate,
							data->GetInternalField(kTransport).As<v8::Value>(),
							transport) || !*transport) { ... }

注释说得比我能说得更好:"so the functions work unbound (const { send } = ipcRenderer) as the JavaScript implementation's closures did"。老实现是一个 JS 类,方法里用闭包变量 internal 和 binding;现在换成 internal field,语义等价——const { send } = ipcRenderer; send('x') 在新旧两代实现里都能工作。

这是本章的第一个"跨语言等价性"样本:把一段 JS 搬到 C++ 时,真正难的不是功能,是那些 JS 里免费得到、C++ 里要手工重现的语义(闭包捕获、this 无关性、原型链形状、属性可枚举性)。后面 14.5 会看到同样的问题在派发侧再出现一次,处理手法完全不同。

14.1.3 主进程侧的五个 IpcMainImpl

渲染侧只有一个 transport 两个 emitter;主进程侧有三份完全独立的 IpcMainImpl:

实例创建位置谁往里注册收到什么
ipcMainipc-main.ts:3-5应用代码所有非 internal 的 frame IPC
ipcMainInternalipc-main-internal.ts:3Electron 内部internal 通道 + 部分内部事件
webContents.ipcweb-contents.ts:209应用代码只属于这个 WebContents 的消息
frame.ipcweb-frame-main.ts:5应用代码只属于这个 frame 的消息
worker.ipcservice-worker-main.ts:5应用代码只属于这个 service worker 的消息

后两个是懒创建的:WebFrameMain.prototype.ipc 和 ServiceWorkerMain.prototype.ipc 的 getter 在第一次读时 new IpcMainImpl(),然后 Object.defineProperty(this, 'ipc', { value: ipc }) 把它变成数据属性,下次读就不再新建。WebContents.ipc 稍早一点——它在 _init 里就建好,用一个闭包变量捕获,get 只是返回它。

IpcMainImpl(35 行)只有一个有意思的地方:_invokeHandlers 是一个 Map,和 EventEmitter 的 _events 完全分开。

ipc-main-impl.ts:5-9

export class IpcMainImpl extends EventEmitter implements Electron.IpcMain {
	private _invokeHandlers: Map<string, (e: IpcMainInvokeEvent, ...args: any[]) => void> = new Map();
	constructor() {
	super();
	// Do not throw exception when channel name is "error".
	this.on('error', () => {});
	}

构造函数里那行 this.on('error', () => {}) 是个真实教训的化石:Node 的 EventEmitter 在 emit 'error' 且无监听器时会抛异常,而 'error' 恰好是一个非常常见的 IPC 通道名(很多应用用它传日志)。加一个空监听器把这条规则堵掉。

handle 的两个检查都值得记住,因为它们是同步抛的,不是返回失败:

ipc-main-impl.ts:15-20

	handle: Electron.IpcMain['handle'] = (method, fn) => {
	if (this._invokeHandlers.has(method)) {
	throw new Error(`Attempted to register a second handler for '${method}'`);
	}
	if (typeof fn !== 'function') {
	throw new TypeError(`Expected handler to be a function, but found type '${typeof fn}'`);
	}
	this._invokeHandlers.set(method, fn);
	};

重复注册直接抛,这是 invoke 与 on 最大的行为差异:on 可以挂任意多个监听器(都会跑),handle 只能有一个(后来的抛错)。这条差异直接来自 14.6 的实现——FindInvokeHandler 找到第一个就停。

14.1.4 _invokeHandlers 是一条跨语言的私有字段约定

_invokeHandlers 在 TypeScript 里是 private,但那只是编译期约束。C++ 侧直接按名字读它(electron_api_ipc_dispatch.cc:383-398):

v8::Local<v8::Value> FindInvokeHandler(v8::Local<v8::Context> context,
									v8::LocalVector<v8::Object>& targets,
									v8::Local<v8::Value> channel) {
	for (v8::Local<v8::Object> target : targets) {
	v8::Local<v8::Value> handlers = GetProperty(context, target, "_invokeHandlers");
	if (!handlers->IsMap())
	continue;
	v8::Local<v8::Value> handler;
	if (handlers.As<v8::Map>()->Get(context, channel).ToLocal(&handler) &&
		handler->IsFunction()) {
	return handler;
	}
	}
	return v8::Undefined(JavascriptEnvironment::GetIsolate());
}

这段代码有四个隐含约束,每一个都能被一次无害的重构打破,而且打破后不报错:

  1. 字段名必须正好是 _invokeHandlers。 改个名字,C++ 就找不到,invoke 全部变成 "No handler registered"。
  2. 必须是 Map 而不是普通对象。 IsMap() 检查不过就 continue,同样静默。
  3. 键必须是原始字符串。 Map::Get 用的是 SameValueZero,'foo' 和 new String('foo') 不是同一个键——而 handle 的 method 参数在 TS 里声明为 string,运行时不做校验,传 String 对象就再也取不出来。
  4. 值必须是函数。 handleOnce 存的是一个包装函数,所以仍然是函数;如果有人自定义 IpcMainImpl 存别的,检查不过。

这是"跨语言隐式接口"的典型形态:C++ 没有能力声明"我要一个带名为 _invokeHandlers 的 Map 字段的对象",只能用属性查找去试探。 试探失败的默认行为是 continue(当作"这个对象没有 handler"),于是错误从"类型不匹配"退化成了"没有处理器"。

14.1.5 为什么需要两条 internal 通道

internal 这个布尔贯穿全章,值得说清它的用途。

ipc-messages.ts:1-5 里的九个通道全是内部用途:

export const enum IPC_MESSAGES {
	BROWSER_PRELOAD_ERROR = 'BROWSER_PRELOAD_ERROR',
	BROWSER_GET_PROCESS_MEMORY_INFO = 'BROWSER_GET_PROCESS_MEMORY_INFO',
	GUEST_VIEW_INTERNAL_DISPATCH_EVENT = 'GUEST_VIEW_INTERNAL_DISPATCH_EVENT',
	GUEST_VIEW_MANAGER_CREATE_AND_ATTACH_GUEST = 'GUEST_VIEW_MANAGER_CREATE_AND_ATTACH_GUEST',
	...
}

它们是 Electron 自己(rpc-server.ts:11、guest-view-manager.ts、第 12 章的 preload 错误上报)用的,不是给应用的。分成独立通道的理由不是"性能"或"安全边界",是命名空间隔离:BROWSER_PRELOAD_ERROR 这种名字,应用完全可能自己用;如果内部代码和应用代码共用一个 ipcMain,谁先注册谁赢(on 允许重复,两个都跑),内部逻辑就会被应用的同名通道干扰。

internal 通道的接收方只有 ipcMainInternal,且不经过 WebContents 的 'ipc-message' 事件:

electron_api_ipc_dispatch.cc:614-618

	if (internal) {
	if (Emit(context, registry.ipc_main_internal.Get(isolate), argv).IsEmpty())
	return;
	NotifySessionObservers(context, session, session_event, {event, argv[0], args});
	return;
	}

(electron_api_ipc_dispatch.cc:614-620。)这一支里 handled 的概念不存在,因为 internal 消息没有"没人听"的警告——内部代码自己清楚谁在听。


14.2 传输层:ElectronApiIPC 的五个方法

14.2.1 契约

api.mojom 里 frame 与 service worker 共用同一个接口:

api.mojom:100-106

interface ElectronApiIPC {
	// Emits an event on |channel| from the ipcMain JavaScript object in the main
	// process.
	Message(bool internal, string channel, SerializedValue arguments);
	// Emits an event on |channel| from the ipcMain JavaScript object in the main
	// process, and returns the response.
	Invoke(bool internal, string channel, SerializedValue arguments) => (SerializedValue result);
	ReceivePostMessage(string channel, blink.mojom.TransferableMessage message);
	// Emits an event on |channel| from the ipcMain JavaScript object in the main
	// process, and waits synchronously for a response.
	[Sync]
	MessageSync(bool internal, string channel, SerializedValue arguments) => (SerializedValue result);
	MessageHost(string channel, SerializedValue arguments);
}

五个方法里有三个细节值得停一下。

第一,arguments 是单数的 SerializedValue,不是 array<SerializedValue>。 多个参数被打包成一个数组再序列化(14.3 会看到 Rest(info, 1) 怎么造这个数组)。这意味着 send('foo', a, b) 和 send('foo', [a, b]) 在线上是同一串字节,区别只在主进程侧怎么拆:派发时把数组摊平成 event, ...args,所以 (e, a, b) 与 (e, [a, b]) 是两个不同的结果。这个"打包再摊平"的设计让参数个数完全动态,代价是接收端必须先判断"这是数组吗"。

第二,ReceivePostMessage 走的是 blink::TransferableMessage,不是 SerializedValue。 两条序列化路径,一条是 Electron 自己的(SerializeV8Value → SerializedValue),一条是 Blink 的(SerializeV8Value → CloneableMessage → TransferableMessage)。为什么不能统一——因为 MessagePort 的转移必须用 Blink 的 MessagePortChannel,而它只能装在 TransferableMessage 里。

第三,[Sync] 只标在 MessageSync 上。 mojom 的 [Sync] 是一个编译期属性,它让生成的代码把一个异步接口变成阻塞调用:渲染进程发出消息后在 IPC 层自旋等待,直到浏览器回包。这是整个 Electron 里唯一一处主动引入跨进程阻塞的公开 API。

14.2.2 为什么必须是 associated interface

IPCRenderFrame 的构造函数(electron_api_ipc_renderer.cc:219-237)只做了一件事:

	if (execution_context->IsWindow()) {
	RenderFrame* render_frame = GetCurrentRenderFrame();
	DCHECK(render_frame);
	render_frame->GetRemoteAssociatedInterfaces()->GetInterface(
		&electron_ipc_remote_);
	} else {
	NOTREACHED();
	}

GetRemoteAssociatedInterfaces() 而不是 GetRemoteInterfaces()。这两个的差别是本章最重要的一条底层事实:

  • 非 associated(GetRemoteInterfaces()):新建一条独立的 mojo 管道,消息顺序只在这条管道内部有保证,与 frame 的导航、加载、其它接口之间没有顺序关系。
  • associated:接口被"挂"在 frame 已有的那条 content.mojom.Frame 通道上,消息与那条通道上的所有消息共用一个顺序。

mojom 文件里对 ElectronFrame 的注释把这条讲得最清楚:

// Per-frame interface associated with content.mojom.Frame, so its messages and
// replies are ordered with navigation and the frame's other host messages:
// SetStartupData() arrives before the CommitNavigation that follows it, and a
// reply is seen after anything the frame told its host while handling the
// request.

ElectronApiIPC 也是 associated,理由不如 ElectronFrame 那么强(IPC 本身不需要和导航同序),但有一个实际好处:当 frame 被销毁时,associated 接口随宿主通道一起断开,不需要额外的生命周期管理。如果它是非 associated 的独立管道,浏览器就得自己盯着 RenderFrameHost 的销毁来清理,而"盯着"这件事在跨进程场景里永远有窗口期。

14.2.3 注册条件:子 frame 的静默失败

浏览器侧注册这个接口的地方在 electron_browser_client.cc:1849-1870:

void ElectronBrowserClient::RegisterAssociatedInterfaceBindersForRenderFrameHost(
	content::RenderFrameHost& render_frame_host,
	blink::AssociatedInterfaceRegistry& associated_registry) {
	auto* contents = content::WebContents::FromRenderFrameHost(&render_frame_host);
	if (contents) {
	auto* prefs = WebContentsPreferences::From(contents);
	if (render_frame_host.GetFrameTreeNodeId() ==
			contents->GetPrimaryMainFrame()->GetFrameTreeNodeId() ||
		(prefs && prefs->AllowsNodeIntegrationInSubFrames())) {
	associated_registry.AddInterface<mojom::ElectronApiIPC>(...);
	}
	}

条件是一个或:主 frame,或者开了 nodeIntegrationInSubFrames。

这就是本章第一个可复现的静默失败:渲染进程侧无论主 frame 还是子 frame,IPCRenderFrame 的构造函数都会 GetInterface(它不知道浏览器有没有注册)。如果没注册,mojo 的行为是把这条 associated endpoint 关掉——不是抛错,不是返回空,是让 electron_ipc_remote_ 处于"已绑定但已断开"的状态。之后每一次 send:

	void SendMessage(...) {
	if (!electron_ipc_remote_) {
	thrower.ThrowError(kIPCMethodCalledAfterContextReleasedError);
	return;
	}

!electron_ipc_remote_ 用的是 mojo::AssociatedRemote 的 operator bool,它检查的是 is_bound(),而断开的 remote 仍然是 bound 的。所以 send 顺利通过检查、顺利序列化、顺利调用 Message(),然后消息掉进虚空。

更糟的是错误文案:如果它真的走了 thrower 那一支,报的是 "IPC method called after context was released"——在一百个可能的原因里,这句话命中最不可能的那个(context 释放)。这条文案值得记住,因为它是"实现细节泄漏成错误信息"的典型:检查的是 remote 有没有绑定,报的是 context 有没有释放,两者只在一种情况下等价。

(对照第 12 章:子 frame 里 preload 会不会跑,取决于 ShouldLoadPreload 的 node_integration_in_sub_frames;这里的注册条件用的是同一个偏好。所以"子 frame 里 preload 跑了但 IPC 不通"这个组合,只可能出现在 sandbox: false + 子 frame + 未开 nodeIntegrationInSubFrames 的交叉配置里——此时 preload 因为 is_main_frame || is_devtools || allow_node_in_sub_frames 为假而不跑,于是 IPC 不通也没人发现。)

14.2.4 [Sync] 的三层代价

sendSync 的代价不止"阻塞渲染进程"这么简单,它有三层,一层比一层隐蔽。

第一层:渲染进程主线程被挂住。 这不是"JS 在等",而是 IPC 层的同步等待——MessageSync 内部进入 mojo 的同步调用路径,把当前线程阻塞在一个事件上,直到收到回复或通道断开。这期间该渲染进程的所有 frame 都停住(渲染进程主线程只有一个),包括同进程里的 iframe 和正在跑的动画。

第二层:它把浏览器 UI 线程变成关键路径。 回复必须在 UI 线程上产生(ElectronApiIPCHandlerImpl::MessageSync 就在 UI 线程),所以主进程 UI 线程只要忙超过一帧,渲染进程就卡一帧。而 UI 线程忙是常态——一个同步的文件 IO、一个大的 JSON.parse、一次同步的 dialog.showMessageBox,都会传导过去。

第三层:它可以构成跨进程死锁。 三个角色两两等待即可成环:

渲染进程 R1  --sendSync-->  主进程 UI 线程(正在等 R2 的同步 IPC 或某个渲染侧回复)
主进程       --等待------>  R2
R2           --sendSync-->  主进程(排队在 R1 后面)

这一条不需要任何一方写错代码,只需要"两个渲染进程在主进程同一段逻辑里各发一条 sendSync"。第 11 章的 LoadURLPromises 一节提过 kErrAborted 这类硬编码错误码,sendSync 的死锁是同一个层级的问题:跨进程的同步调用天然携带死锁风险,而 Electron 只提供了 sendSync 一个同步原语,没有任何超时机制。

顺带一个实现细节:MessageSync 的回复可以晚于监听器返回。证据在 Electron 自己的 handleSync(ipc-main-internal-utils.ts:5-10):

export const handleSync = function <T extends IPCHandler>(channel: string, handler: T) {
	ipcMainInternal.on(channel, async (event, ...args) => {
	try {
	event.returnValue = [null, await handler(event, ...args)];
	} catch (error) {
	event.returnValue = [error];
	}
	});
};

event.returnValue 的赋值发生在 await 之后,也就是监听器函数已经返回、JS 栈已经弹空之后。这是合法的——mojo 的同步回复可以在任意时刻发出,接收方一直等在那里。

这个事实有两个推论:一是 sendSync 的超时行为完全不可控(没有超时,只有"等到天荒地老");二是"同步"只约束调用者,不约束被调用者,所以主进程侧的 handler 可以 await 一个很慢的 Promise,渲染进程就卡那么久。

14.2.5 反方向的 ElectronRenderer:为什么它不是 associated

主进程发给渲染进程的接口是另一个:

api.mojom:80-83

interface ElectronRenderer {
	Message(bool internal, string channel, SerializedValue arguments);
	ReceivePostMessage(string channel, blink.mojom.TransferableMessage message);
	TakeHeapSnapshot(handle file) => (bool success);
}

它在渲染侧的接收者是 ElectronApiServiceImpl(第 12 章的那个),浏览器侧作为客户端通过 rfh->GetRemoteInterfaces() 拿(electron_api_web_frame_main.cc:460-478):

void WebFrameMain::MaybeSetupMojoConnection() {
	if (render_frame_disposed_) { ... return; }
	if (!renderer_api_) {
	pending_receiver_ = renderer_api_.BindNewPipeAndPassReceiver();
	...
	}
	content::RenderFrameHost* rfh = render_frame_host();
	DCHECK(rfh);
	// Wait for RenderFrame to be created in renderer before accessing remote.
	if (pending_receiver_ && rfh && rfh->IsRenderFrameLive()) {
	rfh->GetRemoteInterfaces()->GetInterface(std::move(pending_receiver_));
	}
}

三个设计选择:

一,非 associated。 webContents.send 不需要和导航同序——事实上它最常被用来"在导航之前先把状态推过去",如果与导航同序,反而会引入新的时序耦合。

二,pending_receiver_ 的延迟绑定。 这里有一个真实的时间窗口:WebFrameMain 对象可以在 RenderFrameHost 创建之后、RenderFrame 在渲染进程就绪之前被访问。此时 rfh->IsRenderFrameLive() 为假,接口拿不到。实现的选择是把 receiver 存起来,等下一次访问时再绑——所以 GetRendererApi() 每次都会调 MaybeSetupMojoConnection()。代价是:如果 RenderFrame 永远不就绪(比如导航被取消),send 会一直静默失败;而且只有下一次有人调 GetRendererApi() 时才重试,没有人调就永远不绑。

三,Message 没有返回值,也没有 ack。 主进程 send 出去之后不知道对方收没收到。这不是疏忽——加 ack 会让 webContents.send 在页面卡顿时排队,而那正是最不该排队的时候。

14.2.6 两条管道、四组顺序

现在可以精确回答"IPC 的顺序保证是什么"这个常被问的问题。答案是一张表:

关系是否有序原因
同一 frame 的多次 send有序同一条 associated 管道,FIFO
send 与 sendSync 与 invoke 之间(同 frame)有序同一个 ElectronApiIPC 接口
主进程发往同一 frame 的多次 send有序同一个 ElectronRenderer 接口
渲染 → 主 与 主 → 渲染 之间无序两条独立的管道
不同 frame(甚至同一渲染进程)之间无序每个 frame 一条 associated 通道
invoke 的请求与它的回复有序对mojom 的请求-应答语义

第四行最容易被误解。很多人以为"ipcRenderer.send('a') 之后主进程 webContents.send('b'),渲染进程一定先看到自己的 a 被处理、再看到 b"。真相是:a 走 ElectronApiIPC,b 走 ElectronRenderer,两条管道之间没有任何顺序保证。实践上它们常常有序,因为两条管道都很快、且都在 UI 线程处理,但这是时序巧合,不是契约。

第六行也有个陷阱:invoke 的回复有序,只保证"回复在请求之后",不保证在这个请求的回复之前没有别的消息插队。如果 invoke('x') 之后紧接 send('y'),主进程一定先处理 x,但 x 的回复到达渲染进程时,y 可能已经被处理完了——因为回复是异步的,而 y 在另一个方向上也很快。

14.3 序列化:SerializeV8Value 与那层假的 Blink 信封

14.3.1 为什么字节流里要写一个"版本号 19"

v8::ValueSerializer 的输出是纯字节,没有任何自描述。为了让两条路径(Electron 的 SerializedValue 和 Blink 的 TransferableMessage)用同一份序列化代码,Electron 在字节流最前面塞了一个伪造的 Blink 信封(v8_util.cc:180-186):

	void WriteBlinkEnvelope(uint32_t blink_version) {
	// Write a dummy blink version envelope for compatibility with
	// blink::V8ScriptValueSerializer
	WriteTag(kVersionTag);
	serializer_.WriteUint32(blink_version);
	}

调用点是 Write 的第一行:WriteBlinkEnvelope(19);。三个常量在文件头:

v8_util.cc:40-42

constexpr uint8_t kNativeImageTag = 'i';
constexpr uint8_t kTrailerOffsetTag = 0xFE;
constexpr uint8_t kVersionTag = 0xFF;

所以每一个 Electron IPC 消息的前 5 个字节永远是 FF 13 00 00 00(0xFF 后跟小端 uint32 的 19)。注释用的是 "dummy",但它的作用不是占位——它让 Electron 的字节流在格式上是合法的 Blink serialized script value,于是 postMessage 那条路径可以直接把同一份字节塞进 blink::CloneableMessage.encoded_message,不需要重新序列化。

反序列化侧对应地有一个版本分支(ReadBlinkEnvelope,:238-270):

v8_util.cc:255-262

	static constexpr uint32_t kMinWireFormatVersionWithTrailer = 21;
	if (*blink_version >= kMinWireFormatVersionWithTrailer) {
	// In these versions, we expect kTrailerOffsetTag (0xFE) followed by an
	// offset and size.
	uint8_t trailer_offset_tag = 0;
	if (!ReadTag(&trailer_offset_tag) || trailer_offset_tag != kTrailerOffsetTag)
		return false;
	constexpr size_t kTrailerOffsetDataSize = sizeof(uint64_t) + sizeof(uint32_t);
	if (!deserializer_.ReadRawBytes(kTrailerOffsetDataSize, &trailer_offset_and_size_bytes))
		return false;
	}

19 小于 21,所以 Electron 自己写的字节流永远走不到这个分支。它存在的原因是前向兼容:如果哪天 Electron 把这个假版本号提到 22(跟着 Blink 一起升),读到新格式的旧代码会在这里崩掉而不是静默错位——先失败比读错好。

ReadTag/WriteTag/kVersionTag 这三个名字抄自 third_party/blink/renderer/core/v8/serialization/serialization_tag.h,注释里明确写了出处。这是 Electron 与 Blink 私有格式耦合的又一处(第 12 章的 preload 代码缓存是另一处):格式没有公开 API,只能靠复制常量来对齐。

14.3.2 两条缓冲:heap_ 与 transport_

V8Serializer 持有两块缓冲(:190-193):

v8_util.cc:188-192

	v8::Isolate* isolate_;
	std::vector<uint8_t> heap_;
	mojo_base::BigBuffer transport_;
	size_t capacity_ = 0;
	bool use_transport_buffer_ = false;

两块而不是一块,是因为两条路径的优化目标不同:

  • 走 blink::CloneableMessage(postMessage、SerializeV8Value(value, CloneableMessage*))时,最终结果必须是一个 std::vector<uint8_t>(owned_encoded_message),所以只能长在堆上。
  • 走 SerializedValue(其余四个方法)时,最终结果要放进 mojo_base::BigBuffer,而 BigBuffer 有一个"超过某个阈值就改用共享内存"的行为。如果先序列化到堆、再拷进 BigBuffer,大消息就会经历一次多余的全量拷贝。

Serialize(value, SerializedValue*)(:70-83)只做一件事:把 use_transport_buffer_ 置真,然后交给 Write:

v8_util.cc:69-76

	bool Serialize(v8::Local<v8::Value> value, SerializedValue* out) {
	use_transport_buffer_ = true;
	size_t length;
	if (!Write(value, &length))
	return false;
	if (transport_.size() == 0 || length <= mojo_base::BigBuffer::kMaxInlineBytes) {
	base::span<const uint8_t> written =
		transport_.size() ? base::span(transport_) : base::span(heap_);
	mojo_base::BigBuffer exact(written.first(length));
	transport_ = std::move(exact);
	}
	*out = SerializedValue(std::move(transport_), length);
	return true;
	}

真正干活的是 ReallocateBufferMemory(:85-118),它是 V8 的 ValueSerializer::Delegate 回调——V8 在需要更多空间时问"给我 N 字节",实现可以决定在哪里给:

v8_util.cc:94-101

	// V8 asks for max(required, 2 * capacity) + 64, so a request beyond plain
	// doubling tells how many bytes the value needs now; move to shared memory
	// once that exceeds an inline message, and grow regions 4x after that.
	const size_t needed = size > 2 * capacity_ + 64 ? size - 64 : capacity_ + 1;
	if (use_transport_buffer_ && needed > mojo_base::BigBuffer::kMaxInlineBytes) {
	mojo_base::BigBuffer bigger(std::max(size, 4 * capacity_));
	// Only kernel-zeroed shared memory is adopted; if the region could not
	// be created BigBuffer falls back to uninitialized heap, so stay on ours.
	if (bigger.storage_type() == mojo_base::BigBuffer::StorageType::kSharedMemory) {
		base::span(bigger).first(capacity_).copy_from(written.first(capacity_));
		transport_ = std::move(bigger);
		heap_ = {};
		capacity_ = transport_.size();
		*actual_size = capacity_;
		return transport_.data();
	}
	}

这段代码有四个可以学的点。

第一,needed 的推导是反推 V8 的分配策略。 V8 请求时给的 size 是 max(required, 2 * capacity) + 64。所以如果 size 恰好等于 2 * capacity + 64,说明这次是"因为扩容策略"而请求,真实需求只比当前容量多一点;如果 size 更大,说明 size - 64 就是真实需求。用这个差值判断"现在是不是真的超阈值了",避免了"每到翻倍点就误判一次"。

第二,kSharedMemory 检查是一道安全门。 注释说得很清楚:如果共享内存创建失败,BigBuffer 会退化成未初始化的堆内存。未初始化的堆内存里可能有上一个对象的残留数据,而 SerializedValue 的长度是单独记录的(size_),只读前 size_ 字节——所以残留数据不会被发出去,但如果接下来有代码误读整块缓冲就会泄漏。实现的处理是:不采用这种退化结果,退回到自己的 heap_。

第三,4 倍增长而不是 2 倍。 大消息的拷贝成本很高(一次共享内存分配 + 一次 memcpy),宁可多占一点虚拟内存,也不要反复搬家。

第四,反向搬运。 如果 use_transport_buffer_ 为真但共享内存拿不到,代码会把 transport_ 里的内容拷回 heap_(:106-112)。这条路径在实践中几乎不会走,但它保证了"不管分配策略怎么变,SerializedValue 总能拿到一块连续可读的字节"。

SerializedValue 本身只有 48 行,核心是那两个成员和一条不变式:

	SerializedValue(mojo_base::BigBuffer buffer, size_t size)
	: buffer_(std::move(buffer)), size_(size) {
	CHECK_LE(size_, buffer_.size());
	}
	base::span<const uint8_t> bytes() const { return base::span(buffer_).first(size_); }
	size_t size() const { return size_; }
	bool is_shared_memory() const {
	return buffer_.storage_type() == mojo_base::BigBuffer::StorageType::kSharedMemory;
	}

buffer_ 可能比 size_ 大——这是 4 倍增长策略的直接后果。头文件里为此专门写了一句话:

// A V8-serialized value held in the buffer it crosses the process boundary in:
// inline bytes for small values, a shared memory region above
// mojo_base::BigBuffer::kMaxInlineBytes. The region may be larger than the
// payload; only the first size() bytes are meaningful.

注释里还有一句解释了 Serialize 里那个看起来多余的 BigBuffer exact(...):

// Only such a region may travel larger than the payload (its spare bytes are
// kernel-zeroed or this value's own); heap-backed results are trimmed.

意思是:共享内存的空白部分是内核清零的(或者就是本值自己写过的),泄漏也无害;而堆内存的空白部分是别人的残留,必须裁掉。所以 Serialize 在小消息(length <= kMaxInlineBytes)时会重新造一个恰好大小的 BigBuffer——不是为了省空间,是为了避免把小消息的堆残留一起发出去。

14.3.3 NativeImage 是唯一有特权的宿主对象

v8::ValueSerializer 遇到无法序列化的对象时会调用 delegate 的 WriteHostObject。V8 只允许宿主在这里写"外部引用",默认实现是抛 DataCloneError。Electron 覆写它,允许一种对象:

	v8::Maybe<bool> WriteHostObject(v8::Isolate* isolate, v8::Local<v8::Object> object) override {
	api::NativeImage* native_image;
	if (gin::ConvertFromV8(isolate, object, &native_image)) {
	WriteTag(kNativeImageTag);
	gfx::ImageSkia image = native_image->image().AsImageSkia();
	std::vector<gfx::ImageSkiaRep> image_reps = image.image_reps();
	serializer_.WriteUint32(image_reps.size());
	for (const auto& rep : image_reps) {
		serializer_.WriteDouble(rep.scale());
		const SkBitmap& bitmap = rep.GetBitmap();
		std::vector<uint8_t> bytes = skia::mojom::InlineBitmap::Serialize(&bitmap);
		serializer_.WriteUint32(bytes.size());
		serializer_.WriteRawBytes(bytes.data(), bytes.size());
	}
	return v8::Just(true);
	} else {
	return v8::ValueSerializer::Delegate::WriteHostObject(isolate, object);
	}
	}

格式是手写的:'i' + 表示数量 + 每份 scale(double) + size(uint32) + 位图字节。对应读取在 ReadNativeImage(:271-300),读完调 api::NativeImage::Create 造一个新对象。

这是唯一一个能跨进程传的 Electron 专有类型。 代价要看清:一张带 1x/2x/3x 三份 rep 的图,过 IPC 时三份 rep 都被完整序列化成位图字节,没有共享、没有惰性——一张逻辑尺寸 1024×1024 的图在线上是 (1²+2²+3²)×1MB ≈ 14MB。所以 nativeImage 过 IPC 的正确姿势是传路径或 buffer,不是传对象。文档里所有 nativeImage 参数都接受 string | NativeImage,两者的成本差一个数量级——这条差异文档没写。

ReadHostObject 那一侧还有一条隐含约束:读到不认识的 tag 就调基类实现(会抛异常)。所以前向兼容是零——如果未来加了第二个宿主对象类型,新旧版本互传必然失败。这在 Electron 里可以接受,因为两端永远是同一个二进制。

14.3.4 反序列化:一条反 TOCTOU 的分支

DeserializeV8Value 有三个重载,最短的那个藏着本章最精细的一段推理(v8_util.cc:316-330):

v8::Local<v8::Value> DeserializeV8Value(v8::Isolate* isolate, const SerializedValue& in) {
	// The process that sent a shared-memory payload can still write to it while
	// it is parsed here; only renderers parse in place, everyone else a copy.
	if (in.is_shared_memory() && !IsRendererProcess()) {
	auto copy = base::HeapArray<uint8_t>::CopiedFrom(in.bytes());
	return V8Deserializer(isolate, copy.as_span()).Deserialize();
	}
	return V8Deserializer(isolate, in.bytes()).Deserialize();
}

推理链条是这样的:

  1. 大消息(超过内联阈值)通过共享内存传递,长度由 size_ 记录。
  2. 共享内存是双方都能映射的。发送方在自己那一侧仍然持有可写映射。
  3. 接收方在解析这块内存。解析不是一次 memcpy,是逐字节读、按 tag 分支、分配对象——耗时与大小成正比。
  4. 如果发送方在这个窗口里改了自己那一侧的数据,接收方就会解析出一份"签名与实际内容不一致"的结构。V8 的 ValueDeserializer 对畸形输入的防御是有的,但那是针对"意外损坏",不是针对"主动构造"。
  5. 所以:只要发送方不可信,就必须先拷贝再解析。

谁可信?主进程发给渲染进程时,发送方是浏览器(Electron 自身的代码),不会在发送后改内存——可以原地解析,省一次全量拷贝。渲染进程发给主进程时,发送方是任意页面脚本——必须拷贝。

is_shared_memory() && !IsRendererProcess():条件读作"我不是渲染进程,且这块是共享内存"。主进程侧命中(拷贝),渲染进程侧不命中(原地)。这条分支是 Electron 的 IPC 里少见的、明确写了威胁模型的代码,虽然只写在一行注释里。

14.3.5 序列化失败的三种表现,对应三个调用点

同一个"序列化失败",在三条路径上有三种完全不同的表现。这是排查"IPC 报错看不懂"问题的关键。

渲染进程发出去(send / sendSync / invoke / postMessage)——抛异常。

electron_api_ipc_renderer.cc:85-88

	electron::SerializedValue message;
	if (!electron::SerializeV8Value(isolate, arguments, &message)) {
	return;
	}
	electron_ipc_remote_->Message(internal, channel, std::move(message));

SerializeV8Value 内部(Write,:153-175)在 WriteValue 失败时做了 isolate_->ThrowException(v8::Exception::Error("An object could not be cloned."))。所以 send 直接抛到调用者的栈上,invoke 的调用者拿到的是同步抛而不是 rejected Promise——这一点很反直觉:ipcRenderer.invoke('x', () => {}) 会抛异常,不会返回一个 reject 的 Promise。文档说"Attempting to send such objects over IPC will result in an error","error" 是抛。

主进程发出去(webContents.send / frame.send)——警告,不抛。

ReadIPCSendArguments(electron_api_web_frame_main.cc:386-417)用了一个 TryCatch 把异常吃掉,转成一条 process warning:

	v8::TryCatch try_catch(isolate);
	if (!gin::ConvertFromV8(isolate, v8::Array::New(isolate, rest.data(), rest.size()), message)) {
	// e.g. a DataCloneError for an argument that cannot be serialized.
	std::string reason = "Failed to serialize arguments";
	if (try_catch.HasCaught()) {
	v8::Local<v8::String> exception;
	if (try_catch.Exception()->ToString(isolate->GetCurrentContext()).ToLocal(&exception)) {
		reason = gin::V8ToString(isolate, exception);
	}
	try_catch.Reset();
	}
	WarnIPCSendFailed(isolate, source, reason);
	return false;
	}

WarnIPCSendFailed(:420-427)拼出 "Error sending from webContents: <reason>" 走 util::EmitWarning。消息丢了,函数返回了,主进程继续跑。 这个不对称有道理:主进程的 send 通常在事件回调里(菜单点击、定时器),抛异常会打断整个回调链;而渲染进程的 send 在页面脚本里,抛异常符合 Web 开发的直觉。

invoke 的回复序列化失败——转成错误回复。

ReplyWithResult(electron_api_ipc_dispatch.cc:263-277)的顺序很讲究:

	v8::Local<v8::Object> reply = v8::Object::New(isolate);
	std::ignore = reply->Set(context, Str(isolate, "result"), result);
	v8::TryCatch try_catch(isolate);
	SendReply(context, event, reply);
	if (try_catch.HasCaught() && !try_catch.HasTerminated()) {
	v8::Local<v8::Value> error = try_catch.Exception();
	try_catch.Reset();
	ReplyWithError(context, event, channel, error);
	}

SendReply 内部会调 gin::ConvertFromV8(isolate, arg, &msg)(reply_channel.cc:59),也就是序列化发生在这里,异常也在这里。抓住之后改发一条 {error} 回复。

所以 handler return 一个函数时,渲染进程拿到的是 reject 的 Promise,错误信息是 "Error invoking remote method 'x': An object could not be cloned."——而不是"主进程崩了"或"没有回复"。这条链路能成立,靠的是 SendReplyImpl 里的一句注释:

reply_channel.cc:51-55

	// Serialize first so a failed conversion leaves |callback| usable.
	electron::SerializedValue msg;
	if (!gin::ConvertFromV8(isolate, arg, &msg))
	return false;
	// Serialization can run JS that replied re-entrantly.
	if (!callback)
	return false;

两句话各挡一种情况。第一句保证失败时 callback_ 没被 move 走,才能改发错误回复。第二句挡的是重入:序列化一个对象可能触发 toJSON 或 getter,那些 JS 可以再调一次 event.reply(),于是 callback_ 已经被别人用掉了——必须再查一次。


14.4 浏览器侧接收:ElectronApiIPCHandlerImpl

14.4.1 一个 self-owned 对象,两条删除路径

ElectronApiIPCHandlerImpl 从不被 unique_ptr 持有,它是 new 出来的,靠两条路删除自己:

electron_api_ipc_handler_impl.cc:24-31

ElectronApiIPCHandlerImpl::ElectronApiIPCHandlerImpl(
	content::RenderFrameHost* frame_host,
	mojo::PendingAssociatedReceiver<mojom::ElectronApiIPC> receiver)
	: render_frame_host_id_(frame_host->GetGlobalId()) {
	content::WebContents* web_contents = content::WebContents::FromRenderFrameHost(frame_host);
	DCHECK(web_contents);
	content::WebContentsObserver::Observe(web_contents);
	receiver_.Bind(std::move(receiver));
	receiver_.set_disconnect_handler(base::BindOnce(
	&ElectronApiIPCHandlerImpl::OnConnectionError, GetWeakPtr()));
}

三条事实:

一,它观察的是 WebContents,不是 RenderFrameHost。 所以同一帧的 handler 会在整个 WebContents 销毁时才被清掉;如果只是 frame 被 swap(导航),handler 还活着。这没问题,因为它不持有 RenderFrameHost*,只持有 GlobalRenderFrameHostId(一对 child_id + routing_id),用的地方现查:

electron_api_ipc_handler_impl.cc:148-149

content::RenderFrameHost* ElectronApiIPCHandlerImpl::GetRenderFrameHost() {
	return content::RenderFrameHost::FromID(render_frame_host_id_);
}

FromID 在 frame 已销毁时返回 nullptr。于是每一个用到它的地方都要处理空值,GetSession() 就是第一个:

electron_api_ipc_handler_impl.cc:152-154

gin::WeakCell<api::Session>* ElectronApiIPCHandlerImpl::GetSession() {
	auto* rfh = GetRenderFrameHost();
	return rfh ? api::Session::FromBrowserContext(rfh->GetBrowserContext()) : nullptr;
}

二,set_disconnect_handler 是主删除路径。 渲染进程销毁、导航、或 associated endpoint 被关掉(14.2.3 的未注册情况)都会触发它。OnConnectionError 里 delete this。

三,WebContentsDestroyed 也 delete this。 两条路径都删同一个对象,靠 WeakPtr 保证 disconnect_handler 不会在对象死后被调用(GetWeakPtr() 在对象析构后失效,mojo 的回调会静默丢弃)。

这个模式在 Electron 里反复出现(InspectableWebContents 的某些子对象、OSR 的几个组件),名字叫 self-owned receiver:mojo 的 SelfOwnedReceiver 提供了同一个功能,但这里没用它——因为还需要 WebContentsObserver 这一层。两套生命周期机制叠在一起,正确的做法就是这里的样子:删除路径只留一条 delete this,其它环节全部用 WeakPtr 保护。

14.4.2 MakeIPCEvent:三道检查和三个"必须回包"

MakeIPCEvent(electron_api_ipc_handler_impl.cc:158-188)是本章第二段最密集的代码:

api::IpcMainEvent* ElectronApiIPCHandlerImpl::MakeIPCEvent(
	v8::Isolate* isolate, api::Session* session, bool internal,
	electron::mojom::ElectronApiIPC::InvokeCallback callback) {
	if (!session) {
	// We must always invoke the callback if present.
	gin_helper::internal::ReplyChannel::SendError(isolate, std::move(callback),
												"Session does not exist");
	return {};
	}
	api::WebContents* api_web_contents = api::WebContents::From(web_contents());
	if (!api_web_contents) {
	gin_helper::internal::ReplyChannel::SendError(isolate, std::move(callback),
												"WebContents does not exist");
	return {};
	}
	v8::Local<v8::Object> wrapper;
	if (!api_web_contents->GetWrapper(isolate).ToLocal(&wrapper)) {
	gin_helper::internal::ReplyChannel::SendError(isolate, std::move(callback),
												"WebContents was destroyed");
	return {};
	}
	return api::IpcMainEvent::Create(isolate, wrapper, GetRenderFrameHost(),
								std::move(callback));
}

那句 // We must always invoke the callback if present. 重复了三次,因为它是mojo 的硬约束:一个请求的 reply callback 如果被销毁而没被调用,mojo 会 DCHECK 失败(release 构建里表现为连接被重置)。所以三条失败路径都必须先把错误回过去,再返回空。

三道检查分别对应三种"世界已经变了":

  1. session 为空:api::Session::FromBrowserContext 返回的是 gin::WeakCell<api::Session>*,弱引用意味着主进程侧的 session 对象可能已经被 GC。这不是理论问题:如果应用代码从来没有强引用过 session.defaultSession,它就可能在某次 GC 后被回收,之后这个 WebContents 的 IPC 全部落在这条错误上。这是"JS 对象生命周期影响 C++ 服务可用性"的又一个例子(第 11 章的三份记账是同一个主题)。
  2. api::WebContents 为空:content::WebContents 还在,但它的 JS wrapper 已经被回收。第 11 章讲过 WebContents 是 CleanedUpAtExit + Pinnable,wrapper 可以被回收而 C++ 对象还活着。
  3. GetWrapper 失败:wrapper 正在析构(gin 的 wrapper 在 GC 过程中拿不到)。

第三道和第二个看起来重复,其实不:第二个查的是"有没有这个包装对象",第三个查的是"能不能现在拿到它的 handle"。中间隔着一次 v8::Local 的创建,而 GC 可以在任意点发生。

注意 IpcMainEvent::Create 的第三个参数是 GetRenderFrameHost()——可能为 nullptr,因为 Create 的签名允许 |frame| may be null。这时事件对象的 frameId / processId / senderFrame 三个属性全部取到 undefined(14.4.4 会看到 getter 里的 has_frame_ 检查)。

14.4.3 那道 IsReady() 门禁

每一个 handler 方法在派发之前都有一模一样的一句:

	if (!ipc_dispatch::IsReady())
	return;

IsReady() 检查的是 ipc-dispatch.ts 有没有跑过:

electron_api_ipc_dispatch.cc:570-572

bool IsReady() {
	const Registry& registry = GetRegistry();
	return !registry.ipc_main.IsEmpty() && !registry.ipc_main_internal.IsEmpty();
}

头文件对这个门的解释是:

// Whether lib/browser/ipc-dispatch.ts has registered ipcMain and
// ipcMainInternal. IPC that arrives earlier is dropped (nothing could be
// listening yet).

这条消息被丢弃,且不回错误。 对 invoke 来说这很危险——回调没被调用,渲染进程的 Promise 永远 pending。为什么可以这么粗暴?因为时序上它不可能发生:lib/browser/init.ts 在加载应用的 main 脚本之前就 require('@electron/internal/browser/ipc-dispatch'),而任何渲染进程都要在应用代码里创建窗口之后才存在。所以这道门是纯防御性的,防的是"未来某次重构把 require 挪到后面"。

这也解释了为什么 GetRegistry() 用 base::NoDestructor:注册表必须在进程整个生命周期内存活,包括退出阶段(此时静态析构顺序不可预测)。

14.4.4 event 对象的八个属性

IpcMainEvent 的属性全部是实例模板上的 native data property,不是每次构造时逐个 Set 的普通属性。FillInstanceTemplate(electron_api_ipc_event.cc:132-210)里有八次 Define,注释说明了一个反直觉的顺序:

void IpcMainEvent::FillInstanceTemplate(v8::Isolate* isolate, v8::Local<v8::ObjectTemplate> templ) {
	// Defined in reverse: template properties enumerate last-defined first.

模板属性按后定义先枚举的顺序排列,所以想让 type 排第一,就得最后一个定义它。八个属性按定义顺序是:_replyChannel(DontEnum)、ports、frameTreeNodeId、processId、frameId、senderFrame、sender、type;枚举顺序正好反过来。

(另外两个成员 preventDefault() 和 defaultPrevented 在 FillObjectTemplate 里,属于原型而不是实例。)

其中四个值得单独看。

type 是一个 symbol 化的字符串。 getter 直接返回 Symbol(isolate, "frame"),所以 event.type === 'frame' 成立,但它是每次二分查找一个 intern 表拿到的(Symbol() 定义在文件头,就是 gin::StringToSymbol)。service worker 版返回 'service-worker'。rpc-server.ts:5-12 里 if (event.type !== 'frame') return; 就是靠这个区分。

senderFrame 每次读都重新解析,并且会警告。

		content::RenderFrameHost* frame = content::RenderFrameHost::FromID(self->frame_id_);
		if (!frame) {
		electron::util::EmitWarning(info.GetIsolate(),
			"Frame property was accessed after it navigated or was destroyed. "
			"Avoid asynchronous tasks prior to indexing.", "electron");
		}

这条警告文案值得背下来——它是"event.senderFrame 是 null 为什么"的标准答案:你把它存进了闭包,然后在 await 之后才读。frame 已经导航走了或销毁了,FromID 返回空。危险在于很多代码写 event.senderFrame.url,没有空值检查,于是 TypeError;而错误发生在异步回调里,堆栈已经和 IPC 无关。

frameId 与 processId 来自 GlobalRenderFrameHostId 的两半:

	Define(isolate, templ, "processId", [](...) {
		if (self && self->has_frame_)
		info.GetReturnValue().Set(self->frame_id_.child_id.GetUnsafeValue());
	});
	Define(isolate, templ, "frameId", [](...) {
		if (self && self->has_frame_)
		info.GetReturnValue().Set(self->frame_id_.frame_routing_id);
	});

child_id 就是渲染进程 id,frame_routing_id 是进程内的 frame 编号。两者合起来才是全局唯一的 frame 标识——所以 webContents.sendToFrame([processId, frameId], ...) 接受一个二元组,而 sendToFrame(frameId, ...) 的单数字形式必须先在 webFrameMain.fromId(processId, frameId) 里补上 processId(web-contents.ts:26-35)。

_replyChannel 是 DontEnum 的,而且是懒取的。 它把内部的 ReplyChannel 包装对象暴露出来,只给 ipc_dispatch 用(14.6 会看到 sendReply)。DontEnum 保证 Object.keys(event) 不会看到它。

最后说一件容易被忽略的事:没有 senderFrameId,也没有 frame 之外的地址信息。 判断"这条消息来自哪个 frame"唯一可靠的途径是 event.senderFrame,而它可能为空。这正是 Electron 安全指南里"永远校验 senderFrame.url"那条建议难写对的原因——校验代码本身要先处理空值,而空值恰恰出现在最需要校验的场景(frame 已经导航走了)。

14.5 派发:ipc_dispatch 的 909 行

14.5.1 为什么把派发从 JS 搬到 C++

老实现里,派发是一段 JS:ipcMain 是个 EventEmitter,浏览器收到消息后先 emit 到 webContents,再由一段 JS 依次 emit 到 frame.ipc、webContents.ipc、ipcMain。这条路的成本结构很糟:

  1. 消息从 mojo 回调进入 C++,C++ 调一个 JS 函数(trampoline),进入 JS。
  2. JS 里做 3–4 次 emit,每次都要走 EventEmitter 的属性查找与监听器数组遍历。
  3. 每次 emit 都是一个独立的 JS 调用帧,Node 的 CallbackScope 语义要靠手工维护。
  4. 参数数组在 C++ 与 JS 之间来回转换两次(C++ 造数组给 JS,JS 再展开给每个 emit)。

新的实现在 electron_api_ipc_dispatch.cc,909 行纯 C++,解决方式是把"扇出"变成在一个 C++ 函数里对若干 V8 对象调用其 emit 属性,全程只有一层 v8::Function::Call,没有 JS→C++→JS 的往返。

代价是本章反复出现的那个主题:JS 里免费的东西要手工重现。 具体四件:

JS 里免费的C++ 里的对应物位置
闭包捕获 ipcMainRegistry 里的 v8::Global<v8::Object>:36-45
字符串字面量常量v8::Eternal<v8::String> intern 表:48-61
一次函数调用一个 CallbackScopeDispatchScope(三个 RAII):502-522
异常自然沿调用栈上抛每次 Call 后手工查 MaybeLocal 是否为空全文

第 4 条最影响代码形状:Emit 的返回类型是 v8::MaybeLocal<v8::Value>,CallMethod 也是,于是全文到处是 if (!X.ToLocal(&y)) return;。一条 listener 抛异常,整个派发立刻停止,后面的 emitter 收不到这条消息——这一点和老实现一致(JS 里 throw 也会中断后续 emit),但 C++ 里没有异常传播机制,只能靠每个调用点检查,所以"一致"是手工维持的。

14.5.2 Message 的七步

Message(:577-658)是主路径,逐段读。

第一步:拿 event 的 wrapper。

	v8::HandleScope handle_scope(isolate);
	v8::Local<v8::Object> event;
	if (!ipc_event->GetWrapper(isolate).ToLocal(&event))
	return;

ipc_event 是 ElectronApiIPCHandlerImpl 刚 MakeIPCEvent 出来的 C++ 对象,这一步把它的 JS wrapper 取出来。取不到就返回——注意这里没有回错误。这是 Message(无回复)的正常情况,Invoke 则会走 RunInvokeHandler 里的 "No handler registered"。

第二步:拿 sender 的 wrapper,并检查"这个 context 能不能跑 JS"。

	// |sender| may be destroyed by a listener below (webContents.destroy() on
	// a <webview> guest deletes it synchronously); only V8 handles are used
	// once JS has run.
	v8::Local<v8::Object> sender_wrapper;
	if (!sender->GetWrapper(isolate).ToLocal(&sender_wrapper) ||
	!DispatchScope::Possible(isolate, sender_wrapper)) {
	return;
	}

那句注释是这一节最该记住的一句:sender 是 api::WebContents*,一个裸 C++ 指针;下面的 listener 可能把它删掉(在 <webview> guest 上调 webContents.destroy() 是同步删除的,第 11 章的 Destroy() 三分支里 is_guest() 那一支直接 delete)。所以从这一行之后,代码不许再碰 sender,只能用 sender_wrapper 这个 V8 handle。

这条纪律在代码里的体现是:sender_id 和 session 都在进入 JS 之前先取出来。

electron_api_ipc_dispatch.cc:599-600

	v8::Local<v8::Value> session = sender->Session(isolate);
	const int32_t sender_id = sender->ID();

session 是 V8 值(不是 C++ 指针),sender_id 是整数。之后所有用到"发送者身份"的地方都用这两个。

第三步:建立派发作用域。

	DispatchScope dispatch_scope(isolate, sender_wrapper);
	v8::Local<v8::Context> context = isolate->GetCurrentContext();

DispatchScope 的构造函数(:506-510)一次建三个 RAII:

electron_api_ipc_dispatch.cc:506-510

	DispatchScope(v8::Isolate* isolate, v8::Local<v8::Object> resource)
	: context_scope_(resource->GetCreationContextChecked(isolate)),
		callback_scope_(isolate, resource, node::async_context{0, 0}),
		microtasks_scope_(resource->GetCreationContextChecked(isolate),
						v8::MicrotasksScope::kRunMicrotasks) {}

注意它用 sender_wrapper 的 creation context,不是当前 context。这是一个必要的选择:webContents 对象是在主进程的 context 里创建的,而此刻的"当前 context"可能已经被别的 JS 改过(比如一个别的地方设的 Context::Scope)。用 creation context 才能保证 sender.emit 在那个对象所属的世界里被调用。

第四步:装事件装饰。

electron_api_ipc_dispatch.cc:605-608

	if (sync)
	AddReturnValue(context, event);
	if (!internal)
	AddReply(context, event);

returnValue 只给同步消息;reply() 只给非 internal 消息。所以:

消息类型event.returnValueevent.reply
send(普通)无有
sendSync有有
internal 的 send / sendSync有(sync 时)无

internal 通道没有 reply() 是设计选择:内部代码用 handleSync 的 returnValue 二元组协议,不需要 reply。

第五步:拼参数。

	v8::LocalVector<v8::Value> argv(isolate);
	BuildArgv(context, &channel, event, args, &argv);

BuildArgv(:122-142)把 [channel, event, ...args] 拼出来,args 是发送端那个"打包的数组":

electron_api_ipc_dispatch.cc:131-138

	if (args->IsArray()) {
	v8::Local<v8::Array> array = args.As<v8::Array>();
	const uint32_t length = array->Length();
	argv->reserve(2 + length);
	for (uint32_t i = 0; i < length; ++i) {
	v8::Local<v8::Value> item;
	if (!array->Get(context, i).ToLocal(&item))
		item = v8::Undefined(isolate);
	argv->push_back(item);
	}
	}

array->Get 可以失败(数组有 getter 且抛异常,或它是 Proxy),失败时塞 undefined 继续。这条兜底保证参数个数不变——如果在这里 return,event 的接收者会看到"参数少了几个",而 arguments.length 是很多 handler 的分支依据。

第六步:扇出。

electron_api_ipc_dispatch.cc:622-629

	bool handled = false;
	// webContents.emit('ipc-message[-sync]', event, channel, ...args)
	{
	v8::LocalVector<v8::Value> wc_argv(isolate);
	wc_argv.reserve(argv.size() + 1);
	wc_argv.push_back(Str(isolate, sync ? "ipc-message-sync" : "ipc-message"));
	wc_argv.push_back(event);
	wc_argv.push_back(argv[0]);
	wc_argv.insert(wc_argv.end(), argv.begin() + 2, argv.end());
	v8::Local<v8::Value> result;
	if (!Emit(context, sender_wrapper, wc_argv).ToLocal(&result))
	return;  // a listener threw; leave the exception to propagate
	handled = result->IsTrue();
	}
	// 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.
	v8::LocalVector<v8::Object> targets(isolate);
	CollectFrameTargets(context, sender_wrapper, ipc_event->frame_tree_node_id(), &targets);
	for (v8::Local<v8::Object> target : targets) {
	v8::Local<v8::Value> result;
	if (!Emit(context, target, argv).ToLocal(&result))
	return;
	handled = handled || result->IsTrue();
	}

第一发和后面几发的参数形状不同。 webContents 上的事件名带了 channel(emit('ipc-message', event, channel, ...args)),而 frame.ipc / webContents.ipc / ipcMain 上是"以 channel 为事件名"(emit(channel, event, ...args))。所以 wc_argv 要额外插一个事件名在头部,而 argv 直接复用。

CollectFrameTargets 在 webContents 的监听器之后调用。 注释给了理由:某个监听器可能在回调里 event.senderFrame.ipc.on(...),先发 webContents 再收集,能让刚注册的 listener 收到这条消息。这是一个"顺序被刻意选择"的例子——如果反过来先收集再发,那条新注册的 listener 就漏了这条消息。

handled 的定义是"任何一个 emitter 的 emit 返回了 true",也就是"至少有一个监听器"。它只用于同步消息的警告(第七步)。

第七步:没有监听器的警告与观察者事件。

electron_api_ipc_dispatch.cc:649-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});
	}
	NotifySessionObservers(context, session, session_event, {event, argv[0], args});

这条警告只在 sync 时出现,因为只有同步消息"没人听"是致命的——渲染进程会一直等到 GC 触发 ReplyChannel 的补发。异步消息没人听就是没人听,不警告。

14.5.3 投递顺序,以及 frame_tree_node_id 为什么不能用 GlobalRenderFrameHostId

CollectFrameTargets(:528-548)的实现:

	v8::Isolate* isolate = JavascriptEnvironment::GetIsolate();
	if (frame_tree_node_id) {
	if (auto* frame = api::WebFrameMain::FromFrameTreeNodeId(
			content::FrameTreeNodeId(frame_tree_node_id))) {
	v8::Local<v8::Object> wrapper;
	v8::Local<v8::Object> ipc;
	if (frame->GetWrapper(isolate).ToLocal(&wrapper) &&
		IpcOf(context, wrapper).ToLocal(&ipc)) {
		out->push_back(ipc);
	}
	}
	}
	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));

三发,顺序固定:frame.ipc → webContents.ipc → ipcMain。加上前面那一发,完整顺序是:

webContents 'ipc-message'  →  frame.ipc  →  webContents.ipc  →  ipcMain

这个顺序有两个可观察后果:

  1. ipcMain 永远最后。所以一个应用的全局 handler 看到的永远是"局部 handler 已经处理过"之后的状态——包括局部 handler 对 event 做的修改(preventDefault、ports)。
  2. 局部注册不会"接管"全局的那一份。在 webContents.ipc 和 ipcMain 上注册同一个 channel,两个 handler 都会跑——它们是两个独立的对象、两张独立的 Map。

为什么用 FrameTreeNodeId 而不是 GlobalRenderFrameHostId?注释就在这段代码上方:

// 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.

"so a frame that is mid-swap still receives it" ——这是本章最值得抄下来的一句。导航时 Chromium 会做 RenderFrameHost swap:旧的 RFH 变成 pending-delete,新的 RFH 接管同一个 frame。如果事件里记的是 GlobalRenderFrameHostId,消息到达时那个 id 指向的 RFH 可能已经在删除队列里,WebFrameMain 就拿不到,消息丢失。而 FrameTreeNodeId 在 swap 前后不变——它标识的是 frame 在树里的位置,不是某一代 RFH。

所以 IpcMainEvent 同时记了两个 id(frame_id_ 和 frame_tree_node_id_),用途完全不同:

  • frame_id_ 给 senderFrame / processId / frameId 用——这三个属性的语义就是"具体的那一代 RFH",拿不到就该为空。
  • frame_tree_node_id_ 给派发用——语义是"这个位置上的 frame",swap 后依然有效。

同一份数据存两遍,因为两个问题问的不是同一件事。 这是本章第二个"看起来冗余,其实精确"的设计(第一个是 SerializedValue 的 buffer 与 size)。

14.5.4 Str():一张按字面量地址索引的 intern 表

electron_api_ipc_dispatch.cc:48-55

v8::Local<v8::String> Str(v8::Isolate* isolate, std::string_view s) {
	static base::NoDestructor<
	absl::flat_hash_map<std::string_view, v8::Eternal<v8::String>>> strings;
	auto it = strings->find(s);
	if (it == strings->end()) {
	// Keyed by the caller's storage: every caller passes a literal.
	it = strings->emplace(s, v8::Eternal<v8::String>(
								isolate, gin::StringToSymbol(isolate, s))).first;
	}
	return it->second.Get(isolate);
}

注释 "Keyed by the caller's storage: every caller passes a literal." 是这一节的全部要点,也是一个真实的雷。

std::string_view 不拥有数据,只存指针和长度。把它当 absl::flat_hash_map 的键,哈希的是内容(absl 对 string_view 的 hash 是按字节算的),但存下来的 key 是视图——指向调用者的缓冲区。只要调用者传的是字符串字面量(静态存储期,永久有效),这张表就安全。

一旦有人传了一个临时 std::string,键就悬空了。 之后查找同一个字符串会做一次 memcmp,读的是已释放的内存——UB,而且是那种"在测试里永远不出现、在客户机上偶发崩溃"的类型。代码里用注释而不是类型来约束这一点(比如把参数改成 const char (&)[N] 就能编译期挡住)。

表里存的是 v8::Eternal<v8::String>,也就是一个跨 GC 的持久句柄,Get(isolate) 每次都拿到当前 isolate 的那个字符串对象。为什么要 intern 而不是每次 gin::StringToSymbol?因为派发路径上一次消息要查十几次属性名(emit、ipc、sender、frameId……),每次都造一个 V8 字符串就是十几次分配 + 十几次哈希。intern 表把这些压成十几次指针比较。

GetProperty 与 CallMethod(:63-84)是这张表的两个使用者:

electron_api_ipc_dispatch.cc:63-69

v8::Local<v8::Value> GetProperty(v8::Local<v8::Context> context,
								v8::Local<v8::Object> object,
								std::string_view name) {
	v8::Local<v8::Value> value;
	if (object->Get(context, Str(JavascriptEnvironment::GetIsolate(), name)).ToLocal(&value))
	return value;
	return v8::Undefined(JavascriptEnvironment::GetIsolate());
}

注意它不用传进来的 isolate,而是每次调 JavascriptEnvironment::GetIsolate()。这是"主进程只有一个 isolate"这个事实的直接映射,也让调用点少写一个参数。代价是这段代码没法在 worker 线程上跑(那些线程有自己的 isolate),不过派发本来只在 UI 线程发生。

GetProperty 的失败兜底是返回 undefined 而不是空——于是 IpcOf 的 ipc->IsObject() 检查会失败,targets 里就少一个。少一个目标不报错,这是 14.10 里"webContents.ipc 收不到消息"那条的根因之一。

14.5.5 Emit 的三个返回值状态

electron_api_ipc_dispatch.cc:101-107

v8::MaybeLocal<v8::Value> Emit(v8::Local<v8::Context> context,
							v8::Local<v8::Object> target,
							v8::LocalVector<v8::Value>& argv) {
	v8::Local<v8::Value> emit = GetProperty(context, target, "emit");
	if (!emit->IsFunction())
	return v8::Undefined(JavascriptEnvironment::GetIsolate());
	return emit.As<v8::Function>()->Call(context, target, argv.size(), argv.data());
}

三种结果,三处调用点各按自己的方式解释:

Emit 返回含义Message 的处理
MaybeLocal 为空有 listener 抛了异常return,整条派发中断,异常留给上层
undefined(非空)目标没有 emit 方法继续下一个目标,handled 不变
false有 emit 但没有监听器继续,handled 不变
true有监听器继续,handled = true

第二行值得注意:如果 webContents.ipc 的 ipc 属性被人改成了一个普通对象(没有 emit),派发不会报错,只是跳过。这是"JS 层的对象形状被 C++ 依赖"的脆弱之处——Str() 表和 _invokeHandlers 约定(14.1.4)是同一类问题。

第一行的处理方式也值得说:C++ 里没有"异常传播"这回事,Call 返回空表示"有一个异常挂在这个 isolate 上"。Message 直接 return,异常继续挂在 isolate 上,mojo 的消息分发结束后由 V8 的默认机制报给进程级 uncaughtException。所以主进程里 ipcMain.on 的回调抛异常,会走到 process.on('uncaughtException')——这是 lib/browser/init.ts:118 里那个 "showErrorBox" 弹窗的来源之一。

14.5.6 PostMessage:三个和 Message 不同的地方

PostMessage(:693-728)看起来和 Message 很像,但有三处实质差异。

一,没有 webContents 'ipc-message' 那一发。

	v8::LocalVector<v8::Object> targets(isolate);
	CollectFrameTargets(context, sender_wrapper, ipc_event->frame_tree_node_id(), &targets);
	v8::LocalVector<v8::Value> argv(
	isolate, {gin::StringToV8(isolate, channel), event, message});
	for (v8::Local<v8::Object> target : targets) {
	if (Emit(context, target, argv).IsEmpty())
	return;
	}

只有 frame.ipc / webContents.ipc / ipcMain 三发。所以 webContents.on('ipc-message') 收不到 ipcRenderer.postMessage 发出的消息——这是一个真实的行为差异,很多"用老式监听器接端口"的代码因此失败。要接端口只能用 ipcMain.on 或 *.ipc.on。

二,端口先挂到 event 上。

	v8::Local<v8::Value> ports_array = v8::Array::New(isolate, ports.data(), ports.size());
	ipc_event->SetPorts(isolate, ports_array);

SetPorts 存进 v8::TracedReference<v8::Value> ports_,ports 属性 getter 在 14.4.4 里已经见过。

三,参数不摊平。

argv 只有三个元素 [channel, event, message]。message 是单值,不是数组——因为 postMessage 的签名就是 (channel, message, transfer),不存在可变参数。到了主进程侧,handler 拿到的是 (event, message)。

这三处差异合起来说明一件事:postMessage 不是 send 的变体,它是另一条语义不同的路,只是共用了同一个 mojo 接口。 文档把两者放在一起讲,是实现层面的复用,不是语义层面的同族。

14.5.7 MessageHost:只发一发

electron_api_ipc_dispatch.cc:748-753

	v8::Local<v8::Value> channel_value = gin::StringToV8(isolate, channel);
	v8::LocalVector<v8::Value> argv(
	isolate, {Str(isolate, "-ipc-message-host"), event, channel_value, args});
	if (Emit(context, sender_wrapper, argv).IsEmpty())
	return;
	NotifySessionObservers(context, session, "-ipc-message-host", {event, channel_value, args});

只有一个目标,且事件名是 -ipc-message-host,channel 是参数。 没有 ipcMain,没有 frame.ipc,因为 sendToHost 的语义是"发给宿主页面",而宿主是那个 WebContents 的创建者——<webview> 的 guest 并不知道宿主是谁。

接收方在 guest-view-manager.ts:171:

	guest.on('-ipc-message-host' as any, function (event: Electron.IpcMainEvent, channel: string, args: any[]) {
	sendToEmbedder(IPC_MESSAGES.GUEST_VIEW_INTERNAL_DISPATCH_EVENT, 'ipc-message', {
	frameId: [event.processId, event.frameId],
	channel,
	args
	});
	});

sendToEmbedder 再走一次 IPC 到宿主页面(GUEST_VIEW_INTERNAL_DISPATCH_EVENT 是 internal 通道),宿主页面的 <webview> 元素上触发 ipc-message DOM 事件。一次 sendToHost 是两次 IPC:guest → 主进程 → embedder 的渲染进程。这条链上有两处可能丢:第二次 IPC 是 webContents.send(非 associated,14.2.5 的三个坑全适用)。

注意 args 在两次传递中始终保持"数组"形态(第一次是 MessageHost 的 args,第二次放进 payload 的 args 字段),到 DOM 事件里才被摊平。这是唯一一条参数不摊平的路径,因为中间那次是 JSON-ish 的普通对象,不是 event, ...args 的调用约定。

14.5.8 NotifySessionObservers:不调 JS 也能判断有没有监听器

electron_api_ipc_dispatch.cc:477-484

void NotifySessionObservers(v8::Local<v8::Context> context,
							v8::Local<v8::Value> session,
							const char* event_name,
							std::initializer_list<v8::Local<v8::Value>> args) {
	if (!session->IsObject())
	return;
	v8::Isolate* isolate = JavascriptEnvironment::GetIsolate();
	v8::LocalVector<v8::Value> argv(isolate, args);
	v8::Local<v8::Object> session_object = session.As<v8::Object>();
	v8::Local<v8::String> name = Str(isolate, event_name);
	v8::Local<v8::Value> events = GetProperty(context, session_object, "_events");
	if (!events->IsObject() || !events.As<v8::Object>()
								->HasOwnProperty(context, name).FromMaybe(false)) {
	return;
	}
	argv.insert(argv.begin(), name);
	std::ignore = Emit(context, session_object, argv);
}

目的是给 IPC 观察工具(Devtron 那类)留钩子:这些工具监听 session 上的 -ipc-message 这类私有事件。但观察工具是罕见的,绝大多数应用没有——所以每次派发都去 emit 一次是纯浪费(emit 会查监听器表、分配一个临时数组)。

优化手段是直接读 EventEmitter 的内部表:session._events 是一个普通对象(或 Map,取决于 Node 版本与事件数),HasOwnProperty(name) 为假就说明"没有任何监听器",直接返回,一次 JS 调用都不发生。

三个细节:

  1. _events 是 Node 的内部字段,不在公开 API 里。它的形状在 Node 的版本之间变过(Object.create(null) 的普通对象 ↔ Map)。这里只做了 IsObject() 和 HasOwnProperty,两者对两种形状都成立——但如果哪天 Node 换成 Map 存单监听器,HasOwnProperty 就会永远为假,钩子静默失效。
  2. HasOwnProperty 的第二个参数(v8::Just(false) 的等价物)隐含在 FromMaybe(false) 里:属性查找抛异常时当作"没有监听器"。
  3. argv.insert(argv.begin(), name) 把事件名插到参数最前面——emit 的第一个参数是事件名,不是参数列表的一部分。这个 insert 是 O(n),但 n 最大是 4(PostMessage 那条)。

这段代码是"性能优化改写语义"的样本:老实现是 if (session.listenerCount(name) > 0) session.emit(...),新实现绕开 listenerCount(那是一次 JS 调用)直接读表。两条路径的可观察行为完全相同,只有成本不同——这正是把派发搬进 C++ 的收益所在。

14.5.9 service worker 的三个方法

ServiceWorkerMessage / ServiceWorkerInvoke / ServiceWorkerPostMessage(:759-874)和 frame 版的结构对称,差异集中在三处:

  1. sender 变成了 session。 没有 WebContents,没有 senderFrame,event 是 IpcMainServiceWorkerEvent(带 session / versionId / processId / serviceWorker 四个属性)。

  2. 目标只有一个:ipcMainInternal(internal 时)或 worker 自己的 ServiceWorkerMain.ipc。CollectServiceWorkerTargets 只往 targets 里推 worker 的 ipc,不推全局 ipcMain。

    看 CollectServiceWorkerTargets(:551-566):它只 push worker 的 ipc。所以是的——service worker 的消息默认只到 ServiceWorkerMain.ipc,不到 ipcMain。这与 frame 的行为不同(frame 的消息一定会到 ipcMain)。

  3. ServiceWorkerMessage 的 internal 分支只推 ipcMainInternal,非 internal 分支只推 worker 的 ipc。两条路互斥,不像 frame 版那样"internal 短路,非 internal 扇出四个"。

第 2 条是一个真实的行为差异,也是"为什么我的 service worker 里 ipcRenderer.send 主进程收不到"的答案:必须在 session.serviceWorkers 拿到的那个 worker 对象的 .ipc 上注册,而不是 ipcMain。文档在 service-worker-main.md 里写了,但和 ipcMain 的心智模型冲突,很容易踩。

顺带说一个容易忽略的对称性:ServiceWorkerMain 也有 send / postMessage(electron_api_service_worker_main.cc:141 用了同一个 ReadIPCSendArguments),路径是 ElectronRenderer::Message。所以主进程 → service worker 用的是和主进程 → frame 相同的接口,而 service worker → 主进程用的是 ElectronApiIPC。方向决定接口,角色不决定接口。

14.6 invoke 的完整回路

14.6.1 渲染侧:一个只装着字节的 Promise

IPCBase::Invoke(electron_api_ipc_renderer.cc:92-116):

	v8::Local<v8::Promise> Invoke(v8::Isolate* isolate, gin_helper::ErrorThrower thrower,
								bool internal, const std::string& channel,
								v8::Local<v8::Value> arguments) {
	if (!electron_ipc_remote_) { thrower.ThrowError(kIPCMethodCalledAfterContextReleasedError); return {}; }
	electron::SerializedValue message;
	if (!electron::SerializeV8Value(isolate, arguments, &message)) { return; }
	gin_helper::Promise<electron::SerializedValue> p(isolate);
	auto handle = p.GetHandle();
	electron_ipc_remote_->Invoke(
		internal, channel, std::move(message),
		base::BindOnce(
			[](gin_helper::Promise<electron::SerializedValue> p,
			electron::SerializedValue result) { p.Resolve(result); },
			std::move(p)));
	return handle;
	}

注意 gin_helper::Promise<T> 的模板参数是 electron::SerializedValue,不是 v8::Local<v8::Value>。这意味着 p.Resolve(result) 走的是 Converter<SerializedValue>::ToV8,也就是:

serialized_value_converter.cc:11-13

v8::Local<v8::Value> Converter<electron::SerializedValue>::ToV8(
	v8::Isolate* isolate, const electron::SerializedValue& in) {
	return electron::DeserializeV8Value(isolate, in);
}

反序列化发生在 p.Resolve(result) 这一行里,不在 mojo 回调的开头。Promise<T>::Resolve 的实现是:

	template <typename T>
	v8::Maybe<bool> Resolve(const T& value) {
	if (!IsAlive()) return v8::Nothing<bool>();
	SettleScope settle_scope{*this};
	return GetInner()->Resolve(settle_scope.context_, gin::ConvertToV8(isolate(), value));
	}

gin::ConvertToV8 就是 Converter<SerializedValue>::ToV8,也就是 DeserializeV8Value。所以反序列化在当前栈上同步执行——SettleScope 在它之前建好 HandleScope 和 Context::Scope(用的是 Promise 创建时保存的那个 context),这就是为什么调用点不用自己写这两个作用域。

顺带一个后果:Deserialize 失败时不抛异常,返回 v8::Null(v8_util.cc:203-217 里三处 return v8::Null(isolate_))。于是 Promise 以 null resolve,UnwrapInvokeResult 拿不到 .error / .result,静默返回 undefined。渲染进程的 invoke 得到 undefined,主进程以为成功回复了。

14.6.2 那一层 UnwrapInvokeResult

EmitterMethods::Invoke(:408-429)在 C++ 的 Promise 外面再套一层:

electron_api_ipc_renderer.cc:416-423

	v8::Local<v8::Promise> reply =
		transport->Invoke(isolate, gin_helper::ErrorThrower(isolate), internal,
						channel, Rest(info, 1));
	if (reply.IsEmpty()) return;
	v8::Local<v8::Function> unwrap;
	v8::Local<v8::Promise> result;
	if (v8::Function::New(context, UnwrapInvokeResult, info[0], 1,
						v8::ConstructorBehavior::kThrow)
			.ToLocal(&unwrap) &&
		reply->Then(context, unwrap).ToLocal(&result)) {
	info.GetReturnValue().Set(result);
	}

info[0] 是 channel 字符串,作为 data 传给 unwrap 函数——它只用于拼错误文案。UnwrapInvokeResult(:431-458):

electron_api_ipc_renderer.cc:436-443

	if (info.Length() < 1 || !info[0]->IsObject() ||
		!info[0].As<v8::Object>()->Get(context, gin::StringToSymbol(isolate, "error")).ToLocal(&error) ||
		!info[0].As<v8::Object>()->Get(context, gin::StringToSymbol(isolate, "result")).ToLocal(&result)) {
	return;   // ← 静默 resolve undefined
	}
	if (error->BooleanValue(isolate)) {
	v8::Local<v8::String> error_string;
	if (!error->ToString(context).ToLocal(&error_string))
		return;
	isolate->ThrowException(v8::Exception::Error(gin::StringToV8(
		isolate, base::StrCat({"Error invoking remote method '",
								gin::V8ToString(isolate, info.Data()), "': ",
								gin::V8ToString(isolate, error_string)}))));
	return;
	}
	info.GetReturnValue().Set(result);

三个要点:

一,协议是 {result} 或 {error} 的普通对象,没有别的字段。 这个形状由浏览器侧的 ReplyWithResult / ReplyWithError 保证。

二,error 为真值就抛。 抛在 then 的回调里,于是外层 Promise reject,reject 的值是 Error("Error invoking remote method 'x': <原文>")。所以主进程里 throw new Error('boom'),渲染进程拿到的是 Error invoking remote method 'x': Error: boom——错误对象被字符串化了,stack 丢失,name 丢失,只有 message。

这一点文档里那句含糊的话指的是同一件事:

However, the Error object in the renderer process will not be the same as the one thrown in the main process.

三,两次 Get 任何一次失败就 return。 于是 Promise resolve 成 undefined。如果主进程的 handler 返回了一个 Proxy,并且它的 get 陷阱在 error 上抛异常呢?不会——浏览器侧构造的是一个普通对象 v8::Object::New(isolate),不是 handler 的返回值本身。result 才可能是任意值,但它只是被放在 {result} 里,读它不触发任何 getter。

这是整个 invoke 回路里唯一一处"两层包装"的设计:{result} 是线上的封装,result 本身是 handler 的返回值。两层都有必要,因为需要一个"成功还是失败"的二值位,而 result 可以是 undefined(handler 什么都没返回),不能用它兼任。

14.6.3 浏览器侧:RunInvokeHandler 的四种返回路径

electron_api_ipc_dispatch.cc:402-409

void RunInvokeHandler(v8::Local<v8::Context> context,
					v8::LocalVector<v8::Object>& targets,
					v8::Local<v8::Object> event,
					const std::string& channel,
					v8::Local<v8::Value> args) {
	v8::Local<v8::Value> channel_value = gin::StringToV8(isolate, channel);
	v8::Local<v8::Value> handler = FindInvokeHandler(context, targets, channel_value);
	if (!handler->IsFunction()) {
	ReplyWithError(context, event, channel_value,
				v8::Exception::Error(gin::StringToV8(
					isolate, base::StrCat({"No handler registered for '", channel, "'"}))));
	return;
	}
	// handler(event, ...args)
	v8::LocalVector<v8::Value> argv(isolate);
	BuildArgv(context, nullptr, event, args, &argv);
	v8::TryCatch try_catch(isolate);
	v8::Local<v8::Value> result;
	if (!handler.As<v8::Function>()
		->Call(context, v8::Undefined(isolate), argv.size(), argv.data())
		.ToLocal(&result)) {
	if (try_catch.HasCaught() && !try_catch.HasTerminated()) {
	v8::Local<v8::Value> error = try_catch.Exception();
	try_catch.Reset();
	ReplyWithError(context, event, channel_value, error);
	}
	return;
	}

BuildArgv(context, nullptr, event, args, &argv) 的第一个参数是 nullptr——没有 channel。所以 invoke 的 handler 签名是 (event, ...args),和 on 的一样。这看起来理所当然,但它意味着 handler 拿不到自己注册时用的 channel:同一个函数注册到两个 channel,函数内部无法区分自己被谁调用。

ipcMain.on 那边也一样拿不到,但它有一个补偿手段——event.reply(channel, ...args),channel 由调用方显式给出。handle 连这个都没有:它只能 return 一个值,回给谁完全由框架决定。这是 invoke 比 send 少一层灵活性的地方,也是 invoke 能做成 Promise 的原因——正因为不需要指定"回给哪个 channel",回复才能退化成一句 resolve(value)。

Call 的 receiver 是 v8::Undefined(isolate)。这和 ipcMain.handle('x', obj.method) 有关——this 不是 obj。EventEmitter 的 on 那边 JS 自己会绑定(emit 用 target 当 receiver),而这里 handler 是从 Map 里取出来的裸函数,receiver 只能给 undefined(非严格模式下变成全局对象,严格模式下就是 undefined)。所以 ipcMain.handle('x', this.handler) 里的 this 一定是错的,必须 bind。

然后是返回值的四条路:

electron_api_ipc_dispatch.cc:440-447

	// await result, then reply. A plain value or a fulfilled Promise replies in
	// the next microtask without promise reactions; a pending or rejected one
	// gets a reaction (attaching it is also what tells the unhandled-rejection
	// tracker a rejection was handled). Any other object goes through a
	// resolver, which reads its `then` once and adopts it if it is a thenable.
	v8::Local<v8::Promise> promise;
	if (IsNativePromise(context, result)) {
	promise = result.As<v8::Promise>();
	} else if (try_catch.HasCaught()) {
	...
	QueueInvokeReply(context, event, channel_value, error, /*rejected=*/true);
	return;
	} else if (result->IsObject()) {
	v8::Local<v8::Promise::Resolver> resolver;
	if (!v8::Promise::Resolver::New(context).ToLocal(&resolver) ||
		resolver->Resolve(context, result).IsNothing()) {
	return;
	}
	promise = resolver->GetPromise();
	} else {
	QueueInvokeReply(context, event, channel_value, result, /*rejected=*/false);
	return;
	}
	if (promise->State() == v8::Promise::kFulfilled) {
	QueueInvokeReply(context, event, channel_value, promise->Result(), /*rejected=*/false);
	} else {
	ReplyWhenSettled(context, promise, event, channel_value);
	}

四条路,对应四种返回值:

handler 返回走哪条什么时候回复
非对象原始值(42 / 'x' / null)最后一个 else下一个微任务
原生 Promise(含 async 函数)且已 fulfilledkFulfilled 分支下一个微任务
原生 Promise 且 pending / rejectedReplyWhenSettled它 settle 时
其他对象(含 thenable、Promise 子类实例)Resolver::Resolve → 可能 pending视情况

IsNativePromise 为什么要检查 constructor:

// Whether Promise.resolve(value) would return |value| itself: a Promise whose
// `constructor` is %Promise%. Instances of Promise subclasses are not; they
// are adopted through their own then() like any other thenable.
bool IsNativePromise(v8::Local<v8::Context> context, v8::Local<v8::Value> value) {
	if (!value->IsPromise()) return false;
	v8::Local<v8::Value> constructor;
	return value.As<v8::Object>()->Get(context, Str(isolate, "constructor")).ToLocal(&constructor) &&
		constructor->StrictEquals(GetRegistry().promise_constructor.Get(isolate));
}

v8::Promise::Then 对 Promise 子类实例会走一条不同的路径(不走子类的 then,直接挂内部反应),而 Promise.resolve() 对子类实例不会返回它本身。这里的判断精确复刻了 Promise.resolve(x) === x 这个条件,从而保证"走快路径"和"走 thenable 慢路径"的语义与 await 完全一致。

GetRegistry().promise_constructor 是在 Setup 里存的:

electron_api_ipc_dispatch.cc:888-893

	v8::Local<v8::Promise::Resolver> resolver;
	v8::Local<v8::Value> constructor;
	if (v8::Promise::Resolver::New(context).ToLocal(&resolver) &&
	resolver->GetPromise()->Get(context, gin::StringToSymbol(isolate, "constructor"))
			.ToLocal(&constructor)) {
	registry.promise_constructor.Reset(isolate, constructor);
	}

用一个临时 Resolver 造一个 Promise,再从它身上取 constructor。这是"拿当前 realm 的 %Promise%"的标准做法——不能用 context->Global()->Get('Promise'),因为用户可能改过全局的 Promise(此时 IsNativePromise 应该按用户改过的那份判断吗?不,这里取的是当前 context 内置的 %Promise%,而 resolver->GetPromise() 的 constructor 也是内置的,两者一定相等,除非用户改过 Promise.prototype.constructor)。

这行代码有个真实的边界:如果用户执行 Promise.prototype.constructor = Fake,那么所有 async 函数返回的真 Promise 都不再被认作 native,全部走 Resolver 路径。结果仍然正确(Resolver 也是内部路径),只是多一次 then 读取——因为 Resolve 遇到 thenable 会调 then,而用户改过的 constructor 不影响实际行为。性能退化而非错误,这是个边界处理得相当稳的地方。

14.6.4 为什么要 EnqueueMicrotask 而不是直接回复

// Replies in a microtask, where `await`ing the result used to put it, so
// microtasks the handler queued still run first.
void QueueInvokeReply(v8::Local<v8::Context> context, v8::Local<v8::Object> event,
					v8::Local<v8::Value> channel, v8::Local<v8::Value> value,
					bool rejected) {
	auto pending = std::make_unique<PendingInvokeReply>();
	pending->event.Reset(isolate, event);
	pending->channel.Reset(isolate, channel);
	pending->value.Reset(isolate, value);
	pending->rejected = rejected;
	context->GetMicrotaskQueue()->EnqueueMicrotask(isolate, SendInvokeReplyMicrotask, pending.release());
}

注释是关键:"where awaiting the result used to put it, so microtasks the handler queued still run first"。老实现是 JS:

// 老版本的等价逻辑
const result = await handler(event, ...args);
event._replyChannel.sendReply({ result });

await 把后续代码放进微任务队列的尾部。如果 handler 是同步函数,await 仍然至少让出一个微任务——所以 handler 里 Promise.resolve().then(() => sideEffect()) 排的微任务会先于回复执行。

新实现如果不做这个,同步 handler 的回复会立刻通过 mojo 发出去,渲染进程的 then 可能在主进程那个 sideEffect 之前跑。这是一个只在"主进程和渲染进程都在观察同一份外部状态"时才能观察到的差异,但它是可观察的,所以必须复刻。

SendInvokeReplyMicrotask 是 v8::MicrotaskQueue 的 native callback:拿到 PendingInvokeReply*,重建 HandleScope 与 Context::Scope,调 ReplyWithResult 或 ReplyWithError。

PendingInvokeReply 用 v8::Global 存 event / channel / value,因为微任务执行时原来的 Local 已经失效。这是本节最朴素也最容易写错的地方:如果换成裸指针存 v8::Local,微任务执行时对象可能已被 GC。

14.6.5 三条错误文案与它们的来源

invoke 失败时渲染进程看到的文案只有三种来源:

文案产生位置触发条件
No handler registered for 'x'RunInvokeHandlerFindInvokeHandler 没找到
Error invoking remote method 'x': <原文>UnwrapInvokeResulthandler 抛异常 / reject / 返回值不可序列化
handler 自己抛的字符串同上,<原文> 部分—

还有两条不是 IPC 层的:

文案来源
Attempted to register a second handler for 'x'IpcMainImpl.handle(同步抛)
Error occurred in handler for 'x':ReplyWithError 里的 console.error(只有日志)

第二条值得单独说。ReplyWithError(:224-259)在回错误之前先打一条主进程日志:

	Console(context, "error",
		{gin::StringToV8(isolate, base::StrCat({"Error occurred in handler for '",
												channel_name, "':"})),
		error});

然后才开始处理"怎么把这个错误变成字符串":

electron_api_ipc_dispatch.cc:238-245

	// error.toString(), which unlike abstract ToString also works for a Symbol;
	// anything that still throws is reported as a plain "Error".
	v8::Local<v8::Value> message;
	{
	v8::TryCatch try_catch(isolate);
	v8::Local<v8::Value> string;
	if (error->IsObject() &&
		CallMethod(context, error.As<v8::Object>(), "toString", 0, nullptr).ToLocal(&string) &&
		string->IsString()) {
	message = string;
	} else if (!try_catch.HasCaught() && !error->IsObject() &&
			error->ToDetailString(context).ToLocal(&string)) {
	message = string;
	} else {
	message = Str(isolate, "Error");
	}
	if (try_catch.HasCaught() && !try_catch.HasTerminated())
	try_catch.Reset();
	}
	v8::Local<v8::Object> reply = v8::Object::New(isolate);
	std::ignore = reply->Set(context, Str(isolate, "error"), message);
	SendReply(context, event, reply);

这段"把任意值变成字符串"的逻辑有四个分支,每个都有具体原因:

  1. 对象 → error.toString(),不用抽象 ToString。注释说 "unlike abstract ToString also works for a Symbol"——Symbol('x') 的抽象 ToString 会抛 TypeError,而 Symbol.prototype.toString 返回 'Symbol(x)'。
  2. 非对象 → ToDetailString(),它不会调用户代码(不像 ToString 会触发 valueOf/toString)。
  3. toString 抛异常或返回非字符串 → "Error"。
  4. try_catch.Reset() 放在末尾而不是 catch 分支里,因为 ToString 失败之后还要继续走后面的分支。

error 的值本身不跨进程——只有它的字符串形式。所以主进程 throw {code: 42} 到渲染进程变成 Error invoking remote method 'x': [object Object]。要传结构化错误,只能自己约定(throw new Error(JSON.stringify(obj)),或者 handler 返回 {ok: false, error: {...}} 而不抛)。

14.6.6 ReplyChannel:一个为了 mojo 约束而存在的对象

ReplyChannel 是 gin::Wrappable,只包一个 InvokeCallback。它存在的唯一理由是头文件里那段注释:

// This object wraps the InvokeCallback so that if it gets GC'd by V8, we can
// still call the callback and send an error. Not doing so causes a Mojo DCHECK,
// since Mojo requires callbacks to be called before they are destroyed.

mojo 的硬约束是:reply callback 在销毁前必须被调用。 而 invoke 的回复时机由用户决定(handler 可能 await 很久),所以 callback 必须活到那时。它挂在 IpcMainEvent 上(cppgc::Member<ReplyChannel> reply_channel_),IpcMainEvent 挂在 JS 的 event 对象上,event 被用户代码持有——只要用户还持有 event,callback 就活着。

如果用户不持有 event 呢?handler 返回后 event 就没引用了,下一次 GC 会回收它,ReplyChannel 的 prefinalizer 被调用:

reply_channel.cc:88-95

void ReplyChannel::EnsureReplySent() {
	v8::Isolate* isolate = v8::Isolate::GetCurrent();
	if (callback_) {
	DCHECK(isolate);
	// Create a task since we cannot allocate on V8 heap during GC
	// which is needed by ReplyChannel::SendError implementation.
	base::SingleThreadTaskRunner::GetCurrentDefault()->PostTask(
		FROM_HERE,
		base::BindOnce(&ReplyChannel::SendError, isolate, std::move(callback_),
					"reply was never sent"));
	}
}

注意 PostTask 的理由:prefinalizer 在 GC 期间运行,而 SendError 要造一个 JS 对象(gin::DataObjectBuilder),GC 期间不能分配。所以只能把 callback 和 isolate 打包成一个任务,扔到消息循环上延后执行。

对 invoke 来说,这条兜底是合理的——渲染进程多等一个 GC 周期(可能很久),然后拿到一条 "reply was never sent"。对 sendSync 来说,这条兜底太晚:渲染进程的主线程已经阻塞在那里,等一个 GC 触发。这就是 14.5.2 第七步那条警告存在的原因——同步消息没人听,等于把渲染进程挂起到下一次 GC。

ReplyChannel 还兼任 event._replyChannel 的暴露者(DontEnum),sendReply 是它唯一的方法:

reply_channel.cc:84-85

bool ReplyChannel::SendReply(v8::Isolate* isolate, v8::Local<v8::Value> arg) {
	return SendReplyImpl(isolate, callback_, arg);
}

第二次调用返回 false,什么都不做。 SendReplyImpl 里 std::move(callback).Run(...) 把 callback_ 掏空,之后 if (!callback) return false; 就挡住了。所以 event.reply() 调两次只有第一次生效,且第二次不报错——这是 14.10 里"调了两次 event.reply 但渲染进程只收到第一个"那条的根因。


14.7 sendSync 的完整回路

14.7.1 阻塞到底发生在哪一行

渲染侧:

electron_api_ipc_renderer.cc:188-190

	electron::SerializedValue result;
	electron_ipc_remote_->MessageSync(internal, channel, std::move(message), &result);
	return electron::DeserializeV8Value(isolate, result);

[Sync] 的 mojom 方法生成的签名是 bool MessageSync(params..., SerializedValue* result)——同步调用的结果通过 out 参数返回,返回值是"调用是否成功"。

这一行就是阻塞点。 生成的 MessageSync 走 mojo 的同步调用路径:把当前线程注册到 IPC 的同步等待机制上,然后在这个机制里等回复消息。等待期间:

  • 当前线程不能跑任何任务(不是 run loop,是真的阻塞);
  • 但 IPC 层仍在收消息,包括别的同步请求(这就是死锁成环的物理基础);
  • 渲染进程的 GPU、IO、worker 线程不受影响(只有主线程阻塞)。

bool 返回值被丢弃了。所以通道断开时:result 保持默认构造(空 SerializedValue),DeserializeV8Value 对空字节流调 ReadBlinkEnvelope,ReadTag 立刻失败,返回 v8::Null。

结论:sendSync 在通道断开时返回 null,不抛异常、不警告。 这是一个几乎不可能被用户正确处理的行为——正常代码写 const r = ipcRenderer.sendSync('x'),然后 r.foo,得到 TypeError: Cannot read properties of null。

14.7.2 returnValue 是一个读写不对称的属性

void AddReturnValue(v8::Local<v8::Context> context, v8::Local<v8::Object> event) {
	std::ignore = event->SetNativeDataProperty(
	context, Str(JavascriptEnvironment::GetIsolate(), "returnValue"),
	ReturnValueGetter, ReturnValueSetter, v8::Local<v8::Value>(),
	v8::DontEnum);
}

electron_api_ipc_dispatch.cc:157-163

void ReturnValueGetter(v8::Local<v8::Name> name,
					const v8::PropertyCallbackInfo<v8::Value>& info) {
	info.GetReturnValue().SetUndefined();
}
void ReturnValueSetter(v8::Local<v8::Name> name, v8::Local<v8::Value> value,
					const v8::PropertyCallbackInfo<v8::Boolean>& info) {
	v8::Isolate* isolate = info.GetIsolate();
	SendReply(isolate->GetCurrentContext(), info.Holder(), value);
}

读永远是 undefined,写触发发送。 注释直接写明了:

// event.returnValue = x replies to a synchronous message; reads are always
// undefined. Own and non-enumerable.

这不是"写进一个槽、稍后发送",而是赋值即发送。三个后果:

  1. event.returnValue = 1; event.returnValue = 2; 只有 1 到达渲染进程(第二次 SendReply 里 callback_ 已空,静默失败)。
  2. event.returnValue++ 这类写法会先读(undefined)再写(NaN),发出去的是 NaN。
  3. 读回来拿不到自己写的值,所以"先设值再基于它修改"的代码会静默出错。

DontEnum 让 Object.keys(event) 里没有它,{...event} 也不会带上——这对 event 的序列化很重要(14.7.4 会看到 event 有时会被整个传出去)。

14.7.3 同步消息也有 reply()

14.5.2 第四步写了两行独立的 if:

electron_api_ipc_dispatch.cc:605-608

	if (sync)
	AddReturnValue(context, event);
	if (!internal)
	AddReply(context, event);

所以 sendSync 的消息同时有 returnValue 和 reply()。reply() 走的是异步路径(sender.sendToFrame),完全绕过同步回复。这意味着一个 handler 可以:

ipcMain.on('x', (event, arg) => {
	event.reply('x-reply', 'later');   // 异步发一条新消息
	event.returnValue = 'now';         // 同步回复
});

渲染进程的 sendSync 立刻返回 'now',而 'x-reply' 会在之后某个时刻到达 ipcRenderer.on('x-reply')。一条 sendSync 可以变成两条消息,这是文档里没有的行为。

ReplyImpl 的实现还揭示了一件事:

electron_api_ipc_dispatch.cc:182-189

void ReplyImpl(const v8::FunctionCallbackInfo<v8::Value>& info) {
	...
	v8::Local<v8::Value> frame_parts[] = {
	GetProperty(context, event, "processId"),
	GetProperty(context, event, "frameId")};
	v8::LocalVector<v8::Value> argv(isolate);
	argv.reserve(info.Length() + 1);
	argv.push_back(v8::Array::New(isolate, frame_parts, 2));
	for (int i = 0; i < info.Length(); ++i)
	argv.push_back(info[i]);
	std::ignore = CallMethod(context, sender.As<v8::Object>(), "sendToFrame",
						argv.size(), argv.data());
}

event.reply(...) 等价于 event.sender.sendToFrame([processId, frameId], ...)。而 sendToFrame 是 JS 方法(web-contents.ts:37):

WebContents.prototype.sendToFrame = function (frameId, channel, ...args) {
	const frame = getWebFrame(this, frameId);
	if (!frame) return false;
	frame.send(channel, ...args);
	return true;
};

所以一次 event.reply() 的完整路径是:C++ → JS(sendToFrame)→ JS(getWebFrame / webFrameMain.fromId)→ C++(frame.send)→ mojo。跨语言四次,比 webContents.send 多两次。

如果 frame 已经不在了(event.processId / frameId 指向已销毁的 frame),getWebFrame 返回 undefined,sendToFrame 返回 false,reply() 静默失败。这就是"event.reply 有时候没反应"的答案——不是 IPC 坏了,是那个 frame 没了。

14.7.4 三种死锁的构造

sendSync 的死锁不需要写错代码,只需要三条常见配置凑在一起。

构造一:主进程在等渲染进程。 主进程执行 dialog.showMessageBoxSync(同步模态对话框)时,UI 线程进入一个嵌套的 run loop。这个 run loop 会处理 IPC,所以 sendSync 不会死——但它的处理顺序变成"对话框的事件循环决定",可能出现"渲染进程发了两条 sendSync,第二条在对话框关掉之后才被处理"。

构造二:两个渲染进程互等。 主进程 UI 线程在 ipcMain.on('a') 里 await 一个渲染进程的回包(用 invoke 的 callback 或 webContents.send 后的确认),而这个 await 期间又来了另一个渲染进程的 sendSync——那个 sendSync 会插进 await 的等待队列,因为同步 IPC 在嵌套 run loop 里被处理。如果处理它需要主进程那个还没 resolve 的 Promise,死锁。

构造三:渲染进程等自己。 主进程收到 sendSync 后,在 handler 里调 webContents.executeJavaScript 并同步等待结果(Electron 没有同步版 executeJavaScript,但 sendSync 到同一个渲染进程的另一条 channel 可以构造出来)。被调的渲染进程正在 sendSync 阻塞,收不到执行请求——死锁。

第三种是唯一能纯靠应用代码构造出来的,也是最常见的成因:在 handler 里向"发起同步 IPC 的那个渲染进程"再发一条需要它响应的消息。

14.7.5 handleSync 证明"回复可以晚于 handler 返回"

回到那段 11 行代码:

ipc-main-internal-utils.ts:5-10

export const handleSync = function <T extends IPCHandler>(channel: string, handler: T) {
	ipcMainInternal.on(channel, async (event, ...args) => {
	try {
	event.returnValue = [null, await handler(event, ...args)];
	} catch (error) {
	event.returnValue = [error];
	}
	});
};

这是一个 async 函数——它返回一个 Promise,而 Emit 不等这个 Promise。所以:

t0: C++ 调 emit('channel', event, args)
t1: async 函数开始执行,遇到 await,返回 pending Promise
t2: Emit 拿到 undefined(async 函数的返回值不是 true),Message 继续走完
t3: mojo 的 MessageSync handler 返回,**但回复还没发**
t4: handler 的 Promise resolve
t5: event.returnValue = [null, result]  ← 这时才发回复

t3 到 t5 之间,渲染进程的 sendSync 一直阻塞着。 这证明了两件事:

  1. mojo 的同步回复不受"handler 必须同步返回"的约束,可以在任意后续任务里发。
  2. Electron 自己的内部 RPC(rpc-server.ts 里的 handleSync)靠这个性质工作——它的 handler 大多是 async(比如 window.getProcessMemoryInfo())。

代价是:sendSync 没有超时,只有"等到有回复"和"等到通道断开"。 如果那个 async handler 永远不 resolve(比如它自己在等一个渲染进程的回包),渲染进程就永久阻塞。

[error, result] 这个二元组协议也是内部的:ipc-renderer-internal-utils.ts:3-8 里的 invokeSync 是它的消费端。

export function invokeSync<T>(command: string, ...args: any[]): T {
	const [error, result] = ipcRendererInternal.sendSync(command, ...args);
	if (error) {
	throw error;
	} else {
	return result;
	}
}

注意它对 [error, result] 做了解构,如果 sendSync 因为断连返回 null,解构会抛 TypeError: null is not iterable——这就是 14.7.1 里"返回 null"那个行为在内部代码里的表现。Electron 自己也没处理它。

14.8 渲染侧接收:EmitIPCEvent 与它落进的 world

14.8.1 消息落在哪个 world,是算出来的

主进程发来的消息到渲染进程后,第一件事是选一个 context(electron_api_service_impl.cc:208-220):

void ElectronApiServiceImpl::Message(bool internal, const std::string& channel,
									electron::SerializedValue arguments) {
	blink::WebLocalFrame* frame = render_frame()->GetWebFrame();
	if (!frame) return;
	v8::Isolate* isolate = frame->GetAgentGroupScheduler()->Isolate();
	v8::HandleScope handle_scope(isolate);
	v8::Local<v8::Context> context = renderer_client_->GetContext(frame, isolate);
	v8::Context::Scope context_scope(context);
	v8::Local<v8::Value> args = gin::ConvertToV8(isolate, arguments);
	ipc_native::EmitIPCEvent(isolate, context, internal, channel, {}, args);
}

GetContext(renderer_client_base.cc:649-664)是第 12 章那个 world 体系的收口处:

v8::Local<v8::Context> RendererClientBase::GetContext(blink::WebLocalFrame* frame,
													v8::Isolate* isolate) const {
	auto* render_frame = content::RenderFrame::FromWebFrame(frame);
	DCHECK(render_frame);
	if (render_frame) {
	v8::Local<v8::Context> env_context = GetEnvironmentContext(render_frame);
	if (!env_context.IsEmpty())
	return env_context;
	}
	if (render_frame && render_frame->GetBlinkPreferences().context_isolation)
	return frame->GetScriptContextFromWorldId(isolate, WorldIDs::ISOLATED_WORLD_ID);
	else
	return frame->MainWorldScriptContext();
}

三级优先:

  1. GetEnvironmentContext(frame) 非空就用它。 这是 preload 建 Node 环境时用的那个 context——非沙箱路径下,就是 preload 所在的那个 world。
  2. 否则看 context_isolation:真则用隔离世界(999)。
  3. 否则用主世界(0)。

这三个分支决定了消息落进哪个 ipcNative。 而 ipcNative 是每个 context 各一份(14.1.1),所以:

渲染进程形态GetEnvironmentContext消息落在ipcNative 在哪
sandbox: false,preload 在主世界有(主世界)主世界主世界 ✓
sandbox: false,preload 在隔离世界有(999)999999 ✓
sandbox: true空(无 Node 环境)contextIsolation ? 999 : 0同左 ✓

第三种情况值得注意:沙箱渲染进程没有 node::Environment,所以第一级永远落空,靠第二级。这意味着沙箱路径下 ipcRenderer 的可用性完全依赖 context_isolation 与 preload 实际跑在哪个 world 一致——第 12 章讲过 ShouldNotifyClient 的三条规则,其中"已有环境只认环境所在的 world"在沙箱路径下没有环境可认,只能靠偏好。

如果两者不一致,EmitIPCEvent 里的 GetIpcObject 返回空,消息静默丢弃。(:40-57 那段,注释是 "Nothing in this context listens for IPC (no preload script ran here)"。)这是本章第二个"静默失败",也是最难查的一个——因为渲染进程那边一切正常,ipcRenderer.send 工作得很好,只有主进程发过去的消息收不到。单向通、反向不通是它的特征。

14.8.2 EmitIPCEvent 的六个细节

void EmitIPCEvent(v8::Isolate* const isolate, const v8::Local<v8::Context>& context,
				bool internal, const std::string& channel,
				std::vector<v8::Local<v8::Value>> ports, v8::Local<v8::Value> args) {
	TRACE_EVENT0("devtools.timeline", "FunctionCall");
	v8::HandleScope handle_scope(isolate);
	v8::Context::Scope context_scope(context);
	v8::MicrotasksScope script_scope(isolate, context->GetMicrotaskQueue(),
								v8::MicrotasksScope::kRunMicrotasks);
	v8::Local<v8::Object> ipc_native = GetIpcObject(isolate, context);
	if (ipc_native.IsEmpty()) return;
	v8::Local<v8::Value> emitter_value;
	if (!ipc_native->Get(context, gin::StringToSymbol(isolate,
				internal ? "ipcRendererInternal" : "ipcRenderer")).ToLocal(&emitter_value) ||
	!emitter_value->IsObject()) {
	return;
	}
	v8::Local<v8::Object> emitter = emitter_value.As<v8::Object>();
	// Only set up the node::CallbackScope if there's a node environment.
	// Sandboxed renderers don't have a node environment.
	std::optional<node::CallbackScope> callback_scope;
	if (auto* env = node::Environment::GetCurrent(context)) {
	callback_scope.emplace(env, emitter, node::async_context{0, 0});
	}
	// emitter.emit(channel, { sender, ports }, ...args)
	v8::Local<v8::Object> event = v8::Object::New(isolate);
	event->CreateDataProperty(context, gin::StringToSymbol(isolate, "sender"), emitter).Check();
	event->CreateDataProperty(context, gin::StringToSymbol(isolate, "ports"),
							gin::ConvertToV8(isolate, ports)).Check();
	v8::LocalVector<v8::Value> argv(isolate, {event});
	...
	v8::TryCatch try_catch(isolate);
	try_catch.SetVerbose(true);  // report listener exceptions to the console
	gin_helper::EmitEvent(isolate, emitter, gin::StringToV8(isolate, channel), argv);
}

六件事,每件都有对应的坑。

一,TRACE_EVENT0("devtools.timeline", "FunctionCall")。 用 Chromium 的 timeline 分类而不是 Electron 自己的 "electron" 分类(主进程侧用的是 TRACE_EVENT1("electron", "IpcDispatcher::Message", ...))。结果是在 DevTools 的 Performance 面板里,渲染侧的 IPC 投递会显示成一个 FunctionCall,和普通 JS 调用混在一起——这是有意的:对渲染进程来说,IPC 投递本来就是一个函数调用,它应该和页面脚本共享同一条时间轴。

二,MicrotasksScope::kRunMicrotasks。作用域析构时把微任务队列跑干净。所以 listener 里 Promise.resolve().then(...) 的回调会在 EmitIPCEvent 返回之前执行完。这与主进程侧 DispatchScope 的 kRunMicrotasks 对称——两侧都是"一次派发 = 一次微任务检查点"。

三,node::CallbackScope 是条件创建的。

electron_ipc_native.cc:68-70

	std::optional<node::CallbackScope> callback_scope;
	if (auto* env = node::Environment::GetCurrent(context)) {
	callback_scope.emplace(env, emitter, node::async_context{0, 0});
	}

std::optional + emplace 是"可能不存在的作用域"的标准写法。注释说明了条件:沙箱渲染进程没有 Node 环境。

CallbackScope 的作用是给这次 JS 执行一个 async_context({0, 0} 表示"无异步上下文"),使得 process.nextTick、setImmediate 里排的任务能正确归到这个异步链上。没有它,Node 的 async_hooks 会把这次执行归到"上一个上下文"——在沙箱路径下反正是空的,所以干脆不建。

四,event 是一个普通对象,只有两个属性。

	event->CreateDataProperty(context, "sender", emitter)   // ← 是 ipcRenderer,不是 WebContents
	event->CreateDataProperty(context, "ports", ports)

这里有一处主/渲染两侧的语义反转:

位置event.sender 是什么
主进程的 IpcMainEventWebContents(发送方的页面)
渲染进程的 IpcRendererEventipcRenderer(就是 emitter 自己)

渲染侧的 sender 永远是同一个对象(那个 context 的 ipcRenderer),不携带任何来源信息。这不是 bug,是设计:渲染进程只有一个可能的来源(主进程),"谁发的"没有意义;而主进程有多个来源,sender 才需要指向具体那个。

五,没有 senderFrame。 主进程的 event 有 senderFrame / processId / frameId / frameTreeNodeId,渲染侧的 event 只有 sender 和 ports。所以渲染进程没有任何办法从 event 上知道自己这个 frame 的身份——要拿 frame 信息只能 require('electron').webFrame.routingId(沙箱下不行)。

六,try_catch.SetVerbose(true)。

electron_ipc_native.cc:95-96

	v8::TryCatch try_catch(isolate);
	try_catch.SetVerbose(true);  // report listener exceptions to the console

SetVerbose(true) 让 try_catch 在捕获异常时顺手打一条 console 错误。所以渲染进程里 ipcRenderer.on('x', () => { throw new Error('boom') }) 会在 DevTools 控制台看到一条错误,而页面不会崩溃(异常被 try_catch 吃掉)。这是"IPC 回调里的异常被吞掉"的准确机制——不是没人管,是打到 console 了,但调用栈是 IPC 的,跟你的业务代码看起来没关系。

14.8.3 postMessage 在渲染侧的额外一步

void ElectronApiServiceImpl::ReceivePostMessage(const std::string& channel,
												blink::TransferableMessage message) {
	...
	v8::Local<v8::Value> message_value = DeserializeV8Value(isolate, message);
	std::vector<v8::Local<v8::Value>> ports;
	for (auto& port : message.ports) {
	ports.emplace_back(
		blink::WebMessagePortConverter::EntangleAndInjectMessagePortChannel(
			isolate, context, port));
	}
	std::vector<v8::Local<v8::Value>> args = {message_value};
	ipc_native::EmitIPCEvent(isolate, context, false, channel, ports, gin::ConvertToV8(isolate, args));
}

两处差异:

一,端口要先注入 context。 EntangleAndInjectMessagePortChannel(isolate, context, port) 把 Blink 的 MessagePortChannel 变成一个真正的 JS MessagePort 对象,并注入到指定 context——所以渲染进程拿到的端口是那个 world 里的原生 MessagePort,可以用 port.onmessage、port.postMessage、port.start(),和 Web 平台的完全一致。

二,args 被包成一个单元素数组。 {message_value} 传给 EmitIPCEvent,它会摊平成 emit(channel, event, message)。所以渲染侧的 handler 是 (event, message),和主进程侧对称。

注意 internal 传的是 false:ipcRenderer.postMessage 只能发到非 internal 通道(14.1.2 里 internal 版根本没有 postMessage 方法)。

端口的所有权在这里完成第二次转移:渲染进程 A 的 MessagePort → 主进程的 MessagePortMain → 渲染进程 B 的 MessagePort。每一步都是一次 disentangle + 一次 entangle,中间那段主进程侧的对象由 message_port.cc:252 的 Pin()/Unpin() 管着(有未读消息时 pin 住,避免被 GC 掉)。


14.9 七条路的完整拓扑

把前面所有碎片拼起来,七个方向的完整跳数:

#入口跳数中间对象到达的 emitter
1ipcRenderer.send7SerializedValuewebContents → frame.ipc → webContents.ipc → ipcMain
2ipcRenderer.sendSync7 + 阻塞SerializedValue + ReplyChannel同上,另加 returnValue
3ipcRenderer.invoke7 + 回复SerializedValue ×2 + PendingInvokeReplyframe.ipc → webContents.ipc → ipcMain
4ipcRenderer.postMessage7TransferableMessageframe.ipc → webContents.ipc → ipcMain
5ipcRenderer.sendToHost7 + 2SerializedValue ×2guest WebContents(-ipc-message-host)
6webContents.send5SerializedValue渲染进程的 ipcRenderer
7webContents.postMessage5TransferableMessage渲染进程的 ipcRenderer(带 ports)

三处不对称值得指出:

第 3 条少了 webContents 'ipc-message' 那一发。 invoke 的 targets 直接从 CollectFrameTargets 开始(ipc_dispatch.cc:684-687),没有像 Message 那样先 emit 到 WebContents。所以 webContents.on('ipc-message') 收不到 invoke——这大概是本章最容易踩的一个坑,因为 ipcMain.handle 和 ipcMain.on 在文档里是并列的两节,而它们的派发路径并不并列。

第 5 条是唯一一条要过两次 IPC 的。 第一次到主进程(-ipc-message-host),第二次由 guest-view-manager.ts 用 webContents.send 发到宿主页面。所以 sendToHost 的延迟是单程的两倍,而且在宿主页面卡顿时会排队。

第 6、7 条只有 5 跳,因为它们不进派发——EmitIPCEvent 直接 emit,没有"多个 emitter 依次过"的环节。主进程发一条消息最多落到一个 emitter(那个 context 的 ipcRenderer),渲染进程发一条消息可能落到四个。

反向的确认机制

七个方向里只有 invoke 有确认。webContents.send 没有 ack,ipcRenderer.send 也没有。所以"消息发出去了但对方没处理"这件事,在六个方向上都是不可检测的。

能做确认的只有三种土办法:

  1. 用 invoke 代替 send(要求对方有 handler)。
  2. 对端收到后主动回一条(自己实现 ack,注意 14.2.6 的顺序表)。
  3. 监听对端的生命周期事件(render-process-gone、destroyed)来间接判断。

第 3 条最容易出错,因为 webContents.send 在 frame 还没 IsRenderFrameLive() 时会把 receiver 存起来等下一次(14.2.5),消息本身已经丢了——而 render-process-gone 只在对端真的崩了时才触发。


14.10 失败模式手册

按症状排,每一条都能对应到前面某一段代码。

症状根因层
渲染进程 send 之后主进程完全没反应,无报错子 frame 且未开 nodeIntegrationInSubFrames,ElectronApiIPC 没注册,remote 已断开但 operator bool 仍为真传输层(14.2.3)
send 抛 IPC method called after context was releasedremote 是默认构造(context 已释放),不是"未注册"传输层(14.2.3)
invoke 永远 pending,从不 resolve 也不 rejecthandler 返回了永不 settle 的 Promise;或 IsReady() 为假时消息被丢(ReplyChannel 要等 GC 才补发)派发(14.4.3、14.6.3)
invoke 报 No handler registered,但 ipcMain.on 明明注册了on 和 handle 是两个 Map,on 的监听器不参与 invoke 查找派发(14.6.3)
ipcMain.handle 抛"已经在注册"同一 channel 注册了两次;handleOnce 的包装在调用前就删了自己JS 层(14.1.3)
webContents.on('ipc-message') 收不到 invokeInvoke 不 emit 到 WebContents派发(14.9)
webContents.on('ipc-message') 收不到 postMessagePostMessage 也不 emit 到 WebContents派发(14.5.6)
主进程 send 之后渲染进程 ipcRenderer 收不到,但发出去的消息能收到GetContext 选中的 world 里没有 ipcNative(沙箱 + contextIsolation 不一致)渲染接收(14.8.1)
event.senderFrame 为 null,读 .url 抛 TypeErrorframe 已导航或销毁;senderFrame 每次读都重新 FromID事件对象(14.4.4)
event.reply 调了没反应frame 已不在;getWebFrame 返回 undefined,sendToFrame 静默返回 false派发(14.7.3)
event.reply 调两次,只收到第一个ReplyChannel::SendReplyImpl 第二次 callback 已空,返回 false回复通道(14.6.6)
主进程 send 一个含函数的对象,没有任何异常,消息丢了ReadIPCSendArguments 用 TryCatch 吃掉异常,只打 warning序列化(14.3.5)
invoke 的 handler 返回函数,渲染进程收到 reject回复序列化失败,ReplyWithResult 转成 {error}序列化(14.3.5)
sendSync 返回 null通道断开,mojo 的 bool 返回值被丢弃,空字节流反序列化成 null同步(14.7.1)
sendSync 卡死几秒主进程 handler 里 await 了慢操作;同步回复可以晚于 handler 返回同步(14.7.5)
service worker 里 send,ipcMain 收不到worker 的消息只到 ServiceWorkerMain.ipc,不扇出到 ipcMain派发(14.5.9)
send 一个 50 MB 的 Buffer,进程卡顿序列化走共享内存 + 接收端(非渲染进程)再拷一份序列化(14.3.4)
主进程里 ipcMain.on 的回调抛异常,弹出 "A JavaScript error occurred in the main process"Emit 返回空,异常沿 isolate 上抛到 uncaughtException派发(14.5.5)
DevTools 里只看到 FunctionCall,不知道是哪条 IPC渲染侧 trace 用了 devtools.timeline 分类,名字固定渲染接收(14.8.2)

十九条里,只有三条会报错(注册重复、序列化抛异常、No handler registered),其余十六条全是静默失败或晚到的失败。这个比例本身就是本章的论点:IPC 的难点不是发送,是在没有任何反馈的情况下判断消息走到哪一站停下的。


14.11 性能账本

不测时间,只数操作——因为操作次数是可验证的,毫秒数依赖机器。

一次 send 的固定成本

环节分配跨语言说明
渲染侧方法调用1 个数组(Rest)1 次(JS→C++)Rest(info, 1) 造参数数组
序列化1 个 BigBuffer(小值时是内联)0V8 的 WriteValue
mojo 发送1 条消息0associated channel
主进程接收1 个 IpcMainEvent0模板实例化,不是逐属性 Set
反序列化1 组 JS 对象1 次(C++→JS)DeserializeV8Value
派发1 个 argv + 1 个 wc_argv4 次 emit 调用每个 emitter 一次 GetProperty("emit")
监听器0N 次(用户回调)—

"4 次 emit 调用"是这条路径上最大的一笔固定开销,因为它不随消息大小变化,只随 emitter 数量变化。一个只在 ipcMain 上监听的 channel,仍然要经过 webContents、frame.ipc、webContents.ipc 三次 emit(各自查一次监听器表,都是空的)。

这就是为什么 NotifySessionObservers 要绕过 emit 直接读 _events(14.5.8)——它把那三次"空 emit"里最不必要的一次省掉了。如果哪天要做 IPC 的极致优化,方向是把四个 emitter 的监听器表缓存起来,无事可做时直接跳过 emit 调用,而不是改序列化。

大消息的三条阈值

值的大小走什么拷贝次数
小(内联)mojo 消息体内的字节1(序列化时写入)
大于 kMaxInlineBytes共享内存1(序列化时直接写进共享内存)
同上,但接收方是主进程共享内存 + 全量拷贝2(多一次 HeapArray::CopiedFrom)

第三行是 14.3.4 那条 TOCTOU 防御的代价。渲染进程 → 主进程的每一条大消息都多一次全量拷贝,而主进程 → 渲染进程不用。方向不对称,成本也不对称。

四条回复路径的延迟

路径渲染进程观察到回复的时机
invoke + 同步返回当前微任务之后(EnqueueMicrotask)
invoke + async handlerhandler 的 Promise settle 之后
invoke + 永不 resolve等到 ReplyChannel 被 GC,PostTask 补发
sendSync阻塞等待,没有超时

第二行意味着主进程的一个 await 会让渲染进程的 Promise 多等至少一个事件循环。如果 handler 里 await 了三次,回复就晚三个 tick——这些 tick 在渲染进程侧全部表现为"IPC 有点慢"。

Str() intern 表的收益

派发一条消息要查的属性名(按最坏情况数):emit、ipc(×2 目标)、sender、processId、frameId(ReplyImpl 里)、_events、_invokeHandlers。最坏十几次。

没有 intern 时,每次 gin::StringToSymbol 都要:分配一个 v8::String、算哈希、插入隔离的字符串表。有 intern 时是一次 flat_hash_map 查找 + 一次 Eternal::Get。

这是纯收益,没有权衡——代价只是那张表会活到进程结束(十几个条目,几百字节)。


14.12 练习题

14.1(入门) 在 ipcMain.on('x') 和 ipcMain.handle('x') 上各注册一个,渲染进程分别 send 和 invoke。确认两个 handler 互不干扰,并解释为什么 handle 第二次注册会抛而 on 不会(14.1.3、14.6.3)。

14.2(入门) 用 webContents.on('ipc-message')、frame.ipc.on、webContents.ipc.on、ipcMain.on 四处同时监听同一个 channel,打印顺序。然后换成 ipcRenderer.invoke 再试一次,解释少了哪一个(14.5.3、14.9)。

14.3(进阶) 构造 event.senderFrame 为 null:在 ipcMain.on 里 await new Promise(r => setTimeout(r, 100)),期间用 webContents.loadURL 导航走,之后再读 event.senderFrame.url。观察那条 "Frame property was accessed after it navigated or was destroyed" 警告(14.4.4)。

14.4(进阶) 写一个 ipcMain.handle 返回 Promise 子类的实例,确认它走的是 Resolver 慢路径而不是 kFulfilled 快路径。改 Promise.prototype.constructor 再试一次,观察行为是否仍然正确(14.6.3)。

14.5(进阶) 复现"渲染进程能发、主进程发不过去":设 sandbox: true 且 contextIsolation: false,preload 里 ipcRenderer.send 正常,但主进程 webContents.send 到不了。用 --js-flags 或断点确认 GetContext 选中的 world 与 ipcNative 所在的 world 不同(14.8.1)。

14.6(深入) 让 ipcMain.handle 返回一个含函数的对象,确认渲染进程拿到的是 reject 而不是 resolve 成 {result: undefined}。然后读 ReplyChannel::SendReplyImpl 里关于"序列化可能重入"的注释,构造一个重入场景(在返回值对象的 getter 里调 event.reply())并解释为什么要查第二次 callback(14.3.5、14.6.6)。

14.7(挑战) 实现一个带超时的 sendSync:在渲染侧用 Promise.race 包不住它(它是同步的),只能改 ipcRenderer 的 native 实现或在主进程侧保证响应。说明为什么"在 JS 层加超时"对 sendSync 不可能(14.7.1)。


14.13 第 15 章预告:contextBridge 与安全边界

本章反复出现一个前提:渲染进程里的 ipcRenderer 是一个有完整权限的对象。它不检查 channel,不检查参数,不检查调用者是谁。一段被 XSS 注入的脚本只要能摸到 ipcRenderer,就能调主进程的任何 handler。

第 12 章讲 contextIsolation 时提到两个 world 各有自己的 v8::Context,第 14 章讲 IPC 时又用到"消息落进哪个 world"。把这两件事接起来的那个东西叫 contextBridge,它做的事情本质上是在两个 world 之间搭一座只有函数能过的桥:值被复制、函数被代理、对象被冻结。

一句话预告第 15 章的立论:contextBridge 不是一个"安全的复制函数",它是一套在两个 V8 context 之间手工实现的 RPC——每次 exposeInMainWorld 暴露的每个函数,调用时都要跨一次 world 边界,参数要深拷贝、返回值要深拷贝、异常要跨边界重建,而这套 RPC 的边界条件(哪些类型能过、代理对象的生命周期、跨 world 的 Promise 怎么转)决定了"安全"到底是真安全还是看起来安全。

14.14 本章源码落点索引

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

  • API 文档与类型:ipc-main-service-worker.md:5 ipc-main-service-worker-invoke-event.md:3 ipc-main-service-worker-event.md:3 service-workers.md:5 ipc-main.md:2 ipc-renderer.md:2 ipc-main-invoke-event.md:3 service-worker-info.md:3
  •  ipc-main-event.md:3 ipc-renderer-event.md:3 docs/api/local-ai-handler.md:5 message-channel-main.md:12 session.md:5
  • 浏览器进程 C++ 层:electron_api_service_worker_main.h:27 electron_api_ipc_dispatch.h:15 electron_api_service_worker_context.cc:30 electron_api_service_worker_context.h:22 electron_api_ipc_handler_impl.h:18 electron_api_sw_ipc_handler_impl.h:18 electron_api_event_emitter.cc:17 electron_api_event_emitter.h:10
  •  electron_api_session.cc:136
  • shell 其余实现:service_worker_converter.cc:12 service_worker_converter.h:14
  • 渲染进程 C++ 层:service_worker_data.cc:16 service_worker_data.h:24
  • 其他相关位置:api-service-worker-main.spec.ts:13
  • JS 门面与运行时:ipc-renderer.ts:1 session.ts:6