《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:100 | 128 | ElectronApiIPC / ElectronRenderer / ElectronFrame 三个接口 |
| 序列化 | common/v8_util.cc | 401 | V8 → 字节 / 字节 → V8,含 Blink 信封 |
| 序列化载体 | common/serialized_value.h / .cc | 48 / 31 | 一块 BigBuffer 加一个长度 |
| 渲染侧发送 | electron_api_ipc_renderer.cc | 533 | ipcRenderer 与 ipcRendererInternal 两个对象 |
| 渲染侧接收 | electron_ipc_native.cc | 101 | 把字节变成 emit(channel, event, ...args) |
| 主进程接收 | electron_api_ipc_handler_impl.cc | 196 | ElectronApiIPC 的 frame 版实现 |
| 主进程接收(SW) | electron_api_sw_ipc_handler_impl.cc | 229 | ElectronApiIPC 的 service worker 版实现 |
| 派发 | electron_api_ipc_dispatch.cc / .h | 909 / 83 | 把消息送给四个 emitter,纯 C++ 无 JS 中转 |
| 事件对象 | electron_api_ipc_event.cc:175 / .h | 380 / 131 | event 上的 sender / senderFrame / returnValue |
| 回复通道 | reply_channel.cc / .h | 101 / 71 | 把 Promise 的 settle 变成一条 mojo 回复 |
| 反向发送 | electron_api_web_frame_main.cc | 991 | frame.send / frame.postMessage / frame.executeJavaScript |
| 端口 | message_port.cc / .h | 368 / 104 | MessagePortMain 与 disentangle |
JS 侧薄得几乎不存在,这是这一代实现的一个显著特征:
| 文件 | 行数 | 内容 |
|---|---|---|
ipc-dispatch.ts:1-7 | 7 | 把 ipcMain 和 ipcMainInternal 交给 C++ |
ipc-main-impl.ts:5 | 35 | IpcMainImpl:handle / handleOnce / _invokeHandlers |
ipc-main-internal-utils.ts:5 | 11 | handleSync:把 async handler 的结果塞进 returnValue |
ipc-renderer-internal.ts | 1 | process._linkedBinding('electron_renderer_ipc').ipcRendererInternal |
ipc-renderer-internal-utils.ts:3 | 11 | invokeSync:拆 [error, result] 二元组 |
ipc-messages.ts | 14 | 九个内部通道名 |
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 方法 | 有回复 | 阻塞调用者 |
|---|---|---|---|---|---|
| 1 | ipcRenderer.send | 渲染 → 主 | ElectronApiIPC::Message | 无 | 否 |
| 2 | ipcRenderer.sendSync | 渲染 → 主 | ElectronApiIPC::MessageSync([Sync]) | 有 | 是 |
| 3 | ipcRenderer.invoke | 渲染 → 主 | ElectronApiIPC::Invoke | 有(Promise) | 否 |
| 4 | ipcRenderer.postMessage | 渲染 → 主 | ElectronApiIPC::ReceivePostMessage | 无 | 否 |
| 5 | ipcRenderer.sendToHost | 渲染 → 宿主 | ElectronApiIPC::MessageHost | 无 | 否 |
| 6 | webContents.send / frame.send | 主 → 渲染 | ElectronRenderer::Message | 无 | 否 |
| 7 | webContents.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:
| 实例 | 创建位置 | 谁往里注册 | 收到什么 |
|---|---|---|---|
ipcMain | ipc-main.ts:3-5 | 应用代码 | 所有非 internal 的 frame IPC |
ipcMainInternal | ipc-main-internal.ts:3 | Electron 内部 | internal 通道 + 部分内部事件 |
webContents.ipc | web-contents.ts:209 | 应用代码 | 只属于这个 WebContents 的消息 |
frame.ipc | web-frame-main.ts:5 | 应用代码 | 只属于这个 frame 的消息 |
worker.ipc | service-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());
}
这段代码有四个隐含约束,每一个都能被一次无害的重构打破,而且打破后不报错:
- 字段名必须正好是
_invokeHandlers。 改个名字,C++ 就找不到,invoke全部变成 "No handler registered"。 - 必须是
Map而不是普通对象。IsMap()检查不过就continue,同样静默。 - 键必须是原始字符串。
Map::Get用的是 SameValueZero,'foo'和new String('foo')不是同一个键——而handle的method参数在 TS 里声明为string,运行时不做校验,传String对象就再也取不出来。 - 值必须是函数。
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();
}
推理链条是这样的:
- 大消息(超过内联阈值)通过共享内存传递,长度由
size_记录。 - 共享内存是双方都能映射的。发送方在自己那一侧仍然持有可写映射。
- 接收方在解析这块内存。解析不是一次 memcpy,是逐字节读、按 tag 分支、分配对象——耗时与大小成正比。
- 如果发送方在这个窗口里改了自己那一侧的数据,接收方就会解析出一份"签名与实际内容不一致"的结构。V8 的
ValueDeserializer对畸形输入的防御是有的,但那是针对"意外损坏",不是针对"主动构造"。 - 所以:只要发送方不可信,就必须先拷贝再解析。
谁可信?主进程发给渲染进程时,发送方是浏览器(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 构建里表现为连接被重置)。所以三条失败路径都必须先把错误回过去,再返回空。
三道检查分别对应三种"世界已经变了":
session为空:api::Session::FromBrowserContext返回的是gin::WeakCell<api::Session>*,弱引用意味着主进程侧的session对象可能已经被 GC。这不是理论问题:如果应用代码从来没有强引用过session.defaultSession,它就可能在某次 GC 后被回收,之后这个 WebContents 的 IPC 全部落在这条错误上。这是"JS 对象生命周期影响 C++ 服务可用性"的又一个例子(第 11 章的三份记账是同一个主题)。api::WebContents为空:content::WebContents还在,但它的 JS wrapper 已经被回收。第 11 章讲过WebContents是CleanedUpAtExit+Pinnable,wrapper 可以被回收而 C++ 对象还活着。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。这条路的成本结构很糟:
- 消息从 mojo 回调进入 C++,C++ 调一个 JS 函数(trampoline),进入 JS。
- JS 里做 3–4 次
emit,每次都要走 EventEmitter 的属性查找与监听器数组遍历。 - 每次
emit都是一个独立的 JS 调用帧,Node 的CallbackScope语义要靠手工维护。 - 参数数组在 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++ 里的对应物 | 位置 |
|---|---|---|
闭包捕获 ipcMain | Registry 里的 v8::Global<v8::Object> | :36-45 |
| 字符串字面量常量 | v8::Eternal<v8::String> intern 表 | :48-61 |
| 一次函数调用一个 CallbackScope | DispatchScope(三个 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.returnValue | event.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
这个顺序有两个可观察后果:
ipcMain永远最后。所以一个应用的全局 handler 看到的永远是"局部 handler 已经处理过"之后的状态——包括局部 handler 对event做的修改(preventDefault、ports)。- 局部注册不会"接管"全局的那一份。在
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 调用都不发生。
三个细节:
_events是 Node 的内部字段,不在公开 API 里。它的形状在 Node 的版本之间变过(Object.create(null)的普通对象 ↔Map)。这里只做了IsObject()和HasOwnProperty,两者对两种形状都成立——但如果哪天 Node 换成Map存单监听器,HasOwnProperty就会永远为假,钩子静默失效。HasOwnProperty的第二个参数(v8::Just(false)的等价物)隐含在FromMaybe(false)里:属性查找抛异常时当作"没有监听器"。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 版的结构对称,差异集中在三处:
-
sender 变成了 session。 没有
WebContents,没有senderFrame,event是IpcMainServiceWorkerEvent(带session/versionId/processId/serviceWorker四个属性)。 -
目标只有一个:
ipcMainInternal(internal 时)或 worker 自己的ServiceWorkerMain.ipc。CollectServiceWorkerTargets只往targets里推 worker 的ipc,不推全局ipcMain。看
CollectServiceWorkerTargets(:551-566):它只 push worker 的ipc。所以是的——service worker 的消息默认只到ServiceWorkerMain.ipc,不到ipcMain。这与 frame 的行为不同(frame 的消息一定会到ipcMain)。 -
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
Errorobject 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 函数)且已 fulfilled | kFulfilled 分支 | 下一个微任务 |
原生 Promise 且 pending / rejected | ReplyWhenSettled | 它 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' | RunInvokeHandler | FindInvokeHandler 没找到 |
Error invoking remote method 'x': <原文> | UnwrapInvokeResult | handler 抛异常 / 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);
这段"把任意值变成字符串"的逻辑有四个分支,每个都有具体原因:
- 对象 →
error.toString(),不用抽象ToString。注释说 "unlike abstract ToString also works for a Symbol"——Symbol('x')的抽象ToString会抛TypeError,而Symbol.prototype.toString返回'Symbol(x)'。 - 非对象 →
ToDetailString(),它不会调用户代码(不像ToString会触发valueOf/toString)。 toString抛异常或返回非字符串 →"Error"。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.
这不是"写进一个槽、稍后发送",而是赋值即发送。三个后果:
event.returnValue = 1; event.returnValue = 2;只有1到达渲染进程(第二次SendReply里callback_已空,静默失败)。event.returnValue++这类写法会先读(undefined)再写(NaN),发出去的是NaN。- 读回来拿不到自己写的值,所以"先设值再基于它修改"的代码会静默出错。
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 一直阻塞着。 这证明了两件事:
- mojo 的同步回复不受"handler 必须同步返回"的约束,可以在任意后续任务里发。
- 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();
}
三级优先:
GetEnvironmentContext(frame)非空就用它。 这是 preload 建 Node 环境时用的那个 context——非沙箱路径下,就是 preload 所在的那个 world。- 否则看
context_isolation:真则用隔离世界(999)。 - 否则用主世界(0)。
这三个分支决定了消息落进哪个 ipcNative。 而 ipcNative 是每个 context 各一份(14.1.1),所以:
| 渲染进程形态 | GetEnvironmentContext | 消息落在 | ipcNative 在哪 |
|---|---|---|---|
sandbox: false,preload 在主世界 | 有(主世界) | 主世界 | 主世界 ✓ |
sandbox: false,preload 在隔离世界 | 有(999) | 999 | 999 ✓ |
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 是什么 |
|---|---|
主进程的 IpcMainEvent | WebContents(发送方的页面) |
渲染进程的 IpcRendererEvent | ipcRenderer(就是 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 |
|---|---|---|---|---|
| 1 | ipcRenderer.send | 7 | SerializedValue | webContents → frame.ipc → webContents.ipc → ipcMain |
| 2 | ipcRenderer.sendSync | 7 + 阻塞 | SerializedValue + ReplyChannel | 同上,另加 returnValue |
| 3 | ipcRenderer.invoke | 7 + 回复 | SerializedValue ×2 + PendingInvokeReply | frame.ipc → webContents.ipc → ipcMain |
| 4 | ipcRenderer.postMessage | 7 | TransferableMessage | frame.ipc → webContents.ipc → ipcMain |
| 5 | ipcRenderer.sendToHost | 7 + 2 | SerializedValue ×2 | guest WebContents(-ipc-message-host) |
| 6 | webContents.send | 5 | SerializedValue | 渲染进程的 ipcRenderer |
| 7 | webContents.postMessage | 5 | TransferableMessage | 渲染进程的 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 也没有。所以"消息发出去了但对方没处理"这件事,在六个方向上都是不可检测的。
能做确认的只有三种土办法:
- 用
invoke代替send(要求对方有 handler)。 - 对端收到后主动回一条(自己实现 ack,注意 14.2.6 的顺序表)。
- 监听对端的生命周期事件(
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 released | remote 是默认构造(context 已释放),不是"未注册" | 传输层(14.2.3) |
invoke 永远 pending,从不 resolve 也不 reject | handler 返回了永不 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') 收不到 invoke | Invoke 不 emit 到 WebContents | 派发(14.9) |
webContents.on('ipc-message') 收不到 postMessage | PostMessage 也不 emit 到 WebContents | 派发(14.5.6) |
主进程 send 之后渲染进程 ipcRenderer 收不到,但发出去的消息能收到 | GetContext 选中的 world 里没有 ipcNative(沙箱 + contextIsolation 不一致) | 渲染接收(14.8.1) |
event.senderFrame 为 null,读 .url 抛 TypeError | frame 已导航或销毁;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(小值时是内联) | 0 | V8 的 WriteValue |
| mojo 发送 | 1 条消息 | 0 | associated channel |
| 主进程接收 | 1 个 IpcMainEvent | 0 | 模板实例化,不是逐属性 Set |
| 反序列化 | 1 组 JS 对象 | 1 次(C++→JS) | DeserializeV8Value |
| 派发 | 1 个 argv + 1 个 wc_argv | 4 次 emit 调用 | 每个 emitter 一次 GetProperty("emit") |
| 监听器 | 0 | N 次(用户回调) | — |
"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 handler | handler 的 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