webRequest.onErrorOccurred

当请求由于错误而无法处理时触发，例如缺少 Internet 连接。

错误作为 details 对象的 error 属性传递给侦听器。

请注意，此事件不会针对 HTTP 错误（4XX 或 5XX 响应）触发：这些错误将经历请求的正常阶段，调用任何事件侦听器，并将 details.statusCode 设置为报告错误。

此事件仅供参考。

语法

browser.webRequest.onErrorOccurred.addListener(
  listener,             // function
  filter                //  object
)
browser.webRequest.onErrorOccurred.removeListener(listener)
browser.webRequest.onErrorOccurred.hasListener(listener)

事件有三个函数

addListener(listener, filter): 向此事件添加侦听器。
removeListener(listener): 停止监听此事件。listener 参数是要删除的侦听器。
hasListener(listener): 检查listener 是否为此事件注册。如果正在监听，则返回true，否则返回false。

addListener 语法

参数

listener

当此事件发生时调用的函数。该函数将传递此参数

details: object。有关请求的详细信息。有关更多信息，请参阅 details 部分。

filter

webRequest.RequestFilter。限制发送到此侦听器的事件的过滤器。

其他对象

details

cookieStoreId

string。如果请求来自上下文标识中打开的选项卡，则为上下文标识的 cookie 存储 ID。有关更多信息，请参阅使用上下文标识。

documentUrl

string。将在其中加载资源的文档的 URL。例如，如果 https://example.com 上的网页包含图像或 iframe，则图像或 iframe 的 documentUrl 将为 https://example.com。对于顶级文档，documentUrl 未定义。

error

string。错误描述。此字符串是一个内部错误字符串，可能因浏览器而异，并且不保证在不同版本之间保持一致。

frameId

integer。如果请求发生在主框架中，则为零；正值是发生请求的子框架的 ID。如果（子）框架的文档已加载（type 为 main_frame 或 sub_frame），则 frameId 指示此框架的 ID，而不是外部框架的 ID。框架 ID 在一个选项卡内是唯一的。

fromCache

boolean。指示此响应是否从磁盘缓存中获取。

incognito

boolean。请求是否来自私人浏览窗口。

ip

string。发送请求的服务器的 IP 地址。它可以是文字 IPv6 地址。

method

string。标准 HTTP 方法：例如，“GET” 或“POST”。

originUrl

string。触发请求的资源的 URL。例如，如果 https://example.com 包含链接，用户点击该链接，则结果请求的 originUrl 为 https://example.com。

originUrl 通常与 documentUrl 相同，但并非总是如此。例如，如果页面包含 iframe，并且 iframe 包含链接，该链接将加载一个新文档到 iframe 中，则结果请求的 documentUrl 将是 iframe 的父文档，但 originUrl 将是包含链接的 iframe 中的文档的 URL。

parentFrameId

integer。包含发送请求的框架的框架的 ID。如果不存在父框架，则设置为 -1。

proxyInfo

object。此属性仅在请求被代理时存在。它包含以下属性

host

string。代理服务器的主机名。

port

integer。代理服务器的端口号。

type

string。代理服务器的类型。以下之一

"http": HTTP 代理（或 HTTPS 的 SSL CONNECT）
"https": 通过 TLS 连接到代理的 HTTP 代理
"socks": SOCKS v5 代理
"socks4": SOCKS v4 代理
"direct": 无代理
"unknown": 未知代理

username

string。代理服务的用户名。

proxyDNS

boolean。如果代理将根据提供的 hostname 执行域名解析，则为 true，这意味着客户端不应该进行自己的 DNS 查找。

failoverTimeout

integer。故障转移超时时间（以秒为单位）。如果代理连接失败，则在此期间不会再次使用该代理。

requestId

string。请求的 ID。请求 ID 在一个浏览器会话中是唯一的，因此您可以使用它们来关联与同一请求相关的不同事件。

tabId

integer。发生请求的选项卡的 ID。如果请求与选项卡无关，则设置为 -1。

thirdParty

boolean。指示请求及其内容窗口层次结构是否为第三方。

timeStamp

number。此事件触发的时刻，以自纪元以来的毫秒数为单位。

type

webRequest.ResourceType。正在请求的资源类型：例如，“image”、“script”、“stylesheet”。

url

string。请求的目标。

urlClassification

object。如果请求被 Firefox 跟踪保护分类，则与请求相关的跟踪类型。这是一个具有以下属性的对象

firstParty: array of strings。请求的第一方的分类标志。
thirdParty: array of strings。请求或其窗口层次结构的第三方的分类标志。

分类标志包括

fingerprinting 和 fingerprinting_content：指示请求参与指纹识别（“发现指纹识别的来源”）。
- fingerprinting 表示该域名属于指纹识别和跟踪类别。此类域名的示例包括希望将个人资料与访问用户关联的广告商。
- fingerprinting_content 表示该域名属于指纹识别类别，但不属于跟踪类别。此类域名的示例包括使用指纹识别技术识别访问用户以进行反欺诈的支付提供商。
cryptomining 和 cryptomining_content：类似于指纹识别类别，但用于加密货币挖掘资源。
tracking、tracking_ad、tracking_analytics、tracking_social 和 tracking_content：表示请求涉及跟踪。tracking 是任何通用的跟踪请求，ad、analytics、social 和 content 后缀标识跟踪器的类型。
any_basic_tracking：一个元标记，它组合了跟踪和指纹识别标记，但不包括 tracking_content 和 fingerprinting_content。
any_strict_tracking：一个元标记，它组合了所有跟踪和指纹识别标记。
any_social_tracking：一个元标记，它组合了所有社交跟踪标记。

注意如果 Firefox 跟踪保护阻止了请求，则会返回一个空对象，并且 error 会返回以下代码之一

NS_ERROR_MALWARE_URI 表示恶意软件 URI。
NS_ERROR_PHISHING_URI 表示网络钓鱼 URI。
NS_ERROR_TRACKING_URI 表示跟踪 URI。
NS_ERROR_UNWANTED_URI 表示不需要的 URI。
NS_ERROR_BLOCKED_URI 表示被阻止的 URI。
NS_ERROR_HARMFUL_URI 表示有害 URI。
NS_ERROR_FINGERPRINTING 表示指纹识别 URI。
NS_ERROR_CRYPTOMINING_URI 表示加密货币挖掘 URI。
NS_ERROR_SOCIALTRACKING_URI 表示社交跟踪 URI。

浏览器兼容性

BCD 表仅在浏览器中加载

示例

let target = "<all_urls>";

/*
e.g., with no network:
"https://mdn.org.cn/en-US/"
NS_ERROR_NET_ON_RESOLVED in Firefox
net::ERR_INTERNET_DISCONNECTED in Chrome
*/
function logError(responseDetails) {
  console.log(responseDetails.url);
  console.log(responseDetails.error);
}

browser.webRequest.onErrorOccurred.addListener(logError, { urls: [target] });

示例扩展

存储的凭据

注意： 此 API 基于 Chromium 的 chrome.webRequest API。此文档源自 Chromium 代码中的 web_request.json。