Electron Referrer 对象详解：用 url 与 policy 字段精确控制 Referer 行为-北京尧图网络

Electron Referrer 对象详解用 url 与 policy 字段精确控制 Referer 行为【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electron本文基于 Electron 官方 API 文档中的 Referrer Object 结构定义系统讲解该对象的url、policy两个字段逐一解释 8 种Referrer-Policy取值的含义并结合 Electron C 源码中的字符串到net::ReferrerPolicy枚举的映射实现、loadURL的httpReferrer参数解析链路帮助你在主进程、webview、net请求等场景中精确控制请求的Referer头。什么是 Referrer 对象Referrer 是 Electron API 中的一个数据结构structure而不是可直接实例化的类。它成对描述一次导航或请求所使用的 HTTP Referrer即浏览器侧的Referer请求头来源urlstring — HTTP Referrer URL即作为来源页的完整 URLpolicystring — Referrer-Policy 策略值决定url在跨源、降级如https请求http等场景下以何种粒度完整 URL / 仅源 / 不发送出现在Referer请求头中。policy的合法取值为default、unsafe-url、no-referrer-when-downgrade、no-referrer、origin、strict-origin-when-cross-origin、same-origin、strict-origin。与纯字符串形式的 referrer 相比Referrer 对象的关键价值在于它把来源 URL和发送策略绑定在一起。只传一个 URL 字符串时策略只能走默认值而传入 Referrer 对象后Electron 会按你指定的策略在每次真实发出Referer头之前做裁剪。8 种 policy 取值含义速查取值行为摘要default使用默认策略不额外裁剪unsafe-url始终发送完整 URL即使从https降级到http也照常发送no-referrer-when-downgrade同源或https升https时发送完整 URL降级时不发送no-referrer永不发送Referer头origin只发送来源的源scheme host port不发送路径strict-origin-when-cross-origin同源请求发送完整 URL跨源只发送源降级请求不发送same-origin仅同源请求发送完整 URL跨源不发送strict-origin只发送源且仅在安全上下文如https到https下发送其中降级downgrade指从安全协议https转向非安全协议http的导航这也是多数strict-*/no-referrer-when-downgrade策略的核心判断条件。源码实现JS 字符串到 net::ReferrerPolicy 的映射Electron 在 V8 与 Chromium 网络栈之间通过 gin 的Converter完成字符串到枚举的转换。在 electron_api_url_loader.cc 中可以看到完整的映射表template struct Converternet::ReferrerPolicy { static bool FromV8(v8::Isolate* isolate, v8::Localv8::Value val, net::ReferrerPolicy* out) { using Val net::ReferrerPolicy; static constexpr auto Lookup base::MakeFixedFlatMapstd::string_view, Val({ {, Val::REDUCE_GRANULARITY_ON_TRANSITION_CROSS_ORIGIN}, {no-referrer, Val::NO_REFERRER}, {no-referrer-when-downgrade, Val::CLEAR_ON_TRANSITION_FROM_SECURE_TO_INSECURE}, {origin, Val::ORIGIN}, {origin-when-cross-origin, Val::ORIGIN_ONLY_ON_TRANSITION_CROSS_ORIGIN}, {same-origin, Val::CLEAR_ON_TRANSITION_CROSS_ORIGIN}, {strict-origin, Val::ORIGIN_CLEAR_ON_TRANSITION_FROM_SECURE_TO_INSECURE}, {strict-origin-when-cross-origin, Val::REDUCE_GRANULARITY_ON_TRANSITION_CROSS_ORIGIN}, {unsafe-url, Val::NEVER_CLEAR}, }); return FromV8WithLowerLookup(isolate, val, Lookup, out); } };从这段实现可以得到几个与文档对照后值得注意的事实strict-origin-when-cross-origin与空字符串映射到同一枚举REDUCE_GRANULARITY_ON_TRANSITION_CROSS_ORIGIN。也就是说 Chromium 的默认策略等价于strict-origin-when-cross-origin文档中列出的default语义在实现层面落到这一默认值上。映射表额外接受origin-when-cross-origin即源码侧支持的策略字符串比 Referrer 文档列出的 8 个还多一个文档中的 8 个取值是面向Referrer结构policy字段的正式声明。FromV8WithLowerLookup表明匹配是大小写不敏感的传入NO-REFERRER这类写法同样可以生效。枚举命名本身也直观体现了策略语义NEVER_CLEAR永不裁剪对应unsafe-url、CLEAR_ON_TRANSITION_FROM_SECURE_TO_INSECURE降级时清空对应no-referrer-when-downgrade、ORIGIN_ONLY_ON_TRANSITION_CROSS_ORIGIN等。另外electron_api_url_loader.cc 中fetch式请求的默认策略为blink::ReferrerUtils::GetDefaultNetReferrerPolicy()并支持从referrerPolicy选项覆盖而 system_network_context_manager.cc 中enable_referrers true说明 Electron 的系统网络上下文是开启 referrer 支持的策略裁剪才真正有意义。实战场景一loadURL 的 httpReferrer 参数Referrer对象最常见的入口是loadURL的options.httpReferrer其类型为string | Referrer。文档中以下位置均如此声明webContents.loadURLhttpReferrer(string | Referrer) (optional) - An HTTP Referrer url.win.loadURL 与webview.loadURLwebview-tag.md参数列表与webContents.loadURL一致httpReferrer、userAgent、extraHeaders、postData、baseURLForDataURL。在 electron_api_web_contents.cc 中可以看到两种入参的处理差异content::NavigationController::LoadURLParams params(url); if (!options.Get(httpReferrer, params.referrer)) { GURL http_referrer; if (options.Get(httpReferrer, http_referrer)) params.referrer content::Referrer(http_referrer.GetAsReferrer(), network::mojom::ReferrerPolicy::kDefault); }传入 Referrer 对象直接反序列化为content::Referrer你指定的policy会一路带到导航请求传入字符串先用GURL解析再包装为content::Referrer(url, ReferrerPolicy::kDefault)即策略固定为默认值。因此当你需要控制来源页是 A 但只暴露 origin这类行为时必须传对象而不是字符串mainWindow.loadURL(https://example.com/target, { httpReferrer: { url: https://mysite.com/checkout, policy: origin // 跨源时只发送 https://mysite.com } })仓库的 TypeScript 冒烟测试 main.ts 也验证了loadURL接受httpReferrer选项的类型签名mainWindow.loadURL(file://foo/bar, { userAgent: cool-agent, httpReferrer: greatReferrer }); mainWindow.webContents.loadURL(file://foo/bar, { userAgent: cool-agent, httpReferrer: greatReferrer });实战场景二did-create-window 事件中读取 referrer当页面调用window.open()时webContents的did-create-window事件的details中带有referrer字段其类型正是 Referrer 对象referrerReferrer - The referrer that will be passed to the new window. May or may not result in theRefererheader being sent, depending on the referrer policy.文档特别强调是否真的产生Referer头取决于其中的 policy——这正是把url与policy放一起表达的原因。典型用法是在自定义setWindowOpenHandler/ 监听did-create-window时根据来源页 URL 与策略做白名单校验mainWindow.webContents.on(did-create-window, (childWindow, details) { const { url, policy } details.referrer console.log(opened from ${url} with policy ${policy}) // 例如只有 policy 为 no-referrer 的来源才允许打开外链 })实战场景三context-menu 事件的 referrerPolicy 字段webContents与webview的context-menu事件参数中也带有referrerPolicy字段类型同为 Referrer 结构见 web-contents.md 与 webview-tag.md 的 context-menu 参数列表referrerPolicyReferrer - The referrer policy of the frame on which the menu is invoked.它反映的是右键所在 frame 当前生效的 referrer 策略。当你自定义右键菜单、需要在新窗口打开链接等功能时可以读取该字段判断当前页面的策略环境再决定后续导航携带怎样的 referrer。周边 API 中的 referrer 支持Referrer 对象之外Electron 还有几处相关能力可对照理解策略的实际作用点net.request 的 referrerPolicynet模块发起的请求支持referrer与referrerPolicy选项。electron_api_url_loader.cc 中opts.Get(referrerPolicy, request-referrer_policy)完成解析且默认值为GetDefaultNetReferrerPolicy()。集成测试 api-net-spec.ts 验证了这一点// The referrerPolicy must be unsafe-url because the referrers origin // is http:// while the request url is https:// const urlRequest net.request({ url: serverUrl, referrerPolicy: unsafe-url });该测试用例正好演示了策略裁剪的实际影响若 referrer 是http://而目标为https://默认策略下Referer会被清空必须显式指定unsafe-url才能发出完整 URL。webRequest 的 details.referrerelectron_api_web_request.cc 中details-Set(referrer, request.referrer)将 referrer 注入onBeforeRequest等事件的 details字符串形式。因此你可以用session.defaultSession.webRequest在请求管线中观测或改写请求头但注意details.referrer本身是只读的字符串字段要影响最终发出的Referer应通过onBeforeSendHeaders修改requestHeaders见 web-request.md。net 重定向链路electron_url_loader_factory.cc 在重定向时同步更新request_.referrer与request_.referrer_policy说明策略跟随重定向后的新 referrer 生效与 Referrer-Policy 规范的语义一致。小结Referrer 对象由url来源 URL与policy8 种取值之一的策略组成是 Electron 中表达带策略的 Referer的标准数据结构策略字符串在 electron_api_url_loader.cc 的Converternet::ReferrerPolicy中完成到 Chromium 枚举的映射匹配大小写不敏感且源码侧额外支持origin-when-cross-origin需要自定义策略时loadURL必须传Referrer 对象而非字符串否则策略会被固定为kDefaultdid-create-window的details.referrer、context-menu的referrerPolicy、net.request的referrerPolicy、webRequest的details.referrer构成了完整的观测与介入面可结合 net.md 与 web-request.md 的文档进一步使用。【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electron创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Electron Referrer 对象详解：用 url 与 policy 字段精确控制 Referer 行为

相关推荐

Open Interpreter plugin-creator 技能深度解析：Codex 插件、marketplace 条目与本地迭代流程一站式脚手架

Buzz离线转录上手指南：把音频文件和录音变成可编辑文字

Qt Creator 4.11.2源码编译实战：从tar.gz到自定义IDE

更多资讯

黄岛在哪复审电工证怎么考过不白交钱？电子证书怎么查最靠谱

电工证应会多久拿证？证书过期了不知道怎么复审延期怎么办？

兴平市电工证颁发机构官方回应：外省证书能否转过来？这些细节你必须知道

电工证企业需要办理吗？良心建议教你避坑

乐昌市电工证查询官方回应：没证就别想上岗找工作

中级焊工属于特种工吗多少钱报名流程全解析

今日更新

安监局电工证分数查询怎么查才能知道含金量高不高

新疆电工作业干活累吗良心建议助你避开考不过的坑

中牟县电工证怎么报名外省证能转吗

本周精选

安监局电工证分数查询怎么查才能知道含金量高不高

新疆电工作业干活累吗良心建议助你避开考不过的坑

中牟县电工证怎么报名外省证能转吗

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？

相关推荐

Open Interpreter plugin-creator 技能深度解析：Codex 插件、marketplace 条目与本地迭代流程一站式脚手架

Buzz离线转录上手指南：把音频文件和录音变成可编辑文字

Qt Creator 4.11.2源码编译实战：从tar.gz到自定义IDE

更多资讯

黄岛在哪复审电工证怎么考过不白交钱？电子证书怎么查最靠谱

电工证应会多久拿证？证书过期了不知道怎么复审延期怎么办？

兴平市电工证颁发机构官方回应：外省证书能否转过来？这些细节你必须知道

电工证企业需要办理吗？良心建议教你避坑

乐昌市电工证查询 官方回应：没证就别想上岗找工作

中级焊工属于特种工吗多少钱报名流程全解析

今日更新

安监局电工证分数查询怎么查才能知道含金量高不高

新疆电工作业干活累吗 良心建议助你避开考不过的坑

中牟县电工证怎么报名外省证能转吗

本周精选

安监局电工证分数查询怎么查才能知道含金量高不高

新疆电工作业干活累吗 良心建议助你避开考不过的坑

中牟县电工证怎么报名外省证能转吗

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？

乐昌市电工证查询官方回应：没证就别想上岗找工作

新疆电工作业干活累吗良心建议助你避开考不过的坑

新疆电工作业干活累吗良心建议助你避开考不过的坑