Electron.NET 请求拦截实战:用 WebRequest 拦截与改写 HTTP 请求
Electron.NET 请求拦截实战:用 WebRequest 拦截与改写 HTTP 请求
导读:
WebRequest是 Electron 会话(Session)提供的请求级拦截 API,允许你在请求生命周期的各个阶段监听、修改甚至取消网络请求。本文以 docs/API 体系下的 WebRequest 文档 为骨架,结合 Electron.NET 仓库的 C# 封装与 Electron Host 端 TypeScript 实现,带你掌握过滤器(filter)的 URL 匹配规则、8 个生命周期事件的触发时机与回调参数,并给出可直接落地的 C# 示例(如改写User-Agent、取消广告请求、重定向域名),帮助你为基于 ASP.NET Core 的桌面应用实现代理、调试与安全控制。
一、认识 WebRequest:拦截并改写请求的生命周期
WebRequest 类用于在请求生命周期的各个阶段拦截并修改请求内容(Intercept and modify the contents of a request at various stages of its lifetime)。
在 Electron 架构中,它运行在主进程(Main Process),并且不会从 'electron' 模块中导出——只能通过 Session 对象的 webRequest 属性访问。这一点在 Electron.NET 中同样成立:C# 侧的 WebRequest 实例由 Session 创建并暴露(见 Session.cs):
public WebRequest WebRequest { get; private set; }
internal Session(int id)
{
Id = id;
Cookies = new Cookies(id);
WebRequest = new WebRequest(id);
}
而从 WebContents 到 Session 的链路为:WebContents 内部维护 Session 属性(见 WebContents.cs):
internal WebContents(int id)
{
Id = id;
Session = new Session(id);
}
也就是说,在 Electron.NET 中,通过 BrowserWindow/WebContents 的 Session 属性即可拿到 WebRequest,进而注册拦截逻辑。
1.1 统一的调用范式:filter + listener
WebRequest 的所有方法都接受一个可选的 filter(过滤器)和一个 listener(监听器):
filter:包含一个urls数组(URL 模式列表),用于过滤掉不匹配的请求;如果省略filter,则匹配所有请求。listener:当事件发生时被调用,形式为listener(details),其中details描述该请求。- 部分事件(如
onBeforeRequest、onBeforeSendHeaders、onHeadersReceived)的listener还会收到一个callback,需要在处理完成后以response对象调用它。
⚠️ 关键约束:只有最后一个附着的 listener 会被使用。向 listener 传入 null 即可取消订阅该事件。
1.2 一次最经典的拦截改写:User-Agent
官方文档给出的第一个示例,就是为特定 URL 的请求改写 User-Agent 请求头:
const { session } = require('electron')
// Modify the user agent for all requests to the following urls.
const filter = {
urls: ['https://*.github.com/*', '*://electron.github.io/*']
}
session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {
details.requestHeaders['User-Agent'] = 'MyAgent'
callback({ requestHeaders: details.requestHeaders })
})
这段代码说明了两点核心用法:
filter.urls决定哪些请求会被捕获;onBeforeSendHeaders允许修改即将发送的请求头,然后通过callback把新的requestHeaders返回给 Electron 继续发送请求。
二、过滤器 filter:URL 模式匹配规则
filter 对象只有 urls 一个属性,值为 URL 模式(pattern)的数组。Electron 使用 Chromium 的 URL 匹配模式语法,官方文档给出以下合法示例:
'http://foo:1234/' // 精确匹配协议、主机与端口
'http://foo.com/' // 精确匹配主机
'http://foo:1234/bar' // 精确路径
'*://*/*' // 匹配任意协议、任意主机、任意路径(即全部请求)
'*://example.com/*' // 匹配 example.com 下的所有请求
'*://example.com/foo/*' // 匹配 example.com/foo/ 路径前缀
'http://*.foo:1234/' // 匹配 foo 的任意子域(*.foo)
'file://foo:1234/bar' // 也支持 file:// 协议
'http://foo:*/' // 通配端口
'*://www.foo.com/' // 通配协议但限定主机
要点归纳:
| 语法要素 | 含义 |
|---|---|
*:// |
匹配任意协议(http/https/ws/file 等) |
*.domain |
匹配该域名的任意子域 |
* 作为路径 |
匹配任意路径 |
:*/ |
匹配任意端口 |
file:// |
对本地 file:// 请求同样生效 |
三、8 个请求生命周期事件
WebRequest 实例方法全部遵循 webRequest.onXxx([filter, ]listener) 签名。下表汇总了 8 个事件的触发时机与回调能力:
| 方法 | 触发时机 | 回调能力 |
|---|---|---|
onBeforeRequest |
请求即将发生时 | 可取消(cancel)或重定向(redirectURL) |
onBeforeSendHeaders |
请求头可用、尚未发送任何 HTTP 数据时 | 可取消或改写 requestHeaders |
onSendHeaders |
请求即将发送给服务器时(只读) | 无,仅观察 |
onHeadersReceived |
收到 HTTP 响应头时 | 可取消或改写 responseHeaders、statusLine |
onResponseStarted |
响应体第一个字节到达时(只读) | 无,仅观察 |
onBeforeRedirect |
服务器发起的重定向即将发生时(只读) | 无,仅观察 |
onCompleted |
请求完成时(只读) | 无,仅观察 |
onErrorOccurred |
请求发生错误时(只读) | 无,仅观察 |
下面逐一展开每个事件。
3.1 webRequest.onBeforeRequest([filter, ]listener)
请求即将发生时触发,是拦截能力最强的事件之一。
details对象字段:idInteger:请求唯一标识urlstring:请求 URLmethodstring:HTTP 方法webContentsIdInteger(可选):发起请求的 WebContents 标识webContentsWebContents(可选)frameWebFrameMain(可选):请求所在的 FrameresourceTypestring:资源类型,取值可为mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket或otherreferrerstring:来源页timestampDouble:时间戳uploadData[UploadData[]]:上传数据数组(例如 POST body)
callback的response对象:cancelboolean(可选):设为true则取消该请求redirectURLstring(可选):阻止原请求发送/完成,改为重定向到给定 URL
应用场景:拦截广告请求、阻止危险域名、将特定资源重定向到本地缓存/代理。
3.2 webRequest.onBeforeSendHeaders([filter, ]listener)
在发送 HTTP 请求之前、请求头可用时触发。此时可能已建立 TCP 连接,但尚未发送任何 HTTP 数据。
details在onBeforeRequest的基础上额外包含:requestHeadersRecord<string, string>:即将发送的请求头
callback的beforeSendResponse对象:cancelboolean(可选)requestHeadersRecord<string, string | string[]>(可选):提供该字段时,请求将携带这些请求头发送
应用场景:改写 User-Agent、注入认证 Token、统一添加自定义请求头(即 1.2 节示例)。
3.3 webRequest.onSendHeaders([filter, ]listener)
在请求即将发送给服务器之前触发。此时,前一个 onBeforeSendHeaders 的修改结果已经可见。
details包含requestHeaders,但没有callback,只能观察、不能修改。
应用场景:最终确认发送的请求头集合,用于日志与审计。
3.4 webRequest.onHeadersReceived([filter, ]listener)
当 HTTP 响应头被收到时触发。
details在基础字段外包含:statusLinestring:状态行(如HTTP/1.1 200 OK)statusCodeInteger:状态码responseHeadersRecord<string, string[]>(可选):响应头
callback的headersReceivedResponse对象:cancelboolean(可选)responseHeadersRecord<string, string | string[]>(可选):提供该字段时,服务器被视为以这些头响应statusLinestring(可选):改写responseHeaders时应同时提供,用于修改状态行;否则沿用原响应头的状态
应用场景:改写响应头(如 CSP、X-Frame-Options、跨域头)、修正错误的状态码。
3.5 webRequest.onResponseStarted([filter, ]listener)
当响应体第一个字节到达时触发。对 HTTP 请求而言,此时状态行和响应头已经可用。
details包含responseHeaders、fromCache(是否来自磁盘缓存)、statusCode、statusLine。
应用场景:记录响应开始时间与状态,做性能埋点。
3.6 webRequest.onBeforeRedirect([filter, ]listener)
当服务器发起的重定向即将发生时触发。
details额外包含:redirectURLstring:重定向目标statusCode、statusLine:重定向响应信息ipstring(可选):请求实际发送到的服务器 IPfromCachebooleanresponseHeaders(可选)
应用场景:追踪 3xx 跳转链、发现盗链与劫持。
3.7 webRequest.onCompleted([filter, ]listener)
当请求完成时触发。
details包含responseHeaders、fromCache、statusCode、statusLine,以及errorstring(错误描述)。
应用场景:请求成功率统计、耗时汇总。
3.8 webRequest.onErrorOccurred([filter, ]listener)
当错误发生时触发。
details包含fromCache与errorstring(错误描述)。
应用场景:全局错误监控与上报。
四、Electron.NET 中的 C# 用法
文档本身给出的是原生 Electron JS 调用方式。在 Electron.NET 中,这些能力通过 C# 封装暴露。下面说明当前仓库中的实现状态与可用的 C# 写法。
4.1 从 Session 拿到 WebRequest
按 Session.cs 的公开属性,C# 侧访问路径为:
var session = Electron.WindowManager.BrowserWindows.First().WebContents.Session;
var webRequest = session.WebRequest;
Session 同时还提供了丰富的会话级能力(同文件 Session.cs),包括 Cookies、代理设置(SetProxyAsync)、网络模拟(EnableNetworkEmulation)、User-Agent 覆盖(SetUserAgent)等,可与 WebRequest 配合完成更完整的请求治理。
4.2 已实现的 onBeforeRequest 封装
仓库的 WebRequest.cs 提供了 OnBeforeRequest 的完整实现,签名如下:
public void OnBeforeRequest(
WebRequestFilter filter,
Action<OnBeforeRequestDetails, Action<object>> listener)
其中两个实体类型定义在同一文件中:
public class OnBeforeRequestDetails
{
public int Id { get; set; }
public string Url { get; set; }
public string Method { get; set; }
public int? WebContentsId { get; set; }
}
public class WebRequestFilter
{
public string[] Urls { get; set; }
}
典型的 C# 调用示例(拦截并取消对 https://ads.example.com/ 的请求):
webRequest.OnBeforeRequest(
new WebRequestFilter { Urls = new[] { "*://ads.example.com/*" } },
(details, callback) =>
{
var shouldCancel = details.Url.StartsWith("https://ads.example.com");
callback(new { cancel = shouldCancel });
});
4.3 底层桥接原理:C# 与 Electron 主进程如何协作
OnBeforeRequest 之所以能实现“C# 决定请求去留”,依赖 Electron.NET 的 Socket 桥接机制,其调用链在 WebRequest.cs 中清晰可见:
- 首次注册时,C# 通过
BridgeConnector.Socket.Emit("register-webContents-session-webRequest-onBeforeRequest", Id, filter)通知 Electron Host 注册拦截; - Electron Host 端 webContents.ts 调用
session.webRequest.onBeforeRequest(filter, ...),在请求到达时把details通过socket.emit("webContents-session-webRequest-onBeforeRequest{id}", details)回传 C#; - C# 反序列化
details为OnBeforeRequestDetails并触发托管事件; - C# 侧回调时,把
response通过BridgeConnector.Socket.Emit("webContents-session-webRequest-onBeforeRequest-response{id}", response)发回 Electron Host; - Electron Host 用
electronSocket.once(...)收到该响应后调用原生callback(response),请求据此被放行、取消或重定向。
// C# 端核心代码(摘自 WebRequest.cs)
BridgeConnector.Socket.On<JsonElement>($"webContents-session-webRequest-onBeforeRequest{Id}",
(args) =>
{
var details = args.Deserialize<OnBeforeRequestDetails>(ElectronJson.Options);
var callback = (Action<object>)((response) =>
BridgeConnector.Socket.Emit($"webContents-session-webRequest-onBeforeRequest-response{Id}", response));
_onBeforeRequest?.Invoke(details, callback);
});
同时支持 RemoveListener 取消订阅(WebRequest.cs):移除监听后若没有剩余订阅者,会调用 Socket.Off(...) 关闭对应事件通道,避免资源泄漏。
五、实战综合示例:请求治理组合拳
将各事件组合起来,即可构建一个完整的请求治理管道。以下示例演示在 Electron.NET 应用启动后,对 https://api.example.com/* 的请求统一注入 Token、改写响应头并记录日志:
var webRequest = Electron.WindowManager.BrowserWindows.First().WebContents.Session.WebRequest;
// 1) 发送前注入认证请求头
webRequest.OnBeforeSendHeaders(
new WebRequestFilter { Urls = new[] { "*://api.example.com/*" } },
(details, callback) =>
{
var headers = new Dictionary<string, string> { ["Authorization"] = "Bearer <token>" };
callback(new { requestHeaders = headers });
});
// 2) 响应头改写(同时提供 statusLine)
webRequest.OnHeadersReceived(
new WebRequestFilter { Urls = new[] { "*://api.example.com/*" } },
(details, callback) =>
{
callback(new
{
responseHeaders = new Dictionary<string, string> { ["X-Powered-By"] = "Electron.NET" },
statusLine = details.StatusLine
});
});
// 3) 错误监控
webRequest.OnErrorOccurred(
new WebRequestFilter { Urls = new[] { "*://*/*" } },
(details) =>
{
Console.WriteLine($"请求失败: {details.Url} -> {details.Error}");
});
注意:文档明确提示“只有最后一个附着的 listener 会被使用”,因此同一事件不要重复注册多个监听器;需要取消时传入
null或调用RemoveListener。
六、常见问题与注意事项
- 主进程限制:
WebRequest运行于主进程,需在 Electron.NET 的主进程上下文(OnReady回调等)中使用。 - Listener 唯一性:同一事件只保留最后一个
listener;重复注册会覆盖前一个。 - URL 过滤粒度:URL 模式匹配基于 Chromium 规则,
*通配符不能匹配路径中的/(需写成/*);调试时建议先用'*://*/*'观察全部请求,再逐步收窄。 - 改写响应头需带状态行:在
onHeadersReceived中提供responseHeaders时,应同时提供statusLine,否则沿用原状态。 - 取消订阅:传入
null可取消订阅;C# 侧也可调用RemoveListener主动解绑,避免回调通道残留。
七、延伸阅读
- WebRequest 文档原文:本主题的完整 API 参考;
- WebRequest.cs 实现:C# 侧
OnBeforeRequest封装与桥接事件; - Session.cs:
WebRequest的宿主类,以及 Cookies、代理、User-Agent 等配套会话能力; - WebContents.cs:通过
WebContents.Session获取Session实例的入口; - webContents.ts:Electron Host 端将 C# 调用映射到原生
session.webRequest的桥接代码; - WebContents 文档:包含
Session属性的使用说明与相关注意点。