《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 里的 net | URLLoaderBundle(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>(...));
}
顺序有讲究:
AddDisposeObserver(this)——注册到 isolate 的销毁观察者列表,isolate 要死时会回调OnBeforeMicrotasksRunnerDispose(:1959),那里才真正断开与browser_context_的关系。也就是说Session 的生命周期比 BrowserContext 长,它必须能感知 isolate 的死亡。- 观察
DownloadManager——session.on('will-download')就是从这来的。Session 顺便当了下载事件的转发器。 SessionPreferences::CreateForBrowserContext——把session.setPreloads()那套 per-session 配置挂到 BrowserContext 的 user data 上(第 12 章讲过 preload 的五种来源)。Protocol::Create(isolate, browser_context->protocol_registry())——protocol 对象不是全局的,是每个 session 一个,但底层注册表属于 BrowserContext。所以session.defaultSession.protocol和session.fromPartition('x').protocol是两个 JS 对象、两张注册表。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));
}
先小写,再转义。 这带来两个可观察的后果:
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 同时是四样东西:
- BrowserContext 的 JS 门面(
browser_context_成员,1:1,通过 user data 双向索引)。 - 一组网络身份配置的容器(cache 大小、proxy、UA、SSL 配置、证书校验回调、网络模拟参数)——这些最终都写进 NetworkContext 的参数里。
- 六个子 API 的宿主(cookies / protocol / webRequest / netLog / serviceWorkers / extensions),每个都是"属于这个分区"的。
- 一个永不回收的 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 里有三个来源,优先级从低到高:
- 命令行
--proxy-server、--proxy-pac-url、--proxy-bypass-list。 session.setProxy({ mode, proxyRules, pacScript, proxyBypassRules })。- 运行时
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 的理由,代码里没写,但从结构上能推出来:
- 导航没有"高频直连"的收益。 一个页面一个导航,省一次线程跳转没有意义。
- 导航必须走 proxying。 即使没有
webRequest监听器,导航也要经过ProxyingURLLoaderFactory,因为onBeforeRequest之外还有navigation_ui_data、navigation_id这些只有 proxying 才处理的东西(electron_api_ipc_dispatch里 SW 的消息路由也依赖它)。 - 导航的 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);
三件事同时做:
- 暂停客户端管道。
proxied_client_receiver_是"renderer 那边发来的消息"的接收端(FollowRedirect、SetPriority),header_client_receiver_是 network service 发来的头处理请求。两个都Pause()——否则 JS 还没回答,renderer 已经在问下一个问题,状态会乱。 - 不调 continuation。
continuation被存进WebRequest::BlockedRequest,等 JS 回调触发。 - 返回。 控制权回到 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 抄了一份。
差分带来三个可观察的行为:
- 删不掉"JS 看不到的头"。 你没法通过"从对象里移除"来删
Cookie——它可能压根不在details.requestHeaders里。 - 改大小写不生效。
HasHeader是大小写不敏感的,但i.value() != old_headers->GetHeader(i.name())只比值。所以改'User-Agent'为'user-agent'不会算作修改(值相同),最终发的还是原来的名字。 - 顺序改了也无所谓。 差分是两个 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相反,会被重定向改。注释特意强调:"unlikereferrer, is not under the requesting document's control"——这是安全判断该用的字段。
17.4.7 两条路径:header client 与手动
这是全章最绕的一段,也是"为什么我的请求慢了一倍"的答案。
Chromium 有两种方式让 embedder 参与头处理:
TrustedURLLoaderHeaderClient:在URLLoaderFactoryParams里挂一个header_client,network service 会在发请求前和收到响应后回调它。这条路径不额外花一次 IPC,因为头处理发生在 network service 内部,回调是同一进程内的 mojo 调用。- 手动路径: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 看不到 | 同 |
| 每次请求的额外往返 | 0 | 2 |
这也是为什么 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 五个真实陷阱
把上面这些压成可操作的清单:
- 注册监听器就改变拓扑。
HasListener()为真后,所有 renderer subresource 从kDirect/kObserve变成kProxy,请求开始走 UI 线程。这就是"加了 webRequest 之后页面变慢"的原因,不是回调本身慢。 types: ['other']注册不上。 见 17.4.1,ParseResourceType对'other'和未知字符串返回同一个值,都会被!= OTHER的判断拒掉。onBeforeSendHeaders是差分,删不掉看不见的头。 尤其Cookie、Content-Length、Host——它们在 JS 拿到 details 时可能还不存在。onHeadersReceived改statusCode无效。 要改状态码只能改statusLine,且必须同时给responseHeaders。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));
}
四个坑,代码里都有痕迹:
read()会重入触发readable:is_reading_挡嵌套,has_read_waiting_记住"还有一次待读"。read()可能删除this:注释 "ReadMore() may deletethis, so it must be the last thing we do."——用户代码可能在里面destroy()。所以每次MakeCallback后都DCHECK(weak)。- Buffer 必须持有到写完:
buffer_.Reset(...)+STRING_STAYS_VALID_UNTIL_COMPLETION,否则 V8 GC 会在异步写完成前回收。 - 结束可能早于写完:
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;
\0和\直接拒:\0会在open()时截断路径,\在 Windows 是分隔符、POSIX 是合法字符——统一拒绝避免平台差异。IsAbsolute()拒:防止rest是/etc/passwd时Append变成绝对路径。ReferencesParent()拒:防..。检查在UnescapeBinaryURLComponent之后,所以%2e%2e%2f也拦得住。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.handle | registerSource | |
|---|---|---|
| 每个请求 | 一次 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 |
| 要接管某个 scheme | protocol.handle | 唯一的现代方案;registerFileProtocol 已废弃 |
| 要快速挂一个静态目录 | protocol.handle + 自己读文件,或 registerSource | registerSource 只支持 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