Electron.NET 请求拦截实战:用 WebRequest 拦截与改写 HTTP 请求

原创2026-09-27 23:37:431,691 阅读
文章标签:桌面应用跨平台

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 })
})

这段代码说明了两点核心用法:

  1. filter.urls 决定哪些请求会被捕获;
  2. 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 对象字段:
    • id Integer:请求唯一标识
    • url string:请求 URL
    • method string:HTTP 方法
    • webContentsId Integer(可选):发起请求的 WebContents 标识
    • webContents WebContents(可选)
    • frame WebFrameMain(可选):请求所在的 Frame
    • resourceType string:资源类型,取值可为 mainFrame、subFrame、stylesheet、script、image、font、object、xhr、ping、cspReport、media、webSocket 或 other
    • referrer string:来源页
    • timestamp Double:时间戳
    • uploadData [UploadData[]]:上传数据数组(例如 POST body)
  • callback 的 response 对象:
    • cancel boolean(可选):设为 true 则取消该请求
    • redirectURL string(可选):阻止原请求发送/完成,改为重定向到给定 URL

应用场景:拦截广告请求、阻止危险域名、将特定资源重定向到本地缓存/代理。

3.2 webRequest.onBeforeSendHeaders([filter, ]listener)

在发送 HTTP 请求之前、请求头可用时触发。此时可能已建立 TCP 连接,但尚未发送任何 HTTP 数据。

  • details 在 onBeforeRequest 的基础上额外包含:
    • requestHeaders Record<string, string>:即将发送的请求头
  • callback 的 beforeSendResponse 对象:
    • cancel boolean(可选)
    • requestHeaders Record<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 在基础字段外包含:
    • statusLine string:状态行(如 HTTP/1.1 200 OK)
    • statusCode Integer:状态码
    • responseHeaders Record<string, string[]>(可选):响应头
  • callback 的 headersReceivedResponse 对象:
    • cancel boolean(可选)
    • responseHeaders Record<string, string | string[]>(可选):提供该字段时,服务器被视为以这些头响应
    • statusLine string(可选):改写 responseHeaders 时应同时提供,用于修改状态行;否则沿用原响应头的状态

应用场景:改写响应头(如 CSP、X-Frame-Options、跨域头)、修正错误的状态码。

3.5 webRequest.onResponseStarted([filter, ]listener)

当响应体第一个字节到达时触发。对 HTTP 请求而言,此时状态行和响应头已经可用。

  • details 包含 responseHeaders、fromCache(是否来自磁盘缓存)、statusCode、statusLine。

应用场景:记录响应开始时间与状态,做性能埋点。

3.6 webRequest.onBeforeRedirect([filter, ]listener)

当服务器发起的重定向即将发生时触发。

  • details 额外包含:
    • redirectURL string:重定向目标
    • statusCode、statusLine:重定向响应信息
    • ip string(可选):请求实际发送到的服务器 IP
    • fromCache boolean
    • responseHeaders(可选)

应用场景:追踪 3xx 跳转链、发现盗链与劫持。

3.7 webRequest.onCompleted([filter, ]listener)

当请求完成时触发。

  • details 包含 responseHeaders、fromCache、statusCode、statusLine,以及 error string(错误描述)。

应用场景:请求成功率统计、耗时汇总。

3.8 webRequest.onErrorOccurred([filter, ]listener)

当错误发生时触发。

  • details 包含 fromCache 与 error string(错误描述)。

应用场景:全局错误监控与上报。

四、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 中清晰可见:

  1. 首次注册时,C# 通过 BridgeConnector.Socket.Emit("register-webContents-session-webRequest-onBeforeRequest", Id, filter) 通知 Electron Host 注册拦截;
  2. Electron Host 端 webContents.ts 调用 session.webRequest.onBeforeRequest(filter, ...),在请求到达时把 details 通过 socket.emit("webContents-session-webRequest-onBeforeRequest{id}", details) 回传 C#;
  3. C# 反序列化 details 为 OnBeforeRequestDetails 并触发托管事件;
  4. C# 侧回调时,把 response 通过 BridgeConnector.Socket.Emit("webContents-session-webRequest-onBeforeRequest-response{id}", response) 发回 Electron Host;
  5. 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。

六、常见问题与注意事项

  1. 主进程限制:WebRequest 运行于主进程,需在 Electron.NET 的主进程上下文(OnReady 回调等)中使用。
  2. Listener 唯一性:同一事件只保留最后一个 listener;重复注册会覆盖前一个。
  3. URL 过滤粒度:URL 模式匹配基于 Chromium 规则,* 通配符不能匹配路径中的 /(需写成 /*);调试时建议先用 '*://*/*' 观察全部请求,再逐步收窄。
  4. 改写响应头需带状态行:在 onHeadersReceived 中提供 responseHeaders 时,应同时提供 statusLine,否则沿用原状态。
  5. 取消订阅:传入 null 可取消订阅;C# 侧也可调用 RemoveListener 主动解绑,避免回调通道残留。

七、延伸阅读

登录后查看全文
Electron.NET