极速阅览

declarativeNetRequest - Mozilla | MDN

Toggle sidebar

Theme

OS default
Light
Dark

English (US)

Remember language Learn more

Permissions

To use this API, an extension must request the "declarativeNetRequest" or "declarativeNetRequestWithHostAccess" permission in its manifest.json file. The "declarativeNetRequest" permission is shown to users in permission prompts, the "declarativeNetRequestWithHostAccess" is not.

The "declarativeNetRequest" permission allows extensions to block and upgrade requests without any host permissions. Host permissions are required if the extension wants to redirect requests or modify headers on requests or when the "declarativeNetRequestWithHostAccess" permission is used instead of the "declarativeNetRequest" permission. To act on requests in these cases, host permissions are required for the request URL. For all requests, except for navigation requests (i.e., resource type main_frame and sub_frame), host permissions are also required for the request's initiator. The initiator of a request is usually the document or worker that triggered the request.

Some requests are restricted and cannot be matched by extensions. These include privileged browser requests, requests to or from restricted domains, and requests from other extensions.

The "declarativeNetRequestFeedback" permission is required to use getMatchedRules and onRuleMatchedDebug as they return information on declarative rules matched. See Testing for more information.

Rules

The declarative rules are defined by four fields:

id – An ID that uniquely identifies a rule within a ruleset. Mandatory and should be >= 1.
priority – The rule priority. When specified, it should be >= 1. Defaults to 1. See Matching precedence for details on how priority affects which rules are applied.
condition – The condition under which this rule is triggered.
action – The action to take when the rule is matched. Rules can do one of these things:
- block a network request.
- redirect a network request.
- modify headers from a network request.
- prevent another matching rule from being applied.

Note: A redirect action does not redirect the request, and the request continues as usual when:

the action does not change the request.
the redirect URL is invalid (e.g., the value of redirect.regexSubstitution is not a valid URL).

This is an example rule that blocks all script requests originating from "example.com" to any URL with "abc" as a substring:

json
{
  "id": 1,
  "priority": 1,
  "action": { "type": "block" },
  "condition": {
    "urlFilter": "abc",
    "initiatorDomains": ["example.com"],
    "resourceTypes": ["script"]
  }
}

The urlFilter field of a rule condition is used to specify the pattern matched against the request URL. See RuleCondition for details. Some examples of URL filters are:

urlFilter Matches Does not match

"abc"	https://abcd.com https://example.com/abcd	https://ab.com
"abc*d"	https://abcd.com https://example.com/abcxyzd	https://abc.com
"\|\|a.example.com"	https://a.example.com/ https://b.a.example.com/xyz	https://example.com/
"\|https*"	https://example.com	http://example.com/ http://https.com

Rulesets

Rules are organized into rulesets:

static rulesets: collections of rules defined with the "declarative_net_request" manifest key and stored in the extension. An extension can enable and disable static rulesets using updateEnabledRulesets. The set of enabled static rulesets is persisted across sessions but not across extension updates. The static rulesets enabled on extension installation and update are determined by the content of the "declarative_net_request" manifest key.
dynamic ruleset: rules added or removed using updateDynamicRules. These rules persist across sessions and extension updates.
session ruleset: rules added or removed using updateSessionRules. These rules do not persist across browser sessions.

Note: Errors and warnings about invalid static rules are only displayed during testing. Invalid static rules in permanently installed extensions are ignored. Therefore, it's important to verify that your static rulesets are valid by testing.

Limits

Static ruleset limits

An extension can:

specify static rulesets in the "declarative_net_request" manifest key up to the value of MAX_NUMBER_OF_STATIC_RULESETS.
enable static rulesets (in the "declarative_net_request" manifest key or programmatically) so that the number of rules (enabled or disabled) they contain doesn't exceed the value of GUARANTEED_MINIMUM_STATIC_RULES and the number of enable static rulesets doesn't exceed the value of MAX_NUMBER_OF_ENABLED_STATIC_RULESETS.

Note: The number of rules in enabled static rulesets for all extensions must not exceed the global limit. Extensions shouldn't depend on the global limit having a specific value; instead, they should use getAvailableStaticRuleCount to find the number of additional rules they can enable.
disable rules in static rulesets up to the value of MAX_NUMBER_OF_DISABLED_STATIC_RULES. However, these disabled rules count towards the GUARANTEED_MINIMUM_STATIC_RULES.

Dynamic and session-scoped rules

The number of dynamic and session-scoped rules an extension can add is limited to:

In Safari and up to Chrome 119 and Firefox 127, the value of MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES.
From Chrome 120 and Firefox 128, the values of MAX_NUMBER_OF_DYNAMIC_RULES and MAX_NUMBER_OF_SESSION_RULES

Matching precedence

When the browser evaluates how to handle requests, it checks each extension's rules that have a condition that matches the request and chooses the one to consider applying as follows:

the rule priority, where 1 is the lowest priority (and rules default to 1 where priority is not set).
If this doesn't result in one rule to apply:
the rule action, in the following order of precedence:
1. "allow" which means any other remaining rules are ignored.
2. "allowAllRequests" (for main_frame and sub_frame resourceTypes only) has the same effect as allow but also applies to future subresource loads in the document (including descendant frames) generated from the request.
3. "block" cancels the request.
4. "upgradeScheme" upgrades the scheme of the request.
5. "redirect" redirects the request.
6. "modifyHeaders" rewrites request or response headers or both.

Note: When multiple matching rules have the same rule priority and rule action type, the outcome can be ambiguous when the matched action support additional properties. These properties can result in outcomes that cannot be combined. For example:

The "block" action does not support additional properties, and therefore there is no ambiguity: all matching "block" actions would result in the same outcome.
The "redirect" action redirects a request to one destination. When multiple "redirect" actions match, all but one "redirect" action is ignored. It is still possible to redirect repeatedly when the redirected request matches another rule condition.
Multiple "modifyHeaders" actions can be applied independently when they touch different headers. The result is ambiguous when they touch the same header, because some combination of operations are not allowed (as explained at declarativeNetRequest.ModifyHeaderInfo). The evaluation order of "modifyHeaders" actions is therefore important.

To control the order in which actions are applied, assign distinct priority values to rules whose order of precedence is important.

Note: After rule priority and rule action, Firefox considers the ruleset the rule belongs to, in this order of precedence: session > dynamic > static rulesets. This cannot be relied upon across browsers, see WECG issue 280.

If only one extension provides a rule for the request, that rule is applied. However, where more than one extension has a matching rule, the browser chooses the one to apply in this order of precedence:

"block"
"redirect" and "upgradeScheme"
"allow" and "allowAllRequests"

If the request was not blocked or redirected, the matching modifyHeaders actions are applied, as documented in declarativeNetRequest.ModifyHeaderInfo.

Testing

testMatchOutcome, getMatchedRules, and onRuleMatchedDebug are available to assist with testing rules and rulesets. These APIs require the "declarativeNetRequestFeedback" permissions. In addition:

in Chrome, these APIs are only available to unpacked extensions.
in Firefox, these APIs are only available after setting the extensions.dnr.feedback preference to true. Set this preference using about:config or the --pref flag of the web-ext CLI tool.

Comparison with the webRequest API

The declarativeNetRequest API evaluates network requests in the browser itself. This makes it more performant than the webRequest API, where each network request is evaluated in JavaScript in the extension process.
Because the requests are not intercepted by the extension process, declarativeNetRequest removes the need for extensions to have a background page.
Unlike the webRequest API, blocking or upgrading requests using the declarativeNetRequest API requires no host permissions when used with the declarativeNetRequest permission.
The declarativeNetRequest API provides better privacy to users because extensions do not read the network requests made on the user's behalf.
(Chrome only:) Unlike the webRequest API, any images or iframes blocked using the declarativeNetRequest API are automatically collapsed in the DOM.
While deciding whether a request is to be blocked or redirected, the declarativeNetRequest API is given priority over the webRequest API because it allows for synchronous interception. Similarly, any headers removed through declarativeNetRequest API are not made visible to web request extensions.
The webRequest API is more flexible than the declarativeNetRequest API because it allows extensions to evaluate a request programmatically.