《Electron 45.2.3 内核解剖》第 17 章 网络栈与 Session:一次请求的六道关口

3 阅读1小时+

《Electron 45.2.3 内核解剖》第 17 章 网络栈与 Session:一次请求的六道关口

第 16 章讲的是"没有 Blink 的四种进程"。这一章换一个方向:这些进程都要联网。 而联网这件事在 Electron 里被改造得比任何一块都深——因为它既要复用 Chromium 完整的网络栈(HTTP/2、QUIC、代理、缓存、证书、CORS、cookie 分区),又要在上面开六个口子,让 JS 能看见、能改、能拦、能伪造。

先给一个结论,后面所有细节都在解释它:Electron 没有自己的网络栈。 所有请求最终都进入 Chromium 的 network service 进程,由它完成 DNS、连接、TLS、HTTP 解析、缓存、cookie。Electron 做的事情是在"调用方"和"network service"之间插入自己的一层 URLLoaderFactory,决定这个请求要不要先去主进程走一趟 JS。

17.0 先把"六道关口"数清楚

一次请求在 Electron 里可能经过的东西,可以用一张表列完。这张表的每一行,都对应本章的一节。

入口谁创建 URLLoader会经过 webRequest 吗会经过 protocol handler 吗
渲染进程 subresource(<img>、fetch、XHR)renderer 的 per-scheme factory bundle → gate → ProxyingURLLoaderFactory有监听器才走拦截过的 scheme 才走
导航(loadURL、点链接)WillCreateURLLoaderFactory(type = kNavigation,不套 gate)有监听器才走走 CreateNonNetworkNavigationURLLoaderFactory
net.request() / net.fetch()SimpleURLLoaderWrapper → ElectronBrowserContext::GetURLLoaderFactory()走(frame_host 为 null,仍进 proxying)走(GetURLLoaderFactoryForURL 先查注册表)
protocol.handle() 里再 net.fetch()同上,但可带 bypassCustomProtocolHandlers走可选跳过
utility process 里的 netURLLoaderBundle(browser 侧推下去的工厂)走(在 browser 进程里)走
protocol.registerSource() 的静态目录ProtocolSourceURLLoaderFactory(IO 线程)不走自己就是 handler

六个入口里有五个最终落到 ProxyingURLLoaderFactory。它是本章的主角——一个 1003 行的状态机,把 Chromium 的 URLLoader 协议翻译成 Electron 的 webRequest 事件。

在往下走之前,先把三个容易混的名字钉住:

  • NetworkContext:network service 里的一块"网络身份",持有 cookie store、HTTP cache、proxy 配置、SSL 配置、DNS 解析器。一个 session 一个。
  • URLLoaderFactory:创建 URLLoader 的工厂。可以级联——A 工厂把请求转给 B 工厂,中间可以改、可以拦、可以伪造。Electron 的整个改造都建立在"工厂可以套工厂"这一点上。
  • URLLoader:单个请求。有 FollowRedirect、SetPriority,客户端侧对应 URLLoaderClient(OnReceiveResponse、OnReceiveRedirect、OnComplete)。

17.1 Session:一个"网络人格"的 JS 门面

17.1.1 Session 不是 BrowserContext

最容易搞错的一件事:session 不是一个独立的网络对象,它是 ElectronBrowserContext 的 JS 包装。

electron_api_session.cc:558 的构造函数只做五件事:

Session::Session(v8::Isolate* isolate, ElectronBrowserContext* browser_context)
	: isolate_(isolate),
	network_emulation_token_(base::UnguessableToken::Create()),
	network_emulation_client_id_(base::UnguessableToken::Create()),
	browser_context_{browser_context} {
	gin::PerIsolateData* data = gin::PerIsolateData::From(isolate);
	data->AddDisposeObserver(this);
	browser_context->GetDownloadManager()->AddObserver(this);
	SessionPreferences::CreateForBrowserContext(browser_context);
	protocol_ = Protocol::Create(isolate, browser_context->protocol_registry());
	browser_context->SetUserData(
	kElectronApiSessionKey,
	std::make_unique<UserDataLink>(...));
}

顺序有讲究:

  1. AddDisposeObserver(this)——注册到 isolate 的销毁观察者列表,isolate 要死时会回调 OnBeforeMicrotasksRunnerDispose(:1959),那里才真正断开与 browser_context_ 的关系。也就是说Session 的生命周期比 BrowserContext 长,它必须能感知 isolate 的死亡。
  2. 观察 DownloadManager——session.on('will-download') 就是从这来的。Session 顺便当了下载事件的转发器。
  3. SessionPreferences::CreateForBrowserContext——把 session.setPreloads() 那套 per-session 配置挂到 BrowserContext 的 user data 上(第 12 章讲过 preload 的五种来源)。
  4. Protocol::Create(isolate, browser_context->protocol_registry())——protocol 对象不是全局的,是每个 session 一个,但底层注册表属于 BrowserContext。所以 session.defaultSession.protocol 和 session.fromPartition('x').protocol 是两个 JS 对象、两张注册表。
  5. SetUserData(kElectronApiSessionKey, UserDataLink(...))——反向索引:给定 BrowserContext 能找到 Session。

第 5 步的 UserDataLink 里存的是 cppgc::WeakPersistent<gin::WeakCell<Session>>,所以 FromBrowserContext(:1724)要做两次空检查:

electron_api_session.cc:1724-1730

gin::WeakCell<Session>* Session::FromBrowserContext(
	content::BrowserContext* context) {
	auto* data =
	static_cast<UserDataLink*>(context->GetUserData(kElectronApiSessionKey));
	if (data && data->session)
	return data->session.Get();
	return nullptr;
}

data 为空 = 这个 context 从没被 JS 碰过;data->session 为空 = Session 已经被 GC/销毁。两种情况都必须返回 null,否则调用方会拿到野指针。

17.1.2 分区名怎么变成一个目录

session.fromPartition(partition) 是 Electron 里最常被误用的 API 之一。它的三种形态在 FromPartition(:1770)里一眼看完:

electron_api_session.cc:1774-1780

	if (partition.empty()) {
	browser_context = ElectronBrowserContext::GetDefaultBrowserContext(std::move(options));
	} else if (partition.starts_with(kPersistPrefix)) {
	std::string name = partition.substr(8);
	browser_context = ElectronBrowserContext::From(name, false, std::move(options));
	} else {
	browser_context = ElectronBrowserContext::From(partition, true, std::move(options));
	}

kPersistPrefix 就是 "persist:",8 个字符——所以 substr(8) 是硬编码的长度,不是 strlen。三种形态对应:

  • ""(空串)→ 默认 session,落盘。
  • "persist:foo" → 名字 foo,落盘,目录在 Partitions/foo。
  • "foo" → 名字 foo,内存(in_memory = true),进程退出即丢。

注意第三种形态是"内存 session",不是"临时目录"。第二参数 in_memory 决定的不只是缓存路径,还包括 cookie store 是否加密、是否启用 HTTP cache 的磁盘部分。

分区名到目录的转换在 electron_browser_context.cc:242:

std::string MakePartitionName(const std::string& input) {
	return base::EscapePath(base::ToLowerASCII(input));
}

先小写,再转义。 这带来两个可观察的后果:

  1. persist:MyApp 和 persist:myapp 是同一个 session——但它们不是同一个字符串,所以在 JS 层是两个不同的 Session 请求,只是最终落到同一个 BrowserContext,返回同一个对象。判定发生在 PartitionKey 的 operator<=> 上,而 key 里存的是原始字符串:

electron_browser_context.cc:314-321

struct PartitionKey {
	PartitionKey(const std::string_view partition, bool in_memory)
	: type_{Type::Partition}, location_{partition}, in_memory_{in_memory} {}
	explicit PartitionKey(const base::FilePath& file_path)
	: type_{Type::Path}, location_{file_path.AsUTF8Unsafe()}, in_memory_{false} {}
	friend auto operator<=>(const PartitionKey&, const PartitionKey&) = default;
	enum class Type { Partition, Path };
	Type type_;
	std::string location_;
	bool in_memory_;
};

key 用的是原始 partition,而目录用的是小写 + 转义后的名字。这意味着 persist:Foo 和 persist:foo 会创建两个不同的 BrowserContext,却指向同一个磁盘目录。

这是真实的坑:两个 session、一份 cookie 文件、两套 HTTP cache 索引写同一个目录。表现是"偶发的 cookie 丢失"或"缓存文件损坏"(cache 目录被两个 NetworkContext 同时打开)。代码里没有任何地方对这种情况报错,因为从 PartitionKey 的角度它们是两个合法且不同的 Key。

FromPath(:991)走的是另一条 key:Type::Path,按绝对路径。所以 session.fromPath('/tmp/a') 和 session.fromPartition('persist:/tmp/a') 是两个不同的 context(虽然后者的目录名会被转义成 %2Ftmp%2Fa 之类)。

17.1.3 一个分区只有一个 Session

From 和 FromOrCreate 是两层缓存,别混:

electron_browser_context.cc:973

ElectronBrowserContext* ElectronBrowserContext::From(
	const std::string& partition, bool in_memory, base::DictValue options) {
	auto& context = ContextMap()[PartitionKey(partition, in_memory)];
	if (!context) {
	context.reset(new ElectronBrowserContext{std::cref(partition), in_memory,
											std::move(options)});
	}
	return context.get();
}

ContextMap()(:333)是一个 base::NoDestructor<std::map<PartitionKey, std::unique_ptr<ElectronBrowserContext>>>——进程级静态 map,永不销毁。这解释了一个常见疑问:为什么 session.fromPartition('x') 之后再 session.fromPartition('x'),拿到的是同一个对象?因为两处都指向同一块 BrowserContext,而 FromOrCreate 在 FromBrowserContext 拿到已有 Session 时直接返回。

第二层缓存才是 Session:

session.cc:1743

gin::WeakCell<Session>* existing = FromBrowserContext(browser_context);
if (existing && existing->Get()) {
	return existing->Get();
}
auto* session = cppgc::MakeGarbageCollected<Session>(
	isolate->GetCppHeap()->GetAllocationHandle(), isolate, browser_context);
v8::TryCatch try_catch(isolate);
gin_helper::CallMethod(isolate, session, "_init");
if (try_catch.HasCaught()) { node::errors::TriggerUncaughtException(isolate, try_catch); return nullptr; }
v8::Local<v8::Object> wrapper;
if (!session->GetWrapper(isolate).ToLocal(&wrapper)) return nullptr;
App::Get()->EmitWithoutEvent("session-created", wrapper);
return session;

三个细节值得记:

  • CallMethod(isolate, session, "_init")——JS 侧 Session 原型上有一个 _init(session.ts:24),C++ 造完对象后回调它。这是"混合构造":C++ 负责与 content 层对接,JS 负责补上 fetch、setPreloads 这些纯 JS 方法。如果 _init 抛异常,走 TriggerUncaughtException——在当前 JS 栈上抛出,所以 fromPartition 会直接炸,而不是返回一个半成品。
  • GetWrapper().ToLocal() 失败就返回 nullptr。什么时候会失败?对象刚被创建但 wrapper 还没生成时是正常的(GetWrapper 会触发生成),失败通常意味着 isolate 正在销毁。
  • EmitWithoutEvent("session-created", wrapper)——app 上的 session-created 事件。注意用的是 EmitWithoutEvent,不是 Emit:前者不经过 gin 的事件系统,直接转发给 JS。这个事件在 session.fromPartition 返回之前触发,所以监听器里拿到的 session 与调用方拿到的是同一个。

FromPartition 里还有一段预热:

electron_api_session.cc:1785-1788

	const bool creating = !FromBrowserContext(browser_context);
	Session* session = FromOrCreate(isolate, browser_context);
	// One renderer started ahead of the first window; the first sandboxed
	// WebContents takes it (ElectronBrowserClient::ShouldUseSpareRenderProcess-
	// Host), anything else lets content discard it.
	if (creating && partition.empty()) {
	content::SpareRenderProcessHostManager::Get().WarmupSpare(browser_context);
	}

只有"第一次创建默认 session"才预热一个备用 renderer 进程。"One renderer started ahead of the first window"——这样第一个窗口打开时不用等进程启动。条件里的 partition.empty() 是关键:非默认分区不预热,因为大部分分区可能整个生命周期都没有窗口。

17.1.4 Session 永不 GC

electron_api_session.h:235 有一行容易被忽略的成员:

	gin_helper::SelfKeepAlive<Session> keep_alive_{this};

SelfKeepAlive 的实现(self_keep_alive.h:15-22)是"持有一个指向自己的 cppgc::Persistent":

template <typename Self>
class SelfKeepAlive final {
	public:
	explicit SelfKeepAlive(Self* self) : keep_alive_(self) {}
	void Clear() { keep_alive_.Clear(); }
	explicit operator bool() const { return keep_alive_; }
	private:
	GC_PLUGIN_IGNORE("Allowed to keep a Persistent to itself.")
	cppgc::Persistent<Self> keep_alive_;
};

GC_PLUGIN_IGNORE 是给 clang 的 GC 插件的豁免——否则"对象持有自己的强引用"会被判定为循环引用泄漏。

结论:一个 Session 一旦创建,就不会被 JS GC 回收,直到 isolate 销毁时的 OnBeforeMicrotasksRunnerDispose(:1959)里 keep_alive_.Clear()。这意味着:

  • session.fromPartition() 反复调用不会造成对象堆积(本来就只有一份)。
  • 但如果你动态创建成千上万个不同名字的 partition,每个 Session 都永久占内存,BrowserContext 也是。ContextMap 更是永不清理。
  • Dispose()(:592)的第一行 if (!keep_alive_) return; 就是"已经清理过就别再来一遍"的幂等保护——注意它并不 Clear(),因为真正 Clear 的地方在 isolate 销毁路径上。这个写法有点反直觉:函数名叫 Dispose,却只在"还活着"时才做事。

17.1.5 new Session() 会被拒绝

Session::New()(:1817):

electron_api_session.cc:1817-1819

void Session::New() {
	gin_helper::ErrorThrower(JavascriptEnvironment::GetIsolate())
	.ThrowError("Session objects cannot be created with 'new'");
}

同一模式在 Protocol::New 也有("Protocol cannot be created from JS")。原因不是"不想让你造",而是造不出来:Session 必须绑定一个 BrowserContext,而 BrowserContext 只能通过 From / FromPath 拿到;Protocol 必须绑定一个 ProtocolRegistry,而注册表属于 BrowserContext。

17.1.6 六个懒创建的子对象

Session 的属性里有一批是 SetProperty 挂的 getter(:1822 起):

electron_api_session.cc:1896-1901

	.SetProperty("cookies", &Session::Cookies)
	.SetProperty("extensions", &Session::Extensions)
	.SetProperty("netLog", &Session::NetLog)
	.SetProperty("protocol", &Session::Protocol)
	.SetProperty("serviceWorkers", &Session::ServiceWorkerContext)
	.SetProperty("webRequest", &Session::WebRequest)

Protocol 是构造时就建好的(存在 protocol_ 成员里),其余五个是第一次访问才建,建完缓存到成员上,Trace() 里也把五个成员都遍历了一遍(cookies_、extensions_、protocol_、net_log_、service_worker_context_、web_request_)。

webRequest 的懒创建有个副作用值得说:WebRequest::FromOrCreate 会被 WillCreateURLLoaderFactory 调用。也就是说只要有任何网络请求发生,session.webRequest 这个对象就已经存在了,即使你从没写过 session.webRequest。所以"访问 session.webRequest 是否有开销"这个问题没有意义——开销早就在第一次请求时付过了。

真正的开销在另一点上:WebRequest 对象本身很便宜(两个 map + 一个 id 生成器),贵的是注册监听器。下一节会看到,一个监听器会改变整个 session 的请求路径。

17.1.7 小结:Session 的四张脸

把上面的内容压一下,Session 同时是四样东西:

  1. BrowserContext 的 JS 门面(browser_context_ 成员,1:1,通过 user data 双向索引)。
  2. 一组网络身份配置的容器(cache 大小、proxy、UA、SSL 配置、证书校验回调、网络模拟参数)——这些最终都写进 NetworkContext 的参数里。
  3. 六个子 API 的宿主(cookies / protocol / webRequest / netLog / serviceWorkers / extensions),每个都是"属于这个分区"的。
  4. 一个永不回收的 cppgc 对象(SelfKeepAlive),生命周期等于 isolate。

下一节看第 2 项:这些配置怎么变成 network service 里的一块 NetworkContext。

17.2 NetworkContext:每个 session 一块网络身份

Session 的配置最终都变成 network::mojom::NetworkContextParams 里的字段,交给 network service 去创建一块 NetworkContext。理解这个翻译过程,比记住 session.setProxy 的签名有用得多——因为所有"为什么这个设置不生效"的问题,答案几乎都在这张参数表里。

17.2.1 两个 NetworkContext

Electron 进程里永远有两类 NetworkContext:

  • system context:SystemNetworkContextManager(system_network_context_manager.cc:293 行)持有,全局唯一。用于 Chromium 自己发起、不属于任何 session 的请求(组件更新、DNS 探测、代理解析的脚本下载)。它的 http_cache_enabled = false。
  • session context:每个 ElectronBrowserContext 一个,通过 StoragePartition::GetNetworkContext() 拿到。用户的绝大多数请求走这条。

两者的创建时机不同:system context 在 OnNetworkServiceCreated 里建(network service 启动时),session context 在该 session 第一次需要网络时惰性建。两者共享一份"默认参数":

network_context_service.cc:52

void NetworkContextService::ConfigureNetworkContextParams(
	network::mojom::NetworkContextParams* network_context_params,
	cert_verifier::mojom::CertVerifierCreationParams* cert_verifier_creation_params) {
	bool in_memory = browser_context_->IsOffTheRecord();
	const base::FilePath& path = browser_context_->GetPath();
	g_browser_process->system_network_context_manager()
	->ConfigureDefaultNetworkContextParams(network_context_params);

共享的部分只有三行(system_network_context_manager.cc:193):

void SystemNetworkContextManager::ConfigureDefaultNetworkContextParams(
	network::mojom::NetworkContextParams* network_context_params) {
	network_context_params->enable_brotli = true;
	network_context_params->enable_zstd = true;
	network_context_params->enable_referrers = true;
	network_context_params->proxy_resolver_factory =
	ChromeMojoProxyResolverFactory::CreateWithSelfOwnedReceiver();
}

enable_brotli / enable_zstd 是编解码开关,enable_referrers 决定是否发 Referer 头,proxy_resolver_factory 是 PAC 脚本的执行器(ChromeMojoProxyResolverFactory = 在 utility 进程里跑 V8 来求值 PAC)。

注意这里没有设 user_agent、http_cache_enabled、ssl_config——这三样是 session context 独有的,在 NetworkContextService 里各自设置。

17.2.2 session context 的参数逐项

ConfigureNetworkContextParams 剩下的部分,可以按"这个设置坏了会怎样"来读。

SSL 配置客户端:

network_context_service.cc:56-60

	mojo::Remote<network::mojom::SSLConfigClient> ssl_config_client;
	network_context_params->ssl_config_client_receiver =
	ssl_config_client.BindNewPipeAndPassReceiver();
	browser_context_->SetSSLConfigClient(std::move(ssl_config_client));
	network_context_params->initial_ssl_config = browser_context_->GetSSLConfig();

ssl_config_client_receiver 是一条反向通道:network service 侧 SSL 配置变化(比如 TLS 1.3 早期数据的开关、证书错误策略)会通过它通知 browser。initial_ssl_config 是初值,来自 browser_context_->GetSSLConfig(),而它又被 session.setSSLConfig() 改(session.cc:1043,直接 ssl_config_ = std::move(config))。所以 setSSLConfig 改的是下一次 NetworkContext 创建时的初值,已经在跑的请求不受影响——除非你同时通过 client 推一次。

CORS 白名单与语言:

network_context_service.cc:65-70

	network_context_params->cors_origin_access_list =
	browser_context_->GetSharedCorsOriginAccessList()
		->GetOriginAccessList().CreateCorsOriginAccessPatternsList();
	network_context_params->accept_language =
	net::HttpUtil::GenerateAcceptLanguageHeader(
		ElectronBrowserClient::Get()->GetApplicationLocale());

accept-language 由应用 locale 生成,不是系统 locale。这是 Electron 的既定行为:app.commandLine.appendSwitch('lang') 会影响它,系统语言不会。

HTTP cache:

	network_context_params->http_cache_enabled = browser_context_->can_use_http_cache();

can_use_http_cache() 的值来自两处(electron_browser_context.cc:378):

	use_cache_ = !command_line->HasSwitch(switches::kDisableHttpCache);
	if (auto use_cache_opt = options.FindBool("cache")) {
	use_cache_ = use_cache_opt.value();
	}

也就是 --disable-http-cache 命令行,或 session.fromPartition('x', { cache: false }) 里的 cache 选项。后者是创建时的选项,session 建好之后改不了。

磁盘参数(只在非内存 session 里设):

network_context_service.cc:82-89

	if (!in_memory) {
	network_context_params->http_cache_max_size = browser_context_->max_cache_size();
	network_context_params->file_paths = network::mojom::NetworkContextFilePaths::New();
	network_context_params->file_paths->data_directory = path.Append(chrome::kNetworkDataDirname);
	network_context_params->file_paths->unsandboxed_data_path = path;
	network_context_params->file_paths->trigger_migration = ShouldTriggerNetworkDataMigration();
	network_context_params->file_paths->http_cache_directory = path.Append(chrome::kCacheDirname);
	network_context_params->file_paths->cookie_database_name = base::FilePath(chrome::kCookieFilename);
	network_context_params->file_paths->trust_token_database_name = base::FilePath(chrome::kTrustTokenFilename);
	network_context_params->file_paths->transport_security_persister_file_name =
		base::FilePath(chrome::kTransportSecurityPersisterFilename);
	network_context_params->restore_old_session_cookies = false;
	network_context_params->persist_session_cookies = false;
	...
	}

四个路径值得分开看:

  • data_directory = <session 目录>/Network——NetworkContext 的"根",其他相对路径都相对它解析。
  • unsandboxed_data_path = session 根目录 + trigger_migration。这两个字段是给 Windows 网络沙箱用的:沙箱开启后 network service 只能访问 data_directory,所以旧数据要从非沙箱路径迁移过来。ShouldTriggerNetworkDataMigration()(network_context_service.cc:25)在 Windows 上返回"网络沙箱是否开启",其他平台看 features::kTriggerNetworkDataMigration。
  • http_cache_directory = <session 目录>/Cache——和 data_directory 是兄弟目录,不是子目录。
  • cookie_database_name / trust_token_database_name / transport_security_persister_file_name 是文件名,不是路径——它们相对 data_directory 解析。

最后两行是 Electron 的明确选择:restore_old_session_cookies = false(不恢复上次的 session cookie)、persist_session_cookies = false(不把 session cookie 写盘)。浏览器通常会恢复 session cookie 让用户"关掉再开还在登录状态",Electron 不做这件事:进程退出,session cookie 就没了。

http_cache_max_size 来自 --disk-cache-size 命令行(electron_browser_context.cc:382 用 base::StringToInt 解析,解析失败就是 0,即"用默认值")。

17.2.3 cookie 加密与一个 fuse

network_context_service.cc:114-121

	network_context_params->enable_encrypted_cookies =
		electron::fuses::IsCookieEncryptionEnabled();
	if (network_context_params->enable_encrypted_cookies) {
	if (!cookie_encryption_provider_) {
		cookie_encryption_provider_ =
			std::make_unique<CookieEncryptionProviderImpl>(
				g_browser_process->os_crypt_async());
	}
	network_context_params->cookie_encryption_provider =
		cookie_encryption_provider_->BindNewRemote();
	}

fuses 是编译期/打包期可以翻转的开关(第 20 章会讲)。cookie_encryption 这个 fuse 关闭时,cookie 的 value 在 SQLite 里是明文;打开时用 OS 的密钥库(macOS Keychain、Windows DPAPI、Linux libsecret/kwallet)加密,CookieEncryptionProviderImpl 是那层桥。

这里有个真实的行为差异:fuse 是打包时决定的,不是运行时。所以"开发时 cookie 是明文、打包后加密"这种情况会出现,而 os_crypt_async 在 Linux 上如果拿不到 keyring,加密会退化成 "v10" 前缀 + 固定密钥的弱加密——看起来加密了,实际上换台机器就能解。这不是 Electron 的实现问题,是 Chromium 的既定降级路径。

17.2.4 proxy:pref 与命令行两条路

代理配置在 Electron 里有三个来源,优先级从低到高:

  1. 命令行 --proxy-server、--proxy-pac-url、--proxy-bypass-list。
  2. session.setProxy({ mode, proxyRules, pacScript, proxyBypassRules })。
  3. 运行时 session.forceReloadProxyConfig()(不改配置,只让 network service 重新读一次 PAC)。

setProxy(session.cc:757)的实现短得有点意外:

	if (!browser_context_->in_memory_pref_store()) {
	promise.Resolve();
	return handle;
	}
	...
	browser_context_->in_memory_pref_store()->SetValue(
	proxy_config::prefs::kProxy,
	base::Value{createProxyConfig(proxy_mode, pac_url, proxy_rules, bypass_list)},
	WriteablePrefStore::DEFAULT_PREF_WRITE_FLAGS);
	base::SingleThreadTaskRunner::GetCurrentDefault()->PostTask(
	FROM_HERE, base::BindOnce(gin_helper::Promise<void>::ResolvePromise, std::move(promise)));

三个要点:

  • 写的是 in_memory_pref_store,不是磁盘上的 Preferences。所以 setProxy 的结果不跨进程持久化——下次启动要重新设。
  • 如果 in_memory_pref_store() 为空,直接 resolve,什么都不做,也不报错。什么时候会为空?测试环境或某些非标准构造路径。这是"静默失败"的典型:调用方以为设上了。
  • 写完不立即生效,靠 ProxyConfigMonitor 观察 pref 变化再推给 network service;PostTask 只是保证 promise 在下一轮才 resolve,给观察者一点时间。真正要确保生效,得自己调 forceReloadProxyConfig()。

createProxyConfig(:370)里有一个反直觉的分支:

electron_api_session.cc:776-782

	ProxyPrefs::ProxyMode proxy_mode = ProxyPrefs::MODE_FIXED_SERVERS;
	if (!options.Get("mode", &mode)) {
	if (!pac_url.empty()) {
	proxy_mode = ProxyPrefs::MODE_PAC_SCRIPT;
	} else {
	proxy_mode = ProxyPrefs::MODE_FIXED_SERVERS;
	}
	} else { ... StringToProxyMode ... }

没传 mode 时,有 pacScript 就自动变成 PAC 模式,否则固定服务器模式。 传了 mode 就完全按 mode 走,忽略 pacScript 的存在——所以 setProxy({ mode: 'fixed_servers', pacScript: '...' }) 里那个 pacScript 会被无声丢弃。

ConfigureNetworkContextParams 末尾还有一行:

network_context_service.cc:135-136

	BrowserProcessImpl::ApplyProxyModeFromCommandLine(
	browser_context_->in_memory_pref_store());

每次创建 NetworkContext 都会用命令行覆盖一次 pref store。 也就是说,命令行代理的优先级实际上是最高——它在 NetworkContext 创建这一刻盖掉 setProxy 写进去的值。如果你的 app 用 --proxy-server 启动,又调 setProxy,谁生效取决于时序:setProxy 之后创建 NetworkContext,命令行赢;NetworkContext 建好之后 setProxy,pref 变化通知赢。这种竞态在真实项目里表现为"代理设置偶尔不生效"。

17.2.5 network service 崩了怎么办

network service 是一个可以独立崩溃、独立重启的进程。它一崩,所有指向它的 mojo remote 都断开——包括几千个正在飞的请求,以及所有 URLLoaderFactory。

Electron 在两层做了重建:

system 层(system_network_context_manager.cc:135):

network::mojom::NetworkContext* SystemNetworkContextManager::GetContext() {
	if (!network_context_ || !network_context_.is_connected()) {
	content::GetNetworkService();   // 会触发 OnNetworkServiceCreated → 重建 context
	DCHECK(network_context_);
	}
	return network_context_.get();
}

content::GetNetworkService() 在 service 已经死掉时会拉起一个新进程并回调 OnNetworkServiceCreated,那里重新 CreateNetworkContext。

session 层用 ReconnectableURLLoaderFactory(electron_browser_context.cc:609):

	if (!url_loader_factory_) {
	url_loader_factory_ =
		base::MakeRefCounted<content::ReconnectableURLLoaderFactory>(
			base::BindRepeating(&ElectronBrowserContext::CreateURLLoaderFactory,
								weak_factory_.GetWeakPtr()));
	}

这个类的作用是:持有一个工厂的 PendingRemote,检测到断开就调用回调重建一次,然后把重建后的工厂"接"回原来的 remote——对调用方完全透明。所以 net.request 在 network service 崩溃后能继续工作,不需要重试逻辑。

但已经发出的请求不会复活。URLLoader 的管道是进程内 mojo,进程死了管道就断了,客户端会收到 OnComplete(ERR_FAILED) 或连接错误。能恢复的只有"下一次请求"。

17.3 装配链:一次请求经过谁

17.3.1 唯一的装配点

所有需要"Electron 干预"的 URL 请求,都会经过 ElectronBrowserClient::WillCreateURLLoaderFactory(electron_browser_client.cc:1668)。这是 ContentBrowserClient 的钩子,Chromium 在给某个 renderer(或 browser 自己)创建 URL 加载工厂时调用它。

它的位置很关键:它在"工厂链"的最外层。Chromium 会先准备好一个"直连 network service"的工厂(factory_builder),然后让 embedder 往里插东西。Electron 的做法是:

	auto [proxied_receiver, target_factory_remote] = factory_builder.Append();

URLLoaderFactoryBuilder::Append() 返回一对端点:一个 receiver 交给"上一层",一个 remote 指向"下一层"。插入一个工厂,就是把这两个端点接上自己的实现。Electron 在这里插入的是 ProxyingURLLoaderFactory。

在插入之前还有两个分支:

分支一:Extensions API 优先。 如果编译了 extensions 支持,且 Electron 自己的 webRequest 没有监听器,就让 Chromium 的 extensions 系统先试:

electron_browser_client.cc:1694-1700

	const bool is_browser_process_request =
	type == URLLoaderFactoryType::kNavigation && !frame_host;
	if (!web_request->HasListener() && !is_browser_process_request) {
	auto* web_request_api = extensions::BrowserContextKeyedAPIFactory<
		extensions::WebRequestAPI>::Get(browser_context);
	bool used_proxy_for_web_request = web_request_api->MaybeProxyURLLoaderFactory(...);
	if (used_proxy_for_web_request) return;
	}

这段代码说明 Electron 的 webRequest 和 extensions 的 webRequest 是互斥的:只要 Electron 侧注册了任何监听器,extensions 那边就完全拿不到请求。注释里还特意标明"main process 发起的请求(如 net.fetch)没有 frame,不走 extensions"——因为 extensions 需要 frame 来判定权限。

分支二:给 renderer 装上 gate。 这是这一版代码里最值得讲的结构:

electron_browser_client.cc:1718-1725

	if (frame_host && type != URLLoaderFactoryType::kNavigation) {
	mojo::Remote<network::mojom::URLLoaderFactory> target(std::move(target_factory_remote));
	mojo::PendingRemote<network::mojom::URLLoaderFactory> gate_to_network;
	target->Clone(gate_to_network.InitWithNewPipeAndPassReceiver());
	mojo::PendingRemote<network::mojom::URLLoaderFactory> gate_to_proxy;
	mojo::PendingReceiver<network::mojom::URLLoaderFactory> proxy_receiver =
		gate_to_proxy.InitWithNewPipeAndPassReceiver();
	CreateURLLoaderFactoryGate(
		static_cast<ElectronBrowserContext*>(browser_context),
		render_process_id, frame_host->GetRoutingID(),
		std::move(proxied_receiver), std::move(gate_to_network),
		std::move(gate_to_proxy));
	proxied_receiver = std::move(proxy_receiver);
	target_factory_remote = target.Unbind();
	}

结构变成:

renderer → gate(IO 线程) → ┬→ network service(直连)
							└→ ProxyingURLLoaderFactory(UI 线程) → network service

gate 自己不做任何拦截,它只做路由:这个请求需要去 UI 线程吗? 不需要就直连,需要才转给 proxying。这一层的意义是性能:Electron 用户里绝大多数不注册 webRequest 监听器,但 Chromium 并不知道,如果每个请求都往 UI 线程绕一圈再回 IO 线程,光线程跳转就是可观的成本。

17.3.2 gate 的三种路由

路由规则在 InterceptState(url_loader_factory_gate.h:49):

class InterceptState : public base::RefCountedThreadSafe<InterceptState> {
	public:
	enum class Route { kDirect, kObserve, kProxy };
	void SetListenerTypes(uint32_t blocking_types, uint32_t observer_types);
	void SetInterceptedSchemes(base::flat_set<std::string> schemes);
	void SetIgnoreConnectionsLimitDomains(std::vector<std::string> domains);
	Route RouteFor(const network::ResourceRequest& request) const;

它只有四个字段,全部用一个 base::Lock 保护——因为这个对象在 UI 线程写、在 IO 线程读。注释写得很直白:"Written on the UI thread, read on IO."

RouteFor 的判定只有三步:

url_loader_factory_gate.cc:116-123

InterceptState::Route InterceptState::RouteFor(
	const network::ResourceRequest& request) const {
	base::AutoLock lock(lock_);
	if (WantsURL(request.url)) return Route::kProxy;
	const uint32_t type_bit = 1u << static_cast<int>(ResourceTypeOf(request));
	if (blocking_types_ & type_bit) return Route::kProxy;
	if (observer_types_ & type_bit) return Route::kObserve;
	return Route::kDirect;
}

WantsURL 是"URL 级别的特殊照顾":

url_loader_factory_gate.cc:106-110

bool InterceptState::WantsURL(const GURL& url) const {
	if (intercepted_schemes_.contains(url.scheme())) return true;
	for (const auto& domain : ignore_connections_limit_domains_) {
	if (url.DomainIs(domain)) return true;
	}
	return false;
}

两条:被拦截的 scheme(protocol.interceptProtocol 注册的)必须走 UI 线程,因为拦截处理器是 JS 函数,只能在 UI 线程调;--ignore-connections-limit 指定的域也必须走,因为这个开关的实现是在 proxying 工厂里改 load_flags(proxying_url_loader_factory.cc:845):

	if (ShouldIgnoreConnectionsLimit(request)) {
	request.priority = net::RequestPriority::MAXIMUM_PRIORITY;
	request.load_flags |= net::LOAD_IGNORE_LIMITS;
	}

type_bit 那一层用的是"资源类型位掩码"。类型由 ResourceTypeOf(url_loader_factory_gate.cc:33)算:

WebRequestResourceType ResourceTypeOf(const network::ResourceRequest& request) {
	using Destination = network::mojom::RequestDestination;
	if (request.url.SchemeIsWSOrWSS()) return WebRequestResourceType::WEB_SOCKET;
	if (request.is_fetch_like_api) return WebRequestResourceType::XHR;
	switch (request.destination) {
	case Destination::kDocument: return WebRequestResourceType::MAIN_FRAME;
	...
	case Destination::kScript: ... return WebRequestResourceType::SCRIPT;
	case Destination::kImage: return WebRequestResourceType::IMAGE;
	...
	}
}

注释说它 "Mirrors ToWebRequestResourceType() in extensions/browser/api/web_request/web_request_info.cc, which is not exported."——Chromium 有这个函数,但没导出,所以抄了一份。抄的时候有个后果:Chromium 改了映射,Electron 不会跟着改。

这里有个顺序陷阱:is_fetch_like_api 的判断在 destination 之前。所以 fetch() 请求(destination 可能是 kEmpty)会被归为 XHR,而不是 OTHER。如果用户监听器只写了 types: ['other'],fetch() 不会触发——它被算成 xhr。

blocking_types_ 和 observer_types_ 的来源在 WebRequest::UpdateInterceptState(electron_api_web_request.cc:787):

void WebRequest::UpdateInterceptState() {
	uint32_t blocking = 0, observers = 0;
	for (const auto& [event, info] : response_listeners_)
	blocking |= info.filter.TypeMask();
	for (const auto& [event, info] : simple_listeners_)
	observers |= info.filter.TypeMask();
	browser_context_->intercept_state()->SetListenerTypes(blocking, observers);
}

响应式事件(能改能拦)= blocking,单向事件(只能看)= observer。 这个划分贯穿全章:onBeforeRequest、onBeforeSendHeaders、onHeadersReceived 属于前者;onSendHeaders、onBeforeRedirect、onResponseStarted、onCompleted、onErrorOccurred 属于后者。

17.3.3 observe 路径:不阻塞的"旁听"

Route::kObserve 是最有意思的一条。用户只注册了单向事件(比如 onCompleted 记日志),这时请求不该被阻塞,但仍然要"看见"。做法是在 IO 线程上架一个双向代理(url_loader_factory_gate.cc:133 的 ObservedURLLoader):

class ObservedURLLoader : public network::mojom::URLLoader,
						public network::mojom::URLLoaderClient {
	...
	// Observer events don't report uploadData, and the IO thread is still
	// sending this body to the network.
	request_.request_body = nullptr;
	UIThread()->PostTask(FROM_HERE,
		base::BindOnce(&api::WebRequest::ObservedRequestStarted,
					browser_context_, key_, render_process_id_,
					frame_routing_id_, request_));

它同时实现 URLLoader(面向 renderer)和 URLLoaderClient(面向 network)。数据流是:

renderer client ← ObservedURLLoader ← network
				(原样转发,不缓存)

每个回调都做两件事:先同步转发给 renderer(renderer_client_->OnReceiveResponse(...)),再 PostTask 把一份副本发到 UI 线程。所以 observe 路径的延迟增加接近于零——renderer 不需要等 UI 线程。

三个细节:

  • request_.request_body = nullptr——注释解释了原因:observer 事件本来就不报 uploadData,而 IO 线程还在把 body 往网络送,保留引用没意义。
  • head_for_ui = head.Clone()——response head 是 mojo 结构体,转发给 renderer 时被 move 走了,所以先克隆一份给 UI 线程。
  • OnReceiveRedirect 里 DCHECK(!pending_redirect_),并且把 redirect_info 存到 pending_redirect_,等 renderer 调 FollowRedirect 时用它更新 request_(UpdateOnRedirect),再 PostTask 通知 UI 线程。为什么不能立刻通知? 因为 renderer 可能拒绝跟随重定向(比如 fetch 的 redirect: 'manual'),那时这条链就结束了,不该报一次"跟随了重定向"。

ObservedURLLoader 的析构路径也值得看:Finish() 里 delete this,而它同时被四个 mojo 端点引用(renderer 的 loader、renderer 的 client、network 的 loader、network 的 client)。任何一个断开都会调 Finish,所以 Finish 必须幂等——靠的是 weak_factory_ 加 delete this 后其他回调全部失效。

17.3.4 为什么导航不套 gate

if (frame_host && type != URLLoaderFactoryType::kNavigation)——两个条件缺一不可。frame_host 为空是 browser 进程发起的请求(net.request),没有 frame 可挂;type == kNavigation 是导航,被显式排除。

导航不套 gate 的理由,代码里没写,但从结构上能推出来:

  1. 导航没有"高频直连"的收益。 一个页面一个导航,省一次线程跳转没有意义。
  2. 导航必须走 proxying。 即使没有 webRequest 监听器,导航也要经过 ProxyingURLLoaderFactory,因为 onBeforeRequest 之外还有 navigation_ui_data、navigation_id 这些只有 proxying 才处理的东西(electron_api_ipc_dispatch 里 SW 的消息路由也依赖它)。
  3. 导航的 factory 生命周期与 frame 绑定。 gate 是 SelfDeletingURLLoaderFactory,靠"最后一个 receiver 断开"自毁;导航的 factory 由 NavigationURLLoaderImpl 持有,生命周期规则不同,套 gate 容易出悬挂。

所以 gate 只服务于"renderer 的 subresource"这一类:图片、脚本、XHR、fetch、字体、媒体。这也正是数量最多、性能最敏感的一类。

17.4 webRequest:把 mojo 状态机翻译成事件

ProxyingURLLoaderFactory(1003 行)是整章最长的一块代码。它做的事情听起来简单:收到一个请求,按顺序问 JS 几个问题,根据回答决定继续、改、或者拦。但 Chromium 的 URLLoader 协议是双向且可重入的——客户端随时可能调 FollowRedirect,服务端随时可能推 OnReceiveResponse,而 JS 的回调是异步的。三者叠加,就变成了一个必须显式管理"暂停/恢复"的状态机。

17.4.1 一个事件只能有一个监听器

先看 JS 侧的注册接口,因为它决定了后面所有的设计。

WebRequest 内部不是"事件 → 监听器数组",而是"事件 → 单个监听器":

electron_api_web_request.cc:391-392

bool WebRequest::HasListener() const {
	return !(simple_listeners_.empty() && response_listeners_.empty());
}

两个 map:simple_listeners_(单向事件)和 response_listeners_(可返回响应的事件)。SetListener(:718)在传入 null 时 listeners->erase(event),否则 (*listeners)[event] = {filter, listener}——同一个事件注册第二次会覆盖第一次,不报错,不警告。

这解释了一个常见的困惑:"我在两个模块里都注册了 onBeforeRequest,为什么只有一个生效?"因为 API 就是这样。要合并逻辑只能自己在应用层做。

SetListener 里还有两处值得注意的校验:

electron_api_web_request.cc:735-742

	if (!dict.Get("urls", &filter_include_patterns)) {
		args->ThrowTypeError("Parameter 'filter' must have property 'urls'.");
		return;
	}
	if (filter_include_patterns.empty()) {
		util::EmitDeprecationWarning(
			"The urls array in WebRequestFilter is empty, which is deprecated. "
			"Please use '<all_urls>' to match all URLs.");
		filter_include_patterns.insert("<all_urls>");
	}

urls 是必填的。空数组不算"匹配全部",而是触发一个弃用警告然后当作 <all_urls>。这个行为是历史遗留:早期版本允许省略 urls,现在要求显式写,但为了兼容空数组仍然放行。

types 里的非法值直接抛错:

electron_api_web_request.cc:762-768

	for (const std::string& filter_type : filter_types) {
	auto type = ParseResourceType(filter_type);
	if (type != extensions::WebRequestResourceType::OTHER) {
	filter.AddType(type);
	} else {
	args->ThrowTypeError("Invalid type " + filter_type);
	return;
	}
	}

注意这里有个死角:ParseResourceType 对未知字符串返回 OTHER,而 types: ['other'] 是合法的。所以 types: ['bogus'] 和 types: ['other'] 走到同一个分支——前者抛错,后者也抛错(因为 type == OTHER)。也就是说 types: ['other'] 根本注册不上。想匹配 OTHER 类型的请求,只能靠不写 types(即匹配全部类型)。

注册完立即生效:

	if (listener.is_null()) listeners->erase(event);
	else (*listeners)[event] = {std::move(filter), std::move(listener)};
	UpdateInterceptState();

UpdateInterceptState 重算类型位掩码,写进 InterceptState。从这一刻起,该 session 的 gate 路由就变了——已经在飞的请求不受影响,但下一个请求会走新路径。这也意味着:注册监听器不是"加一个回调",而是"改变整个 session 的网络拓扑"。

17.4.2 阻塞是怎么实现的

webRequest 的三个响应式事件都能"卡住"请求。Chromium 的 URLLoaderFactory 是同步接口——CreateLoaderAndStart 不返回状态,所以"卡住"必须用另一套机制。

Electron 用的就是 Chromium 自己的约定:返回 net::ERR_IO_PENDING,并在稍后调用 continuation。

InProgressRequest::RestartInternal(proxying_url_loader_factory.cc:165)是这条规则的样板:

	int result = factory_->web_request_->OnBeforeRequest(
	&info_.value(), request_, continuation, &redirect_url_);
	if (result == net::ERR_BLOCKED_BY_CLIENT) {
	network::URLLoaderCompletionStatus status(result);
	OnRequestError(status);
	return;
	}
	if (result == net::ERR_IO_PENDING) {
	if (proxied_client_receiver_.is_bound())
	proxied_client_receiver_.Pause();
	if (header_client_receiver_.is_bound())
	header_client_receiver_.Pause();
	return;
	}
	DCHECK_EQ(net::OK, result);
	continuation.Run(net::OK);

三件事同时做:

  1. 暂停客户端管道。 proxied_client_receiver_ 是"renderer 那边发来的消息"的接收端(FollowRedirect、SetPriority),header_client_receiver_ 是 network service 发来的头处理请求。两个都 Pause()——否则 JS 还没回答,renderer 已经在问下一个问题,状态会乱。
  2. 不调 continuation。 continuation 被存进 WebRequest::BlockedRequest,等 JS 回调触发。
  3. 返回。 控制权回到 mojo 事件循环。

对应的恢复在 WebRequest::OnBeforeRequestListenerResult(electron_api_web_request.cc:437):

	int result = net::OK;
	if (response->IsObject()) {
	bool cancel = false;
	dict.Get("cancel", &cancel);
	if (cancel) {
	result = net::ERR_BLOCKED_BY_CLIENT;
	} else {
	dict.Get("redirectURL", request.new_url.get());
	}
	}
	base::SequencedTaskRunner::GetCurrentDefault()->PostTask(
	FROM_HERE, base::BindOnce(std::move(request.callback), result));

为什么用 PostTask 而不是直接调 callback? 因为此刻还在 JS 的调用栈里(info.listener.Run(...) 的同步返回路径上)。直接调 callback 会一路同步回到 mojo,再从 mojo 回调到 InProgressRequest,而 InProgressRequest 可能在这一路上被销毁——典型的"JS 回调里重入 C++ 对象"问题。PostTask 把恢复推到下一轮消息循环,栈已经退干净。

注意 request.callback 是 net::CompletionOnceCallback(只能调一次),blocked_requests_.extract(id) 把它从 map 里摘出来——摘不到就直接 return,说明这个请求已经被 OnErrorOccurred / OnCompleted / OnRequestWillBeDestroyed 清理过了(那些路径都会 blocked_requests_.erase(info->id))。这是"迟到回包"的防护:JS 回调慢了一拍,请求已经死了,不能再调 continuation。

17.4.3 onBeforeRequest:唯一的"拦在发出去之前"

这个事件的三个能力:cancel、redirectURL、看 uploadData。

redirectURL 的处理在 ContinueToBeforeSendHeaders(:462)里:

	if (!current_request_uses_header_client_ && !redirect_url_.is_empty()) {
	if (for_cors_preflight_) { ... }
	else {
	request_.url = redirect_url_;
	...
	}
	}

这里有个前提:只有在"没用 header client"时才能在 onBeforeRequest 里改 URL。 用了 header client 的路径需要在 OnBeforeSendHeaders 里通过 FollowRedirect 传新 URL(见 17.4.7)。所以同一个 redirectURL 在两条路径上走的是完全不同的代码,行为也可能有细微差异——这是本节最容易被忽略的一点。

uploadData 只在这个事件里有:

	if (request.request_body) details.Set("uploadData", *request.request_body);

request_body 是 network::ResourceRequestBody,gin converter 把它转成 Electron 文档里那个 { blobUUID } / { bytes } / { file } 的数组。大文件上传时这个对象会很大——它不是流,是整个 body 的描述。如果一个 1GB 的上传在 onBeforeRequest 里被序列化成 JS 对象,光这一步就能让进程卡住几秒。这是 webRequest 不适合处理大上传的根本原因。

17.4.4 onBeforeSendHeaders:只回传 delta

这是三个响应式事件里最精细的一个。

JS 拿到的 details.requestHeaders 是完整头集合,但回传的不是"新的完整集合",而是差分。原因在 CalculateOnBeforeSendHeadersDelta(:179)的头部注释:

electron_api_web_request.cc:178-185

// Modified from extensions/browser/api/web_request/web_request_api_helpers.cc.
std::pair<std::set<std::string>, std::set<std::string>>
CalculateOnBeforeSendHeadersDelta(const net::HttpRequestHeaders* old_headers,
								const net::HttpRequestHeaders* new_headers) {
	std::set<std::string> modified_request_headers;
	std::set<std::string> deleted_request_headers;
	// The event listener might not have passed any new headers if it
	// just wanted to cancel the request.
	if (new_headers) {
	{ // find deleted
	net::HttpRequestHeaders::Iterator i(*old_headers);
	while (i.GetNext())
		if (!new_headers->HasHeader(i.name())) deleted_request_headers.insert(i.name());
	}
	{ // find modified
	net::HttpRequestHeaders::Iterator i(*new_headers);
	while (i.GetNext())
		if (i.value() != old_headers->GetHeader(i.name()))
		modified_request_headers.insert(i.name());
	}
	}
	return std::make_pair(modified_request_headers, deleted_request_headers);
}

为什么不能整体替换?因为请求头里有一批是 network service 在后面才加的(Host、Content-Length、Cookie、Accept-Encoding、Connection、HTTP/2 伪头)。JS 拿到的 requestHeaders 是"当前已知的那些",整体替换会把后面才生成的丢弃或重复。Chromium 的 extensions 版本用差分正是为此,Electron 抄了一份。

差分带来三个可观察的行为:

  1. 删不掉"JS 看不到的头"。 你没法通过"从对象里移除"来删 Cookie——它可能压根不在 details.requestHeaders 里。
  2. 改大小写不生效。 HasHeader 是大小写不敏感的,但 i.value() != old_headers->GetHeader(i.name()) 只比值。所以改 'User-Agent' 为 'user-agent' 不会算作修改(值相同),最终发的还是原来的名字。
  3. 顺序改了也无所谓。 差分是两个 set,没有顺序概念。想控制头顺序只能靠 rawHeaders——而 webRequest 不给这个机会。

onBeforeSendHeadersListenerResult 里还有一个判断:

electron_api_web_request.cc:542-543

	// Leave |request.request_headers| unchanged if the user didn't modify it.
	if (user_modified_headers)
	request.request_headers->Swap(&new_headers);

user_modified_headers 只在 dict.Get("requestHeaders", &value) && value->IsObject() 时为真。也就是说,回调返回 { cancel: true } 或 {} 时,原头集合保持不变——不会因为"没返回 requestHeaders"而被清空。这个保护很重要,否则一个只想 cancel 的监听器会顺手把所有头删掉。

17.4.5 onHeadersReceived:只能整体替换

onHeadersReceived 的回传语义与前者相反:必须给完整的新头集合,因为它是"响应头",不存在"后面还会加"的问题(除了 Set-Cookie 的分批,见下)。

	} else {
	std::string status_line;
	if (!dict.Get("statusLine", &status_line)) status_line = request.status_line;
	v8::Local<v8::Value> value;
	if (dict.Get("responseHeaders", &value) && value->IsObject()) {
		user_modified_headers = true;
		override_headers->ReplaceStatusLine(status_line);
		gin::Converter<net::HttpResponseHeaders*>::FromV8(isolate, value, override_headers.get());
	}
	}
	}
	if (user_modified_headers) request.override_response_headers->swap(override_headers);

三个细节:

  • statusLine 单独处理。 override_headers 是 new net::HttpResponseHeaders("")(空头),先 ReplaceStatusLine 再灌头。如果不给 statusLine,用原来的。这是唯一能改状态码的地方——statusCode 字段是只读的,改它没用。
  • 不给 responseHeaders 就完全不动响应头,即使给了 statusLine。因为 user_modified_headers 只由 responseHeaders 是否存在决定。
  • 头的原始大小写在这里是保留的。 HttpResponseHeadersToV8(:93)特意没用现成的 converter,注释说明了原因:
// Note that while we already have converters for HttpResponseHeaders, we can
// not use it because it lowercases the header keys, while the webRequest has
// to pass the original keys.

Set-Cookie 是唯一必须用数组形式传的头。HttpResponseHeadersToV8 用 EnsureList(key)->Append(value),所以同名头天然变成数组。反过来,用户回传时如果给了字符串而不是数组,Converter<net::HttpResponseHeaders*>::FromV8(net_converter.cc:198)只会在 else 分支里 AddHeader 一次——多条 Set-Cookie 变成一条,且不会有任何警告。

还有一个被丢掉的参数。WebRequest::OnHeadersReceived 的签名里有 GURL* allowed_unsafe_redirect_url(:551),但实现直接把它丢了:

electron_api_web_request.cc:558-560

	return HandleOnHeadersReceivedResponseEvent(
	info, request, std::move(callback), original_response_headers,
	override_response_headers);

所以 Electron 的 webRequest 无法在 onHeadersReceived 里做"不安全重定向"(跨 scheme、带凭据的 3xx)。Chromium 的 extensions 版本可以,Electron 没实现。

17.4.6 details 对象里到底有什么

FillDetails 是一串重载的 ToDictionary,把所有参数拼进一个字典。字段清单(electron_api_web_request.cc:113):

void ToDictionary(gin_helper::Dictionary* details,
				const extensions::WebRequestInfo* info) {
	details->Set("id", info->id);
	details->Set("url", info->url);
	details->Set("method", info->method);
	details->Set("timestamp", base::Time::Now().InSecondsFSinceUnixEpoch() * 1000);
	details->Set("resourceType", info->web_request_type);
	if (!info->response_ip.empty()) details->Set("ip", info->response_ip);
	if (info->initiator) details->Set("initiatorOrigin", info->initiator->Serialize());
	if (info->response_headers) {
	details->Set("fromCache", info->response_from_cache);
	details->Set("statusLine", info->response_headers->GetStatusLine());
	details->Set("statusCode", info->response_headers->response_code());
	details->Set("responseHeaders", HttpResponseHeadersToV8(info->response_headers.get()));
	}
	auto* render_frame_host = content::RenderFrameHost::FromID(info->global_id);
	if (render_frame_host) {
	details->SetGetter("frame", render_frame_host);
	auto* web_contents = content::WebContents::FromRenderFrameHost(render_frame_host);
	auto* api_web_contents = WebContents::From(web_contents);
	if (api_web_contents) {
	details->Set("webContents", api_web_contents);
	details->Set("webContentsId", api_web_contents->ID());
	}
	}
}

四个值得记住的点:

  • timestamp 是当前时间,不是请求开始时间。这个字段在 Chromium 里也是"事件触发时刻",用来算耗时,不是用来做请求 id 的。
  • frame 是 getter(SetGetter),不是值。每次读 details.frame 都会重新 FromID 一次。如果 frame 已经销毁,拿到的可能是 null。而 webContents 是值——创建 details 时就算好了。
  • ip 只在响应头存在之后才有(response_ip 来自 response info),所以 onBeforeRequest 里永远是 undefined。
  • initiatorOrigin 是"发起请求的源",跨重定向保持不变;referrer 相反,会被重定向改。注释特意强调:"unlike referrer, is not under the requesting document's control"——这是安全判断该用的字段。

17.4.7 两条路径:header client 与手动

这是全章最绕的一段,也是"为什么我的请求慢了一倍"的答案。

Chromium 有两种方式让 embedder 参与头处理:

  1. TrustedURLLoaderHeaderClient:在 URLLoaderFactoryParams 里挂一个 header_client,network service 会在发请求前和收到响应后回调它。这条路径不额外花一次 IPC,因为头处理发生在 network service 内部,回调是同一进程内的 mojo 调用。
  2. 手动路径:proxying 工厂自己构造请求、自己调 target_loader_->CreateLoaderAndStart,在前后插入事件。这条路径要两次往返(先给 browser 看头,再让 network 发)。

哪一个被选中,由这一行决定(proxying_url_loader_factory.cc:159):

	current_request_uses_header_client_ =
	factory_->url_loader_header_client_receiver_.is_bound() &&
	(for_cors_preflight_ || network_service_request_id_ != 0) &&
	has_any_extra_headers_listeners_;

三个条件:

  • header client 存在。它由 WillCreateURLLoaderFactory 的 header_client 出参决定,Electron 在 electron_browser_client.cc:1749 把 *header_client 的管道接管过来。
  • 不是 CORS preflight,或者 request id 非 0。preflight 是浏览器自动发的,不该让 JS 看见;request_id != 0 是"这个请求有一个能被 webRequest 认出来的身份"。
  • has_any_extra_headers_listeners_,它的定义在构造函数里:

proxying_url_loader_factory.cc:92-94

	has_any_extra_headers_listeners_(network_service_request_id != 0 &&
									factory->web_request_ &&
									factory->web_request_->HasListener())

也就是说:有监听器 + 请求 id 非 0 才启用 header client 模式。

请求 id 从哪来?renderer 发起的请求由 Chromium 分配(非 0);browser 进程发起的请求 id 是 0。这正是 SimpleURLLoaderWrapper::Start 里那段注释的用意:

	// Set a non-zero request ID so that the request can use the
	// TrustedHeaderClient code path for webRequest header modifications.
	// See proxying_url_loader_factory.cc for details.
	if (electron::IsBrowserProcess()) {
	loader_->SetRequestID(content::GlobalRequestID::MakeBrowserInitiated().request_id);
	}

net.request 本来会是 0,Electron 手动塞了一个"browser initiated"的 id 进去,让它也能走 header client 路径。如果不塞,net.request 改头会走手动路径——功能一样,多一次往返。

两条路径的行为差异不止性能:

header client手动
onBeforeSendHeaders 时机请求已在 network service 内部,头还没发请求还没进 network
改 URL通过 FollowRedirect 传新 URL直接改 request_.url
能否中途换 target factory不能能(override_target_factory_)
CORS preflight走专门分支,JS 看不到同
每次请求的额外往返02

这也是为什么 net.request 里那个 SetRequestID 是必要的:没有它,主进程发出的每个请求都会比 renderer 的请求慢一个来回。

17.4.8 认证:唯一会弹 UI 的事件

onAuthRequired 比其他事件多一层:它可能弹出一个系统对话框。

electron_api_web_request.cc:645-652

WebRequest::AuthRequiredResponse WebRequest::OnAuthRequired(
	const extensions::WebRequestInfo* request_info,
	const net::AuthChallengeInfo& auth_info,
	WebRequest::AuthCallback callback,
	net::AuthCredentials* credentials) {
	content::RenderFrameHost* rfh = content::RenderFrameHost::FromID(request_info->global_id);
	content::WebContents* web_contents = rfh ? content::WebContents::FromRenderFrameHost(rfh) : nullptr;
	...
	blocked_requests_[request_info->id].login_handler =
	std::make_unique<LoginHandler>(auth_info, web_contents, ...,
									request_info->url, response_headers,
									std::move(login_callback));
	return AuthRequiredResponse::AUTH_REQUIRED_RESPONSE_IO_PENDING;
}

LoginHandler 是 Chromium 的类,它知道怎么弹登录框。所以 onAuthRequired 的 callback(username, password) 有两个用途:给 JS 一个"自己处理"的机会,或者交给默认的对话框。

JS 侧对应的是 ClientRequest 的 login 事件(net-client-request.ts:498):

	this._urlLoader.on('login', (event, authInfo, callback) => {
	const handled = this.emit('login', authInfo, callback);
	if (!handled) {
		// If there were no listeners, cancel the authentication request.
		callback();
	}
	});

没有监听器就 callback()(空参数)——等价于"取消认证"。 这跟浏览器行为不同:浏览器会弹框,net.request 不会。这个设计是对的(主进程没有 UI 上下文),但很容易踩:一个需要 NTLM 认证的内网请求,用 net.request 发出去会直接 401,因为没人应。

17.4.9 WebSocket 是另一套状态机

webRequest 也管 WebSocket,但走的是完全独立的类:ProxyingWebSocket(461 行)。

入口在 ElectronBrowserClient::WillInterceptWebSocket / CreateWebSocket(electron_browser_client.cc:1602):

bool ElectronBrowserClient::WillInterceptWebSocket(content::RenderFrameHost* frame) {
	if (!frame) return false;
	auto* web_request = api::WebRequest::FromOrCreate(isolate, browser_context);
	bool has_listener = web_request->HasListener();
	...
	return has_listener;
}

只要有任何 webRequest 监听器,所有 WebSocket 都会被拦。 不是"只有 ws 类型的监听器才拦"——WillInterceptWebSocket 只看 HasListener(),没有按类型过滤。所以一个只监听 onCompleted 的 app,它的 WebSocket 握手也会多绕一圈。

ProxyingWebSocket 支持的事件比 HTTP 少:onBeforeRequest(可 cancel)、onBeforeSendHeaders、onHeadersReceived、onAuthRequired。不支持 onCompleted/onErrorOccurred——因为 WebSocket 建连成功后就是长连接,"完成"没有明确时刻。

它有一个 has_extra_headers_ 参数,而 Electron 传的是常量 true(:1661):

electron_browser_client.cc:1661-1665

	ProxyingWebSocket::StartProxying(
	web_request, std::move(factory), url, site_for_cookies, user_agent,
	std::move(handshake_client), true, frame->GetProcess()->GetDeprecatedID(),
	frame->GetRoutingID(), frame->GetLastCommittedOrigin(), browser_context,
	&next_id_);

所以 WebSocket 永远走 ContinueToStartRequest 分支(先让 network service 建握手,再在头阶段插事件),而不是"先给 JS 看再建连"。原因大概是 WebSocket 的握手没有"请求体",也不需要 onBeforeRequest 之外的预检——但代码里没有注释说明为什么写死 true。

17.4.10 五个真实陷阱

把上面这些压成可操作的清单:

  1. 注册监听器就改变拓扑。 HasListener() 为真后,所有 renderer subresource 从 kDirect/kObserve 变成 kProxy,请求开始走 UI 线程。这就是"加了 webRequest 之后页面变慢"的原因,不是回调本身慢。
  2. types: ['other'] 注册不上。 见 17.4.1,ParseResourceType 对 'other' 和未知字符串返回同一个值,都会被 != OTHER 的判断拒掉。
  3. onBeforeSendHeaders 是差分,删不掉看不见的头。 尤其 Cookie、Content-Length、Host——它们在 JS 拿到 details 时可能还不存在。
  4. onHeadersReceived 改 statusCode 无效。 要改状态码只能改 statusLine,且必须同时给 responseHeaders。
  5. net.request 默认不带 cookie。 见 17.6,除非传 useSessionCookies: true 或 credentials。

还有一条不算陷阱但值得记:webRequest 的 id 与 network_service_request_id 是两个不同的编号。 前者由 ProxyingURLLoaderFactory 的 request_id_generator_ 分配(每个 BrowserContext 一个递增序列),后者是 Chromium 的请求 id。映射表是 network_request_id_to_web_request_id_,在 CreateLoaderAndStart 里建立:

proxying_url_loader_factory.cc:913-914

	if (request_id)
	network_request_id_to_web_request_id_.emplace(request_id, web_request_id);

那个 if (request_id) 又回到了同一个问题:browser 进程发起的请求 id 是 0,不建映射。所以 net.request 请求在 webRequest 里的 id 与 network 层的 id 对不上——如果你同时在两边打日志,会发现它们永远是两套数字。

17.5 protocol:注册、拦截与静态目录

protocol 模块存在时间最长,也最混乱——它有三套语义不同、API 形状相似的机制,而文档把它们放在一页里。

17.5.1 三个动词,三套语义

ProtocolRegistry(protocol_registry.h)里是三个独立的 map:

	HandlersMap handlers_;            // register*Protocol
	HandlersMap intercept_handlers_;  // intercept*Protocol
	std::map<std::string, scoped_refptr<const ProtocolSource>, std::less<>> sources_;  // registerSource
注册(register)拦截(intercept)目录(source)
作用对象一个新的 scheme一个已有的 scheme一个新的 scheme
典型用法app:// 提供应用资源把远程 URL 映射到本地app:// 直接映射到磁盘目录
处理者JS 函数(主进程)JS 函数(主进程)C++(IO 线程,不开 JS)
能否处理内置 scheme取决于 Chromium 是否放行能(这就是用途)不能(显式拒绝)
每个请求的开销一次 JS 调用一次 JS 调用一次 open()

互斥关系写在两个入口里:

bool ProtocolRegistry::RegisterProtocol(ProtocolType type, const std::string& scheme,
										const ProtocolHandler& handler) {
	if (sources_.contains(scheme)) return false;
	return handlers_.try_emplace(scheme, type, handler).second;
}
bool ProtocolRegistry::RegisterSource(const std::string& scheme,
									scoped_refptr<const ProtocolSource> source) {
	if (IsBuiltinScheme(scheme) || handlers_.contains(scheme)) return false;
	return sources_.try_emplace(scheme, std::move(source)).second;
}

register 与 source 互斥(同一 scheme 只能有一个),但 intercept 与两者都不互斥:可以同时 registerProtocol('app', A) 和 interceptProtocol('app', B),此时拦截赢——因为拦截在工厂链的外层(17.4.7 的 override_target_factory)。

RegisterSource 额外拒绝内置 scheme,RegisterProtocol 不拒绝。这个不对称是有意的:注册一个与内置 scheme 同名的 handler,Chromium 根本不会把请求交给它(内置 scheme 有自己的 factory);而 source 会真的接管请求,必须拦住。

IsBuiltinScheme 的列表是 15 个(protocol_registry.cc:76):about、blob、data、file、filesystem、http、https、javascript、view-source、ws、wss、chrome、chrome-extension、chrome-untrusted、devtools。

还有第二份列表,在 electron_api_protocol.cc:213:

const char* const kBuiltinSchemes[] = { "about", "file", "http", "https", "data", "filesystem" };

只有 6 个,用于已弃用的 protocol.isProtocolHandled()。两份不一致——isProtocolHandled('blob') 返回 false,而 registerSource('blob', ...) 会被拒。

17.5.2 registerSchemesAsPrivileged:九个开关

必须在 app.ready 之前调用。SchemeOptions 有九个布尔值(:39):standard、secure、bypassCSP、allowServiceWorkers、supportFetchAPI、corsEnabled、stream、codeCache、allowExtensions。

打开之后世界变成什么样:

  • standard:app://host/path 按标准 URL 解析(有 host、有 path、支持相对路径、origin 是 app://host)。不开的话整个 app://foo/bar 是 opaque path,new URL() 拿不到 .host。绝大多数自定义协议都要开。
  • secure:当作安全上下文(isSecureContext === true),crypto.subtle、Service Worker、navigator.clipboard 才可用;代价是混合内容检查把它当 https。
  • bypassCSP:该 scheme 的资源不受页面 CSP 限制。这是安全风险:页面写了 script-src 'self' 也能加载 app://x/evil.js。
  • allowServiceWorkers:允许在该 scheme 下注册 SW,需配合 standard。
  • supportFetchAPI:fetch('app://...') 不会立刻抛 "URL scheme not supported"。只影响"允许发起",不影响 CORS(见 17.5.3)。
  • corsEnabled:该 scheme 进入 url::GetCorsEnabledSchemes(),跨源请求需要响应带 Access-Control-Allow-Origin。
  • stream:允许响应体是流(protocol.handle 返回的 Response.body 是 ReadableStream 时不报错)。
  • codeCache:允许 V8 code cache 在该 scheme 下工作。必须同时开 standard,否则抛错:

electron_api_protocol.cc:135-138

	if (custom_scheme.options.codeCache && !custom_scheme.options.standard) {
	thrower.ThrowError("Code cache can only be enabled when the custom scheme is "
						"registered as standard scheme.");
	return;
	}
  • allowExtensions:给该 scheme 加 extension 特权(url::AddExtensionScheme)。

名字先过 Browser::IsValidProtocolScheme,注释说明了原因:

	// Schemes are comma-separated for --*-schemes. Sanitize names so
	// extra commas don't trick child processes into splitting one
	// scheme into many.

因为 privileges 最终通过命令行传给子进程。九个开关各自对应一个开关名:

electron_api_protocol.cc:196-198

	AppendSchemesToCmdLine(electron::switches::kSecureSchemes, secure_schemes);
	AppendSchemesToCmdLine(electron::switches::kCORSSchemes, cors_schemes);
	AppendSchemesToCmdLine(electron::switches::kStandardSchemes, GetStandardSchemes());
	// 另有 bypassCSP / fetch / serviceWorker / extension / streaming / codeCache

为什么必须走命令行? 因为 renderer 里 url::AddStandardScheme 也要调一遍——URL 解析在 renderer 里发生,它必须知道这个 scheme 是 standard,而 renderer 不执行主进程 JS。electron_main_delegate.cc 在子进程启动时读这些开关再调一次。

这也解释了"必须在 app.ready 之前":命令行在进程启动时固定,ready 之后再改,browser 进程的 url:: 全局表能改,已经在跑的子进程改不了,于是主进程与 renderer 对同一个 URL 的解析不一致——最难查的一类 bug。

AddServiceWorkerScheme 里有个 hack:

electron_api_protocol.cc:106-108

void AddServiceWorkerScheme(const std::string& scheme) {
	// There is no API to add service worker scheme, but there is an API to
	// return const reference to the schemes vector.
	// If in future the API is changed to return a copy instead of reference,
	// the compilation will fail, and we should add a patch at that time.
	auto& mutable_schemes = const_cast<std::vector<std::string>&>(content::GetServiceWorkerSchemes());
	mutable_schemes.push_back(scheme);
}

const_cast 掉返回值再 push。注释承认是权宜之计,并指望"将来改成返回值时编译会失败"来提醒。

17.5.3 CORS:一个必须手工补的洞

这是本章技术上最有价值的一段。

Chromium 的 CORS 检查在 CorsURLLoaderFactory 里——network service 内部给每个 renderer 请求套的一层。但 Electron 的协议 handler 绕过了那一层:请求由 renderer 的 per-scheme factory 直接交给 ElectronURLLoaderFactory,根本不进 CorsURLLoader。

后果:https://evil.com 的页面 fetch('app://x/secret'),如果 app 注册了 supportFetchAPI: true 但没开 corsEnabled,请求成功、内容可读。这是跨源数据泄露。

补丁在 electron_url_loader_factory.cc:541:

	// Subresource requests for registered protocols reach this factory via the
	// renderer's per-scheme URLLoaderFactoryBundle entry, which bypasses the
	// network service's CorsURLLoaderFactory entirely. Replicate the
	// kCorsDisabledScheme gate from CorsURLLoader::StartRequest so a cross-origin
	// page cannot read responses from a scheme registered with
	// {supportFetchAPI: true} but without {corsEnabled: true}.
	if (IsCorsDisabledSchemeRequest(request)) {
	FailCorsDisabledSchemeRequest(std::move(client));
	return;
	}

判断本身抄自 CorsURLLoader::StartRequest(:398):

electron_url_loader_factory.cc:398-401

bool IsCorsDisabledSchemeRequest(const network::ResourceRequest& request) {
	// Browser-initiated requests have no initiator and are trusted.
	return request.request_initiator &&
		network::cors::ShouldCheckCors(request.url, request.request_initiator, request.mode) &&
		!std::ranges::contains(url::GetCorsEnabledSchemes(), request.url.GetScheme());
}

三个条件同时成立才算违规:有 initiator(网页发起)、ShouldCheckCors 为真(mode: no-cors、navigate 会跳过)、scheme 没注册 corsEnabled。

失败返回的是 CorsErrorStatus 而不是普通错误:

void FailCorsDisabledSchemeRequest(mojo::PendingRemote<network::mojom::URLLoaderClient> client) {
	mojo::Remote<network::mojom::URLLoaderClient>(std::move(client))
	->OnComplete(network::URLLoaderCompletionStatus(network::CorsErrorStatus(
		network::mojom::CorsError::kCorsDisabledScheme)));
}

这样 renderer 看到的是标准 CORS 错误(控制台那句 "Cross origin requests are only supported for protocol schemes..."),前端能用 try/catch 区分"CORS 拒绝"和"网络失败"。错误类型必须对。

ProtocolSourceURLLoaderFactory 里有同样一段(protocol_source.cc:146),两处独立实现,因为 registerSource 走另一个 factory。

还有一个相关的洞,补在"响应标记"上(:614):

electron_url_loader_factory.cc:623-625

	// For cross-origin no-cors loads (e.g. <img>, fetch({mode:'no-cors'})), the
	// body must not be script-readable; tag the response as opaque so Blink
	// applies opaque filtering.
	const bool tag_response_opaque = IsCrossOriginNoCorsRequest(request);
	if (tag_response_opaque)
	head->response_type = network::mojom::FetchResponseType::kOpaque;

no-cors 跨源请求允许发出,但响应必须是 opaque(body 不可读、status 恒 0)。正常路径下这是 CorsURLLoader 干的。

标记必须在正确的 head 上。string/buffer/stream 三种 sink 直接用传进来的 head,在这里打标记就够;file 和 http 会自己构造 head(file 从文件系统拿 mime,http 从上游转发),所以它们额外接一个 tag_response_opaque 参数,StartLoadingHttp 甚至专门套了一层过滤器:

	// URLPipeLoader forwards the upstream response head, which would drop the
	// opaque tag computed in StartLoading. Interpose so a cross-origin no-cors
	// load stays opaque.
	if (tag_response_opaque)
	client = OpaqueResponseFilter::Wrap(std::move(client));

OpaqueResponseFilter 是纯转发的 URLLoaderClient,只在 OnReceiveResponse 时改一个字段。为一个字段套一层 mojo 代理看着笨,但位置对——head 从上游来,改不了源头。

三处补同一个洞,说明这个洞是架构性的:一旦绕过 CorsURLLoader,它做的所有事都要手工补。CORS 检查是第一件,opaque 标记是第二件;将来 Chromium 给它加新职责,Electron 这边就会漏。这类"复制粘贴的安全检查"最容易腐化。

17.5.4 六种 sink

StartLoading(:581)拿到 JS 的返回值后按 ProtocolType 分派。前五种对应老的五个 register*Protocol,第六种 kFree 是 protocol.handle 用的,按返回值类型自己判断:

electron_url_loader_factory.cc:739-746

	api::SimpleURLLoaderWrapper* fetch_loader = nullptr;
	if (!dict.IsEmpty() && dict.Get("loader", &fetch_loader) && fetch_loader) {
		std::string prefix;
		if (data->IsArrayBufferView()) prefix.assign(node::Buffer::Data(data), node::Buffer::Length(data));
		StartLoadingRelay(..., fetch_loader, std::move(prefix));
	} else if (data->IsArrayBufferView()) { ... buffer ... }
	else if (data->IsString()) { ... string ... }
	else if (LooksLikeStream(args->isolate(), data)) { ... stream ... }
	else if (!dict.IsEmpty()) {
		if (GURL url; dict.Get("url", &url)) StartLoadingHttp(...);
		else if (base::FilePath path; dict.Get("path", &path)) StartLoadingFile(...);
		else OnComplete(..., ERR_FAILED);
	} else OnComplete(..., ERR_FAILED);

顺序是 loader → ArrayBufferView → string → stream → url → path。有实际影响:返回 { url, data } 的对象会被当成"有 data",url 被忽略。

ResponseMustBeObject(:93)是反向约束:kString/kFile/kFree 允许返回非对象(字符串就是 body,路径就是文件),其余三种必须返回对象。所以给 registerBufferProtocol 返回字符串得到 ERR_NOT_IMPLEMENTED——不是 ERR_FAILED,也不是异常。这个错误码极易被误读成"功能没实现",实际是"返回值类型不对"。

{ error } 是唯一能精确控制 renderer 看到什么错误的办法:

electron_url_loader_factory.cc:606-609

	int error_code;
	if (dict.Get("error", &error_code)) {
	OnComplete(std::move(client), request_id, network::URLLoaderCompletionStatus(error_code));
	return;
	}

error 是 net error 的负数(-6 = ERR_FILE_NOT_FOUND)。protocol.handle 的 JS 包装里就用它(ERR_FAILED、ERR_UNEXPECTED)。

还有一条注释解释了为什么不能抛异常:

	// Note that we should not throw JS error in the callback no matter what is
	// passed, to keep compatibility with old code.

handler 是异步调用的,此时 JS 栈已退出,抛异常没人接。所有错误必须通过 callback 的返回值表达。

17.5.5 重定向:必须手工重建 loader

从旧架构迁到 NetworkService 时最容易漏的一块。注释说得很清楚(:627):

	// Note that with NetworkService, sending the "Location" header no longer
	// automatically redirects the request, we have explicitly create a new loader
	// to implement redirection. This is also what Chromium does with WebRequest
	// API in WebRequestProxyingURLLoaderFactory.

实现分三个环节:

electron_url_loader_factory.cc:634-641

	if (head->headers->IsRedirect(&location)) {
	const auto first_party_url_policy =
		request.resource_type == static_cast<int>(blink::mojom::ResourceType::kMainFrame)
			? net::RedirectInfo::FirstPartyURLPolicy::UPDATE_URL_ON_REDIRECT
			: net::RedirectInfo::FirstPartyURLPolicy::NEVER_CHANGE_URL;
	net::RedirectInfo redirect_info = net::RedirectInfo::ComputeRedirectInfo(
		request.method, request.url, request.site_for_cookies, first_party_url_policy,
		request.referrer_policy, request.referrer.GetAsReferrer().spec(),
		request.request_initiator, head->headers->response_code(),
		request.url.Resolve(location),
		net::RedirectUtil::GetReferrerPolicyHeader(head->headers.get()), false);
	client_remote->OnReceiveRedirect(redirect_info, std::move(head));
	new RedirectedRequest(redirect_info, std::move(loader), request_id, options,
						request, client_remote.Unbind(), traffic_annotation,
						std::move(target_factory));
	return;
	}
  • 构造 RedirectInfo:first_party_url_policy 决定重定向后 first-party cookie 算谁——主 frame 导航会更新,子资源永远不变。这直接影响 SameSite 行为。
  • OnReceiveRedirect:通知客户端,然后等它调 FollowRedirect。客户端可能拒绝(redirect: 'manual'),那时这条链就结束。
  • RedirectedRequest:一个等待器,持着 loader 的 receiver,等 FollowRedirect 到来后用 target_factory 建新 loader 继续。

target_factory 是 this->Clone() 出来的(:557)——克隆自己。所以重定向后的请求还要再过一遍这个 handler。这就是自定义协议必须自己防"循环重定向"的原因:handler 返回 302 到自身 URL 会一直转下去。

RedirectedRequest 还有 OnTargetFactoryError(:486):新建 loader 失败时 DeleteThis() 并给客户端 ERR_ABORTED。不这么做,客户端会永远等 FollowRedirect 的回音。

17.5.6 stream:Node 流变成响应体

registerStreamProtocol 允许 handler 返回 Node Readable。这要把"推模型"(Node 流)和"拉模型"(mojo data pipe)接起来,还要处理背压和重入。

StartLoadingStream(:902)先用鸭子类型判断:

electron_url_loader_factory.cc:939-945

	gin_helper::Dictionary data = ToDict(dict.isolate(), stream);
	v8::Local<v8::Value> method;
	if (!data.Get("on", &method) || !method->IsFunction() ||
	!data.Get("removeListener", &method) || !method->IsFunction()) {
	mojo::Remote<network::mojom::URLLoaderClient>(std::move(client))
		->OnComplete(network::URLLoaderCompletionStatus(net::ERR_FAILED));
	return;
	}

有 on 和 removeListener 就当流。 任何带这两个方法的对象都会在 NodeStreamLoader 里被 read(),拿不到 Buffer 就永远等 readable。

管道大小按声明的 Content-Length 调(node_stream_loader.cc:61):

	// A declared Content-Length larger than mojo's 64 KB default grows the pipe
	// (up to the network service's default); it never shrinks it, since the
	// header may describe an encoded upstream body rather than this stream.
	const uint32_t pipe_size =
	head->content_length > kMojoDefaultPipeSize
		? base::saturated_cast<uint32_t>(std::min<int64_t>(
				head->content_length, network::GetDataPipeDefaultAllocationSize()))
		: 0;

CreateDataPipe(0, ...) = 用默认 64KB。"never shrinks" 是硬约束:Content-Length 描述的是编码后长度,实际流可能更长(gzip 解压),按它缩小会卡死。

难点在 ReadMore(:139):

node_stream_loader.cc:139-146

void NodeStreamLoader::ReadMore() {
	if (is_reading_) return;   // 重入保护
	is_reading_ = true;
	auto weak = weak_factory_.GetWeakPtr();
	v8::HandleScope scope(isolate_);
	v8::MaybeLocal<v8::Value> ret = node::MakeCallback(
	isolate_, emitter_.Get(isolate_), "read", 0, nullptr, {0, 0});
	DCHECK(weak) << "We shouldn't have been destroyed when calling read()";
	v8::Local<v8::Value> buffer;
	if (!ret.ToLocal(&buffer) || !node::Buffer::HasInstance(buffer)) {
	is_reading_ = false;
	if (has_read_waiting_) { has_read_waiting_ = false; ReadMore(); return; }
	readable_ = false;
	if (pending_result_) NotifyComplete(result_);
	return;
	}
	buffer_.Reset(isolate_, buffer);
	is_reading_ = false;  is_writing_ = true;
	producer_->Write(std::make_unique<mojo::StringDataSource>(...,
					mojo::StringDataSource::AsyncWritingMode::STRING_STAYS_VALID_UNTIL_COMPLETION),
				base::BindOnce(&NodeStreamLoader::DidWrite, weak));
}

四个坑,代码里都有痕迹:

  1. read() 会重入触发 readable:is_reading_ 挡嵌套,has_read_waiting_ 记住"还有一次待读"。
  2. read() 可能删除 this:注释 "ReadMore() may delete this, so it must be the last thing we do."——用户代码可能在里面 destroy()。所以每次 MakeCallback 后都 DCHECK(weak)。
  3. Buffer 必须持有到写完:buffer_.Reset(...) + STRING_STAYS_VALID_UNTIL_COMPLETION,否则 V8 GC 会在异步写完成前回收。
  4. 结束可能早于写完:NotifyComplete 里若 is_reading_ || is_writing_,只记 pending_result_,等写完再真完成。否则 OnComplete 会在最后一个数据块之前到达,客户端截断 body。

Start 里还有防"同步删除"的处理:

node_stream_loader.cc:86-91

	// Subscribing runs the emitter's "on" method, which may invoke the handler
	// synchronously and delete |this|, so check |weak| between each call.
	auto weak = weak_factory_.GetWeakPtr();
	On("end", base::BindRepeating(&NodeStreamLoader::NotifyEnd, weak));
	if (!weak) return;
	On("error", base::BindRepeating(&NodeStreamLoader::NotifyError, weak));
	if (!weak) return;
	On("readable", base::BindRepeating(&NodeStreamLoader::NotifyReadable, weak));

"挂监听器"这个动作就能销毁对象——JS 与 C++ 混编的反直觉点。

17.5.7 protocol.handle:一次到 C++ 的直通

protocol.handle 把六种返回类型收敛成一种:Response。JS 侧(protocol.ts:157):

	const register = isBuiltInScheme(scheme) ? this.interceptProtocol : this.registerProtocol;

内置 scheme 自动走 intercept。 这一行回答了长期困扰:protocol.handle('https', ...) 是注册还是拦截?内置的走拦截,自定义的走注册。

validateResponse 检查"长得对不对",不是"是不是真 Response":用 Object.hasOwn 而非 in(原型链上的 status 不算),用 webStreams().ReadableStream 而非全局(用户可能改全局)。

最有意思的是 relay 优化(:132):

// A Response that is still exactly what net.fetch produced (its body stream not
// read, locked, cloned or replaced) is relayed natively: ...
async function relayUntouchedFetch(res: Response) {
	const fetched = (res as any).__fetch;
	if (!fetched || res.body !== fetched.body || res.bodyUsed || res.body!.locked) return null;
	const urlLoader = fetched.request._urlLoader;
	if (!urlLoader) return null;
	urlLoader.hold();
	const reader = (res.body as ReadableStream<Uint8Array>).getReader();
	const prefix: Uint8Array[] = [];
	for (;;) {
	const next = await Promise.race([reader.read(), later()]);
	if (next === notYet) break;
	if (next.done) return { data: Buffer.concat(prefix) };
	prefix.push(next.value);
	}
	return { loader: urlLoader, data: Buffer.concat(prefix) };
}

场景:protocol.handle('app', req => net.fetch('https://cdn/' + req.url)) 代理远程资源。不优化时数据流是 "network → C++ → JS 流 → C++ data pipe → renderer",每个字节过两次 JS;优化后是 "network → C++ data pipe → renderer"。

三个条件同时满足才优化:__fetch 存在、res.body 还是原来那个流(没替换/没 clone/没 locked/没 bodyUsed)、_urlLoader 还在。

urlLoader.hold() 让 C++ 暂停把数据交给 JS,然后 JS 尽快把已在流内部缓冲的数据读出来当 prefix(Promise.race([reader.read(), later()]):read() 比一个 setImmediate 还慢就说明缓冲空了)。之后 C++ 把 prefix + 剩余数据直接写进 renderer 的 pipe。

微妙之处:已经流到 JS 的数据收不回来。所以优化不是"切模式",而是"截断 + 拼接"。任何在 handler 里读过 body 的代码(哪怕一个字节)都会让 relay 失效——bodyUsed/locked 变真。这是"看一眼就变慢"的真实例子。

17.5.8 asar:file 协议被整体替换

asar 不是"一个协议",而是替换 file:// 的 factory(protocol_registry.cc:26):

	if (electron::fuses::IsGrantFileProtocolExtraPrivilegesEnabled()) {
	auto file_factory = factories->find(url::kFileScheme);
	if (file_factory != factories->end()) {
	// If Chromium already allows file access then replace the url factory to
	// also loading asar files.
	file_factory->second = AsarURLLoaderFactory::Create();
	} else if (allow_file_access) {
	// Otherwise only allow file access when it is explicitly allowed.
	factories->emplace(url::kFileScheme, AsarURLLoaderFactory::Create());
	}
	}

三个分支:Chromium 已给 file factory(替换)、没给但允许访问(插入)、不允许(什么都不做)。注释里那句 "if asar support breaks in future, please check if Chromium has changed the call" 是维护者经验——这段依赖 Chromium 的调用顺序。

grant_file_protocol_extra_privileges fuse 关掉,asar 就不工作,app.asar 里的资源全部 404——"打包后白屏"的常见原因,而且不报错。

同一个 fuse 还控制导航路径(:53):file:///path/app.asar/index.html 需要走 CreateNonNetworkNavigationURLLoaderFactory,因为导航不走非网络 factory 的 map。

asar loader 本身(513 行)把 file:///x/app.asar/inside/path 拆成"归档路径 + 归档内路径",从归档里读出字节范围当文件返回,还要处理 mime(GetMimeTypeFromFile 对归档内路径不可靠,用 SniffMimeType 兜底)、range request、归档被删。

registerSource 复用了它:

protocol_source.cc:168-171

	network::ResourceRequest file_request = request;
	file_request.url = net::FilePathToFileURL(match->file);
	asar::CreateAsarURLLoader(file_request, std::move(loader), std::move(client),
							std::move(match->headers), match->real_root);

把自定义 scheme 的 URL 改写成 file:// 再交给 asar loader——一套实现同时支持普通目录和 asar 目录。

17.5.9 registerSource:不开 JS 的静态目录

它解决一个具体问题:用 protocol.handle 提供几千个静态文件时,每个请求都要过一次 JS。

一个 route 的形状(protocol_source.h:24):

	struct Route {
	std::optional<std::string> host;  // nullopt matches any host
	std::string path_prefix;          // always starts and ends with '/'
	base::FilePath root;
	base::FilePath real_root;         // `root` with links resolved
	std::string index;                // served for a path ending in '/', may be empty
	scoped_refptr<net::HttpResponseHeaders> headers;
	};

排序在 Create 里做(:196):"有 host 的优先,然后路径前缀长的优先",用 stable_sort 让同等优先级保持声明顺序。

Resolve 的安全防护有四处(:207):

protocol_source.cc:238-242

	rest = base::UnescapeBinaryURLComponent(rest);
	if (rest.find('\0') != std::string::npos || rest.find('\\') != std::string::npos)
	return std::nullopt;
	base::FilePath relative = base::FilePath::FromUTF8Unsafe(rest);
	if (relative.IsAbsolute() || relative.ReferencesParent()) return std::nullopt;
  1. \0 和 \ 直接拒:\0 会在 open() 时截断路径,\ 在 Windows 是分隔符、POSIX 是合法字符——统一拒绝避免平台差异。
  2. IsAbsolute() 拒:防止 rest 是 /etc/passwd 时 Append 变成绝对路径。
  3. ReferencesParent() 拒:防 ..。检查在 UnescapeBinaryURLComponent 之后,所以 %2e%2e%2f 也拦得住。
  4. real_root 做 confinement:解析 root 的真实路径(解开符号链接)传给 asar loader 做边界检查,这样 root 下指向外部的符号链接也逃不出去。

real_root 的注释解释了设计(:103):"Requests are confined to the directory root really is, so a link under it cannot lead elsewhere",并补了一句 "except on Windows"——Windows 的 8.3 短名、junction、大小写让 NormalizeFilePath 与 asar 归档查找用的路径可能不一致,所以 Windows 上 root 保持原样、只把 real_root 用于边界检查。

只接受 GET/HEAD(:155),其余返回 ERR_FILE_NOT_FOUND 而不是 405——URLLoader 层没有"状态码",错误只能表达成 net error。

响应头每个请求拷一份(:236):

	// The loader adds Content-Type etc. to what it is given; hand it a copy.
	return Match{route.real_root, route.root.Append(relative),
				base::MakeRefCounted<net::HttpResponseHeaders>(route.headers->raw_headers())};

HttpResponseHeaders 是引用计数的,多个请求共享一份会出问题(loader 会往里 AddHeader 加 Content-Type/Content-Length)。

与 protocol.handle 的取舍:

protocol.handleregisterSource
每个请求一次 JS 调用 + 序列化一次 open() + 发送
动态生成内容能不能
鉴权能(handler 里判断)不能(无 JS 入口)
适合API 路由、动态内容前端静态资源

两者不能共用一个 scheme:RegisterSource 会因为 handlers_.contains(scheme) 返回 false。所以要么两个 scheme(app-assets:// 给 source,app:// 给 handle),要么一个 scheme 全走 handler、静态目录也由 handler 内部转给 net.fetch('app-assets://...')。

17.6 net 模块:一条不经过 renderer 的路

net.request 是 Electron 里最"不像 Electron"的 API:它完全在主进程跑,没有 renderer、没有 frame、没有 WebContents。这带来两个后果——它不能用 session 的 cookie(默认)、也不能触发需要 frame 的事件(onAuthRequired 的默认行为),但它能用 webRequest(走 proxying 工厂)。

17.6.1 三层结构

net 模块的实现分三层:

lib/browser/api/net.ts            入口,检查 app.isReady
lib/common/api/net-client-request.ts   ClientRequest(Writable)+ IncomingMessage(Readable)
shell/common/api/electron_api_url_loader.cc   SimpleURLLoaderWrapper(C++,包 network::SimpleURLLoader)

入口只有 33 行(lib/browser/api/net.ts:1):

function request(options, callback?) {
	if (!app.isReady()) {
	throw new Error('net module can only be used after app is ready');
	}
	return new ClientRequest(options, callback);
}
function fetch(input: RequestInfo, init?: RequestInit): Promise<Response> {
	return session.defaultSession.fetch(input, init);
}

net.fetch 就是 session.defaultSession.fetch,没有别的。而 session.fetch 是 Session.prototype 上挂的(session.ts:41):

Session.prototype.fetch = function (input: RequestInfo, init?: RequestInit) {
	return fetchWithSession(input, init, this, net.request);
};

所以 net.fetch、session.fetch、protocol.handle 里的 net.fetch 是同一份实现,只是传的 session 不同。

resolveHost 同理,转给 session.defaultSession.resolveHost——所以 net.resolveHost 不能指定 session,永远用默认分区的 DNS。

17.6.2 ClientRequest 是一个 Writable

ClientRequest extends Writable(net-client-request.ts:333)。这个选择决定了 body 的处理方式:你可以 write() 多次,end() 一次,Node 的流机制负责缓冲与背压。

三种 body 策略,取决于你怎么写:

策略一:不设 chunkedEncoding,直接 write。 所有分片进 SlurpStream(:125):

net-client-request.ts:126-133

class SlurpStream extends Writable {
	_chunks: Buffer[] = [];
	_write(chunk: Buffer, encoding: string, callback: () => void) {
	// Copy the chunk: the write callback below tells the caller it may reuse or
	// mutate the buffer, but the body is not concatenated until data() is called.
	this._chunks.push(Buffer.from(chunk));
	callback();
	}
	data() {
	const data = this._chunks.length === 1 ? this._chunks[0] : Buffer.concat(this._chunks);
	this._chunks = [];
	return data;
	}
}

注释点出了关键:_write 的 callback() 一调,调用方就可以复用或改写那块 Buffer。所以必须 Buffer.from(chunk) 拷贝一份。忘了拷贝会出现"body 内容随机错乱"——因为上游把 Buffer 回收后重用了。

end() 时把整个 body 交给 C++:

net-client-request.ts:427-429

	this._body.on('finish', () => {
		this._urlLoaderOptions.body = (this._body as SlurpStream).data();
		this._startRequest();
	});

整个 body 在内存里。 传 1GB 就是 1GB 内存 + 一次 concat 拷贝(2GB 峰值)。这是 net.request 不适合大上传的原因。

策略二:chunkedEncoding = true。 body 进 ChunkedBodyStream(:137),它把第一次 write 当成"开始请求"的信号:

net-client-request.ts:154-160

	_write(chunk: Buffer, encoding: string, callback: () => void) {
	if (this._downstream) {
	this._downstream.write(chunk).then(callback, callback);
	} else {
	// the contract of _write is that we won't be called again until we call
	// the callback, so we're good to just save a single chunk.
	this._pendingChunk = chunk;
	this._pendingCallback = callback;
	// The first write to a chunked body stream begins the request.
	this._clientRequest._startRequest();
	}
	}

this._downstream 是一条 NodeJS.DataPipe,由 C++ 在请求建好后交过来(startReading(pipe))。在此之前只缓存一个 chunk——因为 _write 的契约是"不调 callback 就不会再被调用",所以最多只有一个在飞。

chunkedEncoding 的 setter 有三重保护:

	set chunkedEncoding(value: boolean) {
	if (this._started) throw new Error('chunkedEncoding can only be set before the request is started');
	if (typeof this._chunkedEncoding !== 'undefined') throw new Error('chunkedEncoding can only be set once');
	...

"只能设一次"是因为它决定了 body 走哪条路,中途改会让已经在缓冲的数据无处可去。

策略三:C++ 侧的数据管道。 JSChunkedDataPipeGetter(electron_api_url_loader.cc:234)实现 network::mojom::ChunkedDataPipeGetter,让 network service 按需从 JS 拉数据。注释里有一句:

	// The network stack wants the body again (e.g. a 307/308 redirect or a
	// replay), so ...

也就是说,重定向后 network service 会重新要一遍 body——如果 body 是一条只能读一次的管道,重定向就会失败。这是 307/308 保留方法的代价,net.request 对此没有额外处理。

17.6.3 默认不带 cookie

这是 net.request 最容易被踩的行为。看 Create 里这段(:811):

	const bool use_session_cookies = opts.ValueOrDefault("useSessionCookies", false);
	int options = network::mojom::kURLLoadOptionSniffMimeType;
	if (!credentials_specified && !use_session_cookies) {
	// This is the default case, as well as the case when credentials is not
	// specified and useSessionCookies is false. credentials_mode will be
	// kInclude, but cookies will be blocked.
	request->credentials_mode = network::mojom::CredentialsMode::kInclude;
	options |= network::mojom::kURLLoadOptionBlockAllCookies;
	}

credentials_mode = kInclude 但同时 kURLLoadOptionBlockAllCookies。这个组合看起来自相矛盾,实际上是"让 cookie 相关的语义正常(比如 SameSite 检查会执行),但不真的读写 cookie"。

三种情况会改变它:

  • 传了 credentials: 'include' → credentials_specified = true,不加 BlockAllCookies,发送并接收 cookie。
  • 传了 credentials: 'omit' → 同样 credentials_specified,但 mode 是 kOmit,cookie 被显式排除。
  • 传 useSessionCookies: true → 不加 BlockAllCookies,用 session 的 cookie。

所以"net.request 不带 cookie"只对默认参数成立。文档里那句 "By default, requests made with this API do not use the session's cookies" 是对的,但它没说清 credentials: 'include' 就能打开。

17.6.4 请求 id 与 raw headers

两处"为了让 net 模块能进同一条链"的改动。

请求 id(:560):

	// Set a non-zero request ID so that the request can use the
	// TrustedHeaderClient code path for webRequest header modifications.
	// See proxying_url_loader_factory.cc for details.
	if (electron::IsBrowserProcess()) {
	loader_->SetRequestID(content::GlobalRequestID::MakeBrowserInitiated().request_id);
	}

不设的话 id 是 0,has_any_extra_headers_listeners_ 为假,webRequest 改头会退化到"两次往返"的手动路径(17.4.7)。

raw headers(构造函数末尾):

	// Chromium filters headers using browser rules, while for net module we have
	// every header passed. The following setting will allow us to capture the
	// raw headers in the URLLoader.
	request_->trusted_params->report_raw_headers = true;

report_raw_headers 让 URLLoader 返回未经过滤的响应头。Chromium 默认会剥掉一批"不该给 renderer 看"的头(Set-Cookie、Proxy-Authenticate 等),主进程没有这个限制,所以要显式打开。

打开之后 IncomingMessage.headers 的组装也要跟上(net-client-request.ts:61):

	get headers() {
	const filteredHeaders: Record<string, string | string[]> = {};
	const { headers, rawHeaders } = this._responseHead;
	for (const [name, values] of Object.entries(headers)) {
	filteredHeaders[name] = discardableDuplicateHeaders.has(name) ? values[0] : values.join(', ');
	}
	const cookies = rawHeaders.filter(({ key }) => key.toLowerCase() === 'set-cookie').map(({ value }) => value);
	if (cookies.length) filteredHeaders['set-cookie'] = cookies;
	return filteredHeaders;
	}

两套规则:discardableDuplicateHeaders(Node 规定只保留第一个值的头,如 content-type、content-length、host)取 values[0];其余用 join(', ')。而 set-cookie 必须是数组,且必须从 rawHeaders 里取(因为 headers 里的已经被 join 过,多个 cookie 会粘成一条)。

这份 discardableDuplicateHeaders 是从 Node 的 _http_incoming.js 抄的,21 项。它保证 net.request 的 res.headers 与 http.request 的形状一致——这让"从 http 迁移到 net"成为可能。

17.6.5 重定向的三种策略

redirect: 'follow' | 'error' | 'manual',实现是 _startRequest 里的一个监听器(:487):

	this._urlLoader.on('redirect', (event, redirectInfo, headers) => {
	const { statusCode, newMethod, newUrl } = redirectInfo;
	if (this._redirectPolicy === 'error') {
		this._die(new Error("Attempted to redirect, but redirect policy was 'error'"));
	} else if (this._redirectPolicy === 'manual') {
		let _followRedirect = false;
		this._followRedirectCb = () => { _followRedirect = true; };
		try {
		this.emit('redirect', statusCode, newMethod, newUrl, headers);
		} finally {
		this._followRedirectCb = undefined;
		if (!_followRedirect && !this._aborted) {
			this._die(new Error('Redirect was cancelled'));
		}
		}
	} else if (this._redirectPolicy === 'follow') {
		// Calling followRedirect() when the redirect policy is 'follow' is
		// allowed but does nothing. (Perhaps it should throw an error
		// though...? Since the redirect will happen regardless.)
		try {
		this._followRedirectCb = () => {};
		this.emit('redirect', statusCode, newMethod, newUrl, headers);
		} finally {
		this._followRedirectCb = undefined;
		}
	}

三种策略的实现方式完全不同:

  • error:直接 _die。请求终止,error 事件带一句人话。
  • manual:同步判断你有没有调 followRedirect()。this._followRedirectCb 是一个"标志设置器",emit('redirect') 是同步的,所以监听器里必须同步调 followRedirect()——异步调(比如 setTimeout(() => req.followRedirect()))会先走 finally,判定为"取消",请求被杀。
  • follow:什么都不做,C++ 侧会自动跟随(redirectPolicy 传给 C++,SimpleURLLoader 的内建重定向)。

注释里那个 "(Perhaps it should throw an error though...? Since the redirect will happen regardless.)" 是作者的自我怀疑:follow 模式下调 followRedirect() 没有意义,但也不报错。

followRedirect() 本身的实现只有 5 行:

	followRedirect() {
	if (this._followRedirectCb) {
	this._followRedirectCb();
	} else {
	throw new Error('followRedirect() called, but was not waiting for a redirect');
	}
	}

"不在等重定向"时抛错——包括 follow 模式之外、以及在 redirect 事件之外调用的所有情况。

17.6.6 _die:一个被 Node 流语义逼出来的补丁

	_die(err?: Error) {
	// Node.js assumes that any stream which is ended is no longer capable of emitted events
	// which is a faulty assumption for the case of an object that is acting like a stream
	// (our urlRequest). If we don't emit here, this causes errors since we *do* expect
	// that error events can be emitted after urlRequest.end().
	if ((this as any)._writableState.destroyed && err) {
	this.emit('error', err);
	}
	this.destroy(err);
	if (this._urlLoader) {
	this._urlLoader.cancel();
	if (this._response) this._response.destroy(err);
	}
	}

注释说的是一件事:Node 的 Writable 认为 end() 之后不会再有问题,但 ClientRequest 不是真的流——它只是"表现得像流"。end() 只是把 body 交出去,网络错误还在后面。此时 destroy() 不会再发 error,所以要手动 emit。

条件 _writableState.destroyed && err 很精确:只在"流已经销毁"且"有错误"时才手动发。否则交给 destroy(err) 正常处理。

17.6.7 net.fetch 是适配层,不是新实现

fetchWithSession(net-fetch.ts:22)做的事情是:把 WHATWG 的 Request/Response 翻译成 ClientRequest/IncomingMessage,或者反过来。

请求方向:

	const r = request(allowAnyProtocol({
	session, method: req.method, url: req.url, origin, credentials,
	cache: req.cache, referrerPolicy: req.referrerPolicy, redirect: req.redirect
	}));

allowAnyProtocol 是个 symbol 标记(kAllowNonHttpProtocols),让 ClientRequest 跳过 "only supports http: and https:" 的检查——因为 fetch('app://...') 需要访问自定义协议。这个标记不通过公开 API 暴露,只在内部用。

几个必须做的适配:

  • credentials: 'same-origin' 且没有 origin 时降级为 'include',因为 C++ 侧对 same-origin 要求 origin 非空。
  • mode 通过 Sec-Fetch-Mode 头传递,而不是一个独立参数:

net-fetch.ts:103-104

	if (req.mode && (req.mode !== 'cors' || origin)) {
	r.setHeader('Sec-Fetch-Mode', req.mode);
	}

cors 模式在没有 origin 时不设——因为主进程请求没有 initiator,设了反而会让 C++ 侧的校验失败。

  • body 用 pipeTo(Writable.toWeb(r)) 流式写入:
	// Writable.toWeb() has a measurable per-call cost, so only call it when there is a body.
	if (req.body) {
	req.body.pipeTo(Writable.toWeb(r as any)).then(() => r.end());
	} else {
	r.end();
	}

注释里那句 "measurable per-call cost" 说明这里被测过。没有 body 时直接 end(),避免构造一个 Web 流。

响应方向:

	const nullBodyStatus = [101, 204, 205, 304];
	const body = nullBodyStatus.includes(resp.statusCode) || req.method === 'HEAD'
		? null
		: (Readable.toWeb(resp as any) as ReadableStream);

101/204/205/304 不能有 body——这是 fetch 规范的要求,new Response(body, {status: 204}) 会直接抛错。HEAD 同理。

然后是两个私有字段:

	(rResp as any).__original_resp = resp;
	if (body) (rResp as any).__fetch = { request: r, body: rResp.body };

__original_resp 给 protocol.handle 取 mimeType 用(res.__original_resp?._responseHead?.mimeType),__fetch 给 relay 优化用(17.5.7)。两个都是"内部协议"——用双下划线前缀表示"不要碰"。

最后一个细节:fetch 的 abort。

	req.signal.addEventListener('abort', () => {
	locallyAborted = true;
	const error = (req.signal as any).reason ?? new DOMException('The operation was aborted.', 'AbortError');
	p.reject(error);
	...
	r.abort();
	}, { once: true });

abort 时先 reject promise(带 signal.reason,支持 AbortController.abort(customReason)),再 r.abort()。顺序不能反——r.abort() 会触发 error 事件,那个监听器也会 p.reject,但 promise 只能 reject 一次,第一次赢。所以先 reject 能保证调用方拿到的是 AbortError 而不是底层的 net::ERR_ABORTED。

17.7 证书、代理、DNS:三块独立的老系统

17.7.1 自定义证书校验

session.setCertificateVerifyProc(proc) 让 JS 接管证书校验。链路是三段:

session.cc:855

void Session::SetCertVerifyProc(v8::Local<v8::Value> val, gin::Arguments* args) {
	CertVerifierClient::CertVerifyProc proc;
	if (!(val->IsNull() || gin::ConvertFromV8(args->isolate(), val, &proc))) {
	args->ThrowTypeError("Must pass null or function");
	return;
	}
	mojo::PendingRemote<network::mojom::CertVerifierClient> cert_verifier_client_remote;
	if (proc) {
	mojo::MakeSelfOwnedReceiver(
		std::make_unique<CertVerifierClient>(proc),
		cert_verifier_client_remote.InitWithNewPipeAndPassReceiver());
	}
	browser_context_->GetDefaultStoragePartition()
	->GetNetworkContext()
	->SetCertVerifierClient(std::move(cert_verifier_client_remote));
}

MakeSelfOwnedReceiver 表示这个对象由 mojo 管道自己持有——管道断开就销毁。所以传 null 就是"断开管道",恢复默认校验。

CertVerifierClient::Verify(cert_verifier_client.cc:26)把 Chromium 的校验结果打包给 JS:

	VerifyRequestParams params;
	params.hostname = hostname;
	params.default_result = net::ErrorToString(default_error);
	params.error_code = default_error;
	params.certificate = certificate;
	params.validated_certificate = default_result.verified_cert;
	params.is_issued_by_known_root = default_result.is_issued_by_known_root;
	cert_verify_proc_.Run(params, base::BindOnce(
	[](VerifyCallback callback, const net::CertVerifyResult& result, int err) {
		std::move(callback).Run(err, result);
	}, std::move(callback), default_result));

注意最后一个 lambda:它忽略了 JS 传回来的 result,只取 err,result 用 Chromium 原来的 default_result。所以 setCertificateVerifyProc 的回调只能改"通过/失败",不能改"证书链长什么样"。

这也解释了一个常见疑问:为什么 callback(0) 之后 webContents 里看到的证书信息还是原来的?因为 CertVerifyResult 没被替换。

JS 侧的 request 参数里,errorCode 是负数,default_result 是字符串(如 "net::ERR_CERT_AUTHORITY_INVALID")。要注意 callback(-3)(ERR_ABORTED)会取消请求而不是"校验失败"——两个语义完全不同的结果。

17.7.2 客户端证书

服务端要求客户端证书时,走的是另一个钩子:SimpleURLLoaderClient::OnCertificateRequested → SelectClientCertificateForResponder。它最终触发 app.on('select-client-certificate'),让 JS 从列表里挑一个。

这条路径对 net.request 和 renderer 请求都有效,但 net.request 没有 WebContents 上下文——事件里的 webContents 参数是 undefined。如果应用的事件处理器假设 webContents 一定存在,这里就会崩。

17.7.3 代理:一个串行的解析器

session.resolveProxy(url) 返回的是 PAC 字符串,不是"最终选的代理"。

ResolveProxyHelper(110 行)的实现有两个特点:

void ResolveProxyHelper::ResolveProxy(const GURL& url, ResolveProxyCallback callback) {
	pending_requests_.emplace_back(url, std::move(callback));
	if (!receiver_.is_bound()) {
	DCHECK_EQ(1u, pending_requests_.size());
	StartPendingRequest();
	}
}

串行。 同一时刻只有一个 LookUpProxyForURL 在飞,其余排队。原因是它只用一个 receiver_——receiver_.is_bound() 为真就说明有请求在进行。

	std::string proxy;
	if (proxy_info) proxy = proxy_info->ToPacString();

返回 PAC 字符串(如 "PROXY 127.0.0.1:7890;DIRECT"),而不是 ProxyInfo 里最终选中的那个。所以调用方要自己解析——这也是为什么 session.resolveProxy 的返回值在文档里被描述成 "The proxy settings for the given URL",而不是 "the proxy server"。

错误处理是"吞掉":

	receiver_.set_disconnect_handler(base::BindOnce(
	&ResolveProxyHelper::OnProxyLookupComplete,
	base::Unretained(this), net::ERR_ABORTED, std::nullopt));

管道断开当成"ERR_ABORTED + 空 proxy_info",最终回调拿到空字符串。net_error 参数在 OnProxyLookupComplete 里没有被使用——所以 resolveProxy 永远不会 reject,失败就是空串。

17.7.4 DNS:开着异步解析,但 DoH 是死的

SystemNetworkContextManager::OnNetworkServiceCreated(system_network_context_manager.cc:246):

	net::SecureDnsMode default_secure_dns_mode = net::SecureDnsMode::kOff;
	std::string default_doh_templates;
	net::DnsOverHttpsConfig doh_config;
	if (!default_doh_templates.empty() && default_secure_dns_mode != net::SecureDnsMode::kOff) {
	doh_config = *net::DnsOverHttpsConfig::FromString(default_doh_templates);
	}
	bool additional_dns_query_types_enabled = true;
	content::GetNetworkService()->ConfigureStubHostResolver(
	base::FeatureList::IsEnabled(net::features::kAsyncDns)
		? net::InsecureDnsMode::kEnabledBuiltIn
		: net::InsecureDnsMode::kDisabled,
	base::FeatureList::IsEnabled(net::features::kHappyEyeballsV3),
	default_secure_dns_mode, doh_config, additional_dns_query_types_enabled,
	{} /*fallback_doh_nameservers*/);

default_doh_templates 是局部空串,if 永远不成立。所以 DoH(DNS over HTTPS)在 Electron 里没有任何配置入口——它被编译进来了,但开关恒为关。

kAsyncDns 决定用内置异步解析器还是系统解析器(getaddrinfo)。这个 feature 默认开,所以 Electron 的 DNS 走 Chromium 自己的实现(支持并行 A/AAAA、Happy Eyeballs),而不是系统的阻塞式解析。这是"为什么 Electron 里 DNS 行为和浏览器一样、和 Node 不一样"的根源——同一个进程里,net.request 和 Node 的 dns.lookup 用的是两套解析器。

17.7.5 连接控制

session.preconnect({ url, numSockets }) 和 session.closeAllConnections() 是一对。

preconnect 走 PreconnectManager,它做的事是"提前建好 TCP + TLS 连接放在池子里"。注意它不预解析内容,只建连接——所以对"首字节延迟"有用,对"总加载时间"没用。

closeAllConnections 清空连接池。它的实际用途是"切换代理后强制重连":代理配置改了,但池子里的旧连接还连着旧代理。

session.clearAuthCache() 清 HTTP 认证缓存(Basic/NTLM/Negotiate 的凭据)。session.allowNTLMCredentialsForDomains(domains) 是它的配套——只有列在里面的域,NTLM 才会自动带上当前用户的凭据。

17.7.6 网络模拟

session.enableNetworkEmulation({ offline, latency, downloadThroughput, uploadThroughput }) 直接把参数翻译成 network::mojom::NetworkConditions:

void Session::EnableNetworkEmulation(const gin_helper::Dictionary& options) {
	auto network_conditions = network::mojom::MatchedNetworkConditions::New();
	network_conditions->conditions = network::mojom::NetworkConditions::New();
	options.Get("offline", &network_conditions->conditions->offline);
	options.Get("downloadThroughput", &network_conditions->conditions->download_throughput);
	options.Get("uploadThroughput", &network_conditions->conditions->upload_throughput);
	double latency = 0.0;
	if (options.Get("latency", &latency) && latency) {
	network_conditions->conditions->latency = base::Milliseconds(latency);
	}
	...
	network_context->SetNetworkConditions(network_emulation_token_, network_emulation_client_id_, std::move(matched_conditions));
}

两个 token 在构造函数里生成(:559):network_emulation_token_(谁设的条件)和 network_emulation_client_id_(条件作用于谁)。network service 用这对 token 做多客户端隔离——同一进程里多个 session 各自模拟互不干扰。

latency 的单位是毫秒(base::Milliseconds(latency)),而 downloadThroughput 是字节/秒。文档里写的 "in bytes per second" 是对的,但很多人按 "kbps" 填,结果慢了三个数量级。

17.8 四条通路的真实差异

前面七节把每个部件单独拆开了。这一节把它们放回同一张表上,因为工程里绝大多数网络问题,根源都是"用了 A 通路,却以为自己在 B 通路上"。

Electron 里发一个请求有四种写法:

入口代码位置网络身份有 frame有 initiator走 gate
renderer fetch / XHR / <img>页面代码该 session有有有(subresource)
net.request主进程session无无(除非设 origin)无
net.fetch主进程session无有(若带 origin)无
protocol.handle 内部 net.fetch主进程session无看代码无

四者共用同一个 NetworkContext——同一个 cookie store、同一个 HTTP 缓存、同一套代理与证书配置。差别只在"请求对象里填了哪些字段"。

17.8.1 cookie:三种命运,取决于 credentials 有没有被显式赋值

net.request 默认不带 cookie,这件事在 17.6.3 讲过。但"为什么 net.fetch 就带"这个问题的答案不在 cookie 代码里,在 electron_api_url_loader.cc:751:

bool credentials_specified =
	opts.Get("credentials", &request->credentials_mode);

credentials_specified 只反映"JS 有没有传这个字段"。而 net-fetch.ts:85 这一行,保证了它永远为真:

const credentials = req.credentials === 'same-origin' && !origin ? 'include' : req.credentials;

Request 的 credentials 有规范默认值 same-origin,适配层把它原样往下传,于是 opts.Get("credentials", ...) 必然成功,credentials_specified 必然为 true,electron_api_url_loader.cc:815 那个 BlockAllCookies 分支就永远进不去。

所以四种写法的 cookie 行为是:

  • net.request(url):不带。想带要写 useSessionCookies: true,或自己 setHeader('Cookie', ...),或先 session.cookies.set() 再 useSessionCookies。
  • net.fetch(url):带。因为适配层替你把 credentials 填上了。
  • renderer fetch(url):带(同源)。跨源要 credentials: 'include'。
  • protocol.handle 内部 fetch:看你自己怎么调;调 net.fetch 就带。

再往下还有一层更少人知道的东西。electron_api_url_loader.cc:679:

request->site_for_cookies = net::SiteForCookies::FromUrl(request->url);

site_for_cookies 是 SameSite 判定的"第一方"参照。这里直接用请求 URL 自己当第一方。这意味着从主进程发出的请求,对 cookie store 来说永远是"同站"的——SameSite=Strict 和 SameSite=Lax 的 cookie 都会被带上,无论它原本属于哪个域。

这不是 bug,是"浏览器-initiated 请求没有文档上下文"的必然结果:没有文档,就没有第一方,只能拿 URL 自己顶上。但它的后果很实在——主进程请求不会被 SameSite 挡住。所以"某些 cookie 在页面里发不出去、在主进程里能发出去"这种现象,原因不是权限,是 site_for_cookies。

renderer 发起的请求不吃这一套:它的 site_for_cookies 来自文档的 site,跨站请求带 Lax cookie 会被拦。这是同一个进程里两套语义的典型例子。

17.8.2 CORS:一套半实现

CORS 在 Chromium 里由 CorsURLLoaderFactory 在 network service 侧实现,它读 request_initiator、request.mode、request.credentials_mode 三个字段做判定。

Electron 的自定义协议走的是自己的 factory(17.5.8),绕过了 CorsURLLoaderFactory——这就是"洞"的来源。补丁只有一段,在 electron_url_loader_factory.cc:398:

bool IsCorsDisabledSchemeRequest(const network::ResourceRequest& request) {
	// Browser-initiated requests have no initiator and are trusted.
	return request.request_initiator &&
		network::cors::ShouldCheckCors(request.url, request.request_initiator, request.mode) &&
		!std::ranges::contains(url::GetCorsEnabledSchemes(), request.url.GetScheme());
}

第一个条件 request.request_initiator 是个短路开关。于是:

  • net.request:不传 origin → request_initiator 为空 → 短路 → 自定义 scheme 随便读。这就是"主进程里能读到、页面里读不到"的原因。
  • net.fetch:Request 带不带 origin 决定了它落在哪一边。自己 new Request 且没设 Origin 头时 origin 为 undefined,electron_api_url_loader.cc:688 不赋值,照样短路。一旦你手动 headers: { Origin: 'https://a.com' },net-fetch.ts:83 会把它取出来当 origin 传下去,短路失效,corsEnabled: false 的自定义 scheme 就会被这段补丁拒掉,返回 CorsErrorStatus。
  • renderer:一定带 initiator,一定被判定——但判定不是在这里做的,是 network service 的 CorsURLLoaderFactory 做的,两套判定并存。

第二个条件 ShouldCheckCors(...) 还要看 mode。mode 来自 opts.Get("mode", ...)(electron_api_url_loader.cc:697),而 net.fetch 把 mode 塞进了 Sec-Fetch-Mode 头(net-fetch.ts:104),没塞进 mode 字段。头是给服务端看的,字段是给 CORS 判定看的。所以 net.fetch({ mode: 'no-cors' }) 并不会让这段补丁放行——它只是让请求头里多一行。

一句话总结 CORS:renderer 走完整实现,主进程走一个"有 initiator 才生效"的补丁版。想让主进程请求被当浏览器请求对待,唯一手段是把 origin 填进去。

17.8.3 webRequest:两条通路,两种可见性

webRequest 能不能看到某个请求,取决于它走的是哪条插入点:

  • gate(URLLoaderFactoryGate):装在 WillCreateURLLoaderFactory 里,条件是 frame_host && type != kNavigation。所以它只看得见 renderer 的 subresource。导航看不见(17.3.4 讲过三条理由)。
  • header client(ProxyingURLLoaderFactory):靠 request_id 非 0 触发。所有走 SimpleURLLoader 且设了 id 的请求都有。

net.request 属于第二种。electron_api_net.cc 里创建 request 时的 SetRequestID(MakeBrowserInitiated())(17.4.7 提过)就是为了让它有 id。所以:

// 主进程,能收到事件
session.webRequest.onBeforeRequest({ urls: ['*://*/*'] }, (d, cb) => {
	console.log('seen', d.url); cb({});
});
net.request('https://example.com').end();  // → onBeforeRequest 触发

但 types 过滤对主进程请求没用:MakeBrowserInitiated() 造出来的类型不在那 12 个里头,ParseResourceType 落不到任何一项。urls 过滤仍然有效。

至于 protocol.handle 内部再发的请求:它用的是建 factory 时捕获的那个 factory_(17.5.7 的 this->Clone()),没有 frame_host,也没有 request_id——两条通路的入口判据都是空。所以在 handler 里发出去的请求,webRequest 看不到,你在 onBeforeRequest 里打日志会漏掉它们。这个结论是从两条判据推出来的,不是文档写的,但它和实际行为一致。

17.8.4 缓存、证书、代理:这三样是真的共享

前面三小节讲的都是"差异",容易给人一个错误印象:四条通路是四个独立世界。不是。它们共用 NetworkContext,所以这三样东西完全一致:

  • HTTP 缓存:同一个 http_cache_directory(17.2.3)。主进程 net.request 拿到的东西可能来自 renderer 刚刚填充的缓存条目,反之亦然。{ cache: false } 关的是整个 session 的缓存,不是某一次请求的。
  • 证书校验:setCertificateVerifyProc 装在整个 session 上(17.7.1),四条通路都吃。--ignore-certificate-errors 更狠,进程级。
  • 代理:setProxy 写的是 session 的 in_memory_pref_store(17.2.4),四条通路都走同一套解析。

这三样之所以一致,是因为它们都在 NetworkContext 这一层,而 NetworkContext 是"网络身份",不是"请求身份"。请求身份的差异,全部集中在 ResourceRequest 那几个字段上:request_initiator、mode、credentials_mode、site_for_cookies、request_id、frame_host。记住这六个字段,比记住任何一张表都有用——任何一个"为什么这个请求行为和那个不一样"的问题,答案都在这六个字段里。

17.8.5 选型

给一张可以直接照抄的判断表:

场景用哪个理由
页面里要发请求renderer fetch有 CORS 保护、有 cookie 语义、能被 webRequest 看到
主进程要抓页面抓不到的数据net.request无 CORS、无 SameSite、可控 header
主进程要一个 Response 对象net.fetch省掉手写流管道;注意它默认带 cookie
要接管某个 schemeprotocol.handle唯一的现代方案;registerFileProtocol 已废弃
要快速挂一个静态目录protocol.handle + 自己读文件,或 registerSourceregisterSource 只支持 GET/HEAD
要绕过自定义 handler 直接打网络net.fetch(url, { bypassCustomProtocolHandlers: true })否则会打到自己的 handler 上,递归

最后一行是真实事故:protocol.handle('http', ...) 里调 net.fetch(sameUrl),如果不加 bypassCustomProtocolHandlers,请求会回到自己的 handler,无限递归直到栈溢出。

17.9 十个常见误解

一、"net.request 会带 cookie"。不带。kInclude + kURLLoadOptionBlockAllCookies 的组合语义是"按 include 模式算,但在网络层把 cookie 全掐掉"。想带只有三条路:useSessionCookies: true、手动 Cookie 头、session.cookies.set() 配 useSessionCookies。

二、"protocol.handle 里先 await request.text() 再转发,效果一样"。效果差一个数量级。读 body 会让 urlLoader.hold() 那条 relay 优化失效(17.5.7 的三条件),请求退化成"先全量缓冲再发"。对小 POST 无所谓,对大上传是灾难。要么别读,要么明确接受这个代价。

三、"types: ['other'] 能监听主进程请求"。注册不上。ParseResourceType("other") 返回 OTHER,而更新 intercept state 的判据是 != OTHER(17.4.1),这条过滤器会被判成"无效过滤器"直接丢掉。而且 other 这个字符串本身就在那 12 项里,看起来完全合法——静态检查查不出来,只有运行起来发现"没反应"。

四、"onHeadersReceived 里改 statusCode 能改状态码"。不能。这个回调能改的只有 responseHeaders 和 statusLine。状态码藏在 statusLine 里,要改必须重组整行 HTTP/1.1 404 Not Found。给 statusCode 赋值会被静默忽略——回包结构里没有这个字段的写回路径。

五、"persist:Foo 和 persist:foo 是同一个分区"。代码上不是。PartitionKey 用原始字符串当 map 的 key(17.1.3),所以两个 key 造出两个 BrowserContext;但目录名走 MakePartitionName,里面有 ToLowerASCII,所以两个 BrowserContext 指向同一个磁盘目录。结果是两个独立的 cookie store 抢一份 Cookies SQLite 文件。这是本书里最值得记住的一个坑:不是"行为不一致",是"数据损坏风险"。

六、"registerSchemesAsPrivileged 之后页面就能跨源读这个协议"。不能,除非 corsEnabled: true 或 standard: true 且配了 CORS 头。而且这个函数必须在 app.ready 之前调用——它做的事是 url::Add*Scheme,改的是全局 scheme 注册表,晚了就只对之后创建的进程生效。

七、"session.resolveProxy(url) 返回最终的代理地址"。返回的是 PAC 决定串,形如 PROXY 1.2.3.4:8080 或 DIRECT。要拿真实代理得自己 parse。而且它永不 reject:ResolveProxyHelper 把错误吞了(17.7.3),网络出错时你拿到的是空串或 DIRECT,看不出失败。

八、"setProxy 一定能生效"。写的是 in_memory_pref_store。如果这个 session 的 pref store 是空的(例如 session.fromPath 造出来、没走 SessionPreferences 初始化的路径),setProxy 会静默 resolve,什么也不做。配置了代理但流量没走代理,先查这一条。

九、"setCertificateVerifyProc 能替换证书链"。它只能决定"过还是不过"。cert_verifier_client.cc 里的 lambda 忽略 JS 返回的 result 字段,只取 errorCode(17.7.1)。你可以拒绝一个合法证书,但不能把自签证书"改写成"合法链——要那样做只能整条链路绕开校验。

十、"在 utility process 里用 net 会自动共享主进程的 session"。不会。utility process 有独立的 URLLoaderBundle(17.0),要用哪个 session 得显式传。而且传给它的 session 必须先在主进程里创建好、且 webRequest 监听器也得在主进程注册——utility 侧注册的监听器不会影响主进程的请求。跨进程的"同一个 session"是同一个 NetworkContext,不是同一个 JS 对象。

这十条有个共同点:没有一条会报错。全部是静默失效、静默降级、或者静默错位。这也是为什么这一章要花两万多字去读源码——文档告诉你"有这个 API",源码才告诉你"它在什么条件下真的做了事"。

17.10 小结

回头看这一章的骨架,其实只有一句话:Electron 没有自己的网络栈。

它做的事,全都是在 Chromium 已有的工厂链上插一层:

  • URLLoaderFactory 可以级联,所以 Electron 能在 WillCreateURLLoaderFactory 里 Append() 一个 ProxyingURLLoaderFactory,把 webRequest 塞进去;
  • URLLoaderFactory 可以级联,所以自定义协议能用 ElectronURLLoaderFactory 顶掉 file://,还能在 handler 内部再 Clone() 一份去打真实网络;
  • URLLoaderFactory 可以级联,所以 gate 能在最外层做"看一眼或者拦一下"的路由;
  • 甚至 asar 也是同一个套路——一个替换 file:// 的 factory。

net.request 看起来最像"Electron 自己的东西",实际上它只是 SimpleURLLoader 的一层 JS 包装,请求照样从 NetworkContext 出去,照样能被 webRequest 看见,照样走同一套代理、证书、缓存。

所以真正需要记住的不是 API 清单,是那条链的形状:

renderer subresource
	→ URLLoaderFactoryGate          (看 / 拦)
	→ ProxyingURLLoaderFactory      (webRequest 阻塞)
	→ CorsURLLoaderFactory          (CORS)
	→ NetworkContext 的 URLLoaderFactory
	→ network service

和它的旁路:

net.request / net.fetch
	→ SimpleURLLoader(request_id 非 0)
	→ ProxyingURLLoaderFactory 的 header client 分支   (webRequest,只在有监听器时)
	→ NetworkContext 的 URLLoaderFactory

以及它的顶替:

my-scheme://...
	→ ElectronURLLoaderFactory(registerProtocol / handle / registerSource)
	→ 自己决定是读文件、还是 Clone 一份去打真实网络

三条链,一个出口。所有"为什么这个请求拦截不到"、"为什么那个 cookie 没带上"、"为什么这里 CORS 不生效"的问题,都是"请求走了哪条链"的问题。

下一章换一个方向:从网络回到界面,看 Electron 怎么把原生控件、菜单、托盘、拖放这些东西拼进一个 Chromium 窗口里,以及那些"看起来是 web、其实是原生"的边界到底在哪。

17.11 本章源码落点索引

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

  • 浏览器进程 C++ 层:proxying_url_loader_factory.h:41 electron_url_loader_factory.h:27 asar_url_loader_factory.cc:20 asar_url_loader_factory.h:13 url_loader_network_observer.cc:16 url_loader_network_observer.h:16 electron_api_web_request.h:20 asar_url_loader.cc:39
  •  asar_url_loader.h:14 network_context_service.h:16 network_context_service_factory.cc:14 network_context_service_factory.h:12 system_network_context_manager.h:18 electron_api_extensions.cc:27 electron_api_extensions.h:15 electron_api_cookies.cc:38
  •  electron_api_cookies.h:16 electron_api_protocol.h:19 save_page_handler.cc:15 save_page_handler.h:15 cookie_change_notifier.cc:17 cookie_change_notifier.h:14 electron_api_ipc_handler_impl.cc:24 electron_api_ipc_handler_impl.h:18
  •  electron_api_sw_ipc_handler_impl.cc:28 electron_api_sw_ipc_handler_impl.h:18 electron_web_contents_utility_handler_impl.cc:23 electron_web_contents_utility_handler_impl.h:15
  • 接口契约层:electron_api_url_loader.h:37
  • shell 其余实现:net_converter.h:17 function_template_extensions.h:22
  • 渲染进程 C++ 层:electron_extensions_renderer_api_provider.cc:20 electron_extensions_renderer_api_provider.h:12 electron_extensions_renderer_client.cc:14 electron_extensions_renderer_client.h:11
  • API 文档与类型:protocol-source.md:3