Our volunteers haven't translated this article into 한국어 yet. Join us and help get the job done!
You can also read the article in English (US).

Match patterns are a way to specify groups of URLs: a match pattern matches a specific set of URLs. They are for extensions using WebExtensions APIs in a few places, most notably to specify which documents to load content scripts into, and to specify which URLs to add webRequest listeners to.

APIs that use match patterns usually accept a list of match patterns, and will perform the appropriate action if the URL matches any of the patterns. See, for example, the content_scripts key in manifest.json.

Match pattern structure

Note: Some browsers don’t support certain schemes.
Check the Browser compatibility table for details.

All match patterns are specified as strings. Apart from the special "<all_urls>" pattern, match patterns consist of three parts: scheme, host, and path. The scheme and host are separated by "://".

<scheme>://<host><path>

scheme

The scheme component may take one of two forms:

Form Matches
"*" Only "http" and "https" and in some browsers also "ws" and "wss".
One of "http", "https", "ws", "wss", "ftp", "ftps" or "file". Only the given scheme.

host

The host component may take one of three forms:

Form Matches
"*" Any host.
"*." followed by part of the hostname. The given host and any of its subdomains.
A complete hostname, without wildcards. Only the given host.

host is optional only if the scheme is "file".

Note that the wildcard may only appear at the start.

path

The path component must begin with a "/".

After that, it may subsequently contain any combination of the "*" wildcard and any of the characters that are allowed in URL paths. Unlike host, the path component may contain the "*" wildcard in the middle or at the end, and the "*" wildcard may appear more than once.

<all_urls>

The special value "<all_urls>" matches all URLs under any of the supported schemes: that is "http", "https", "ws", "wss", "ftp" and "file".

Examples

Pattern Example matches Example non-matches

<all_urls>

Match all URLs.

http://example.org/

https://a.org/some/path/

ws://sockets.somewhere.org/

wss://ws.example.com/stuff/

ftp://files.somewhere.org/

ftps://files.somewhere.org/

resource://a/b/c/
(unsupported scheme)

*://*/*

Match all HTTP, HTTPS and WebSocket URLs.

http://example.org/

https://a.org/some/path/

ws://sockets.somewhere.org/

wss://ws.example.com/stuff/

ftp://ftp.example.org/
(unmatched scheme)

ftps://ftp.example.org/
(unmatched scheme)

file:///a/
(unmatched scheme)

*://*.mozilla.org/*

Match all HTTP, HTTPS and WebSocket URLs that are hosted at "mozilla.org" or one of its subdomains.

http://mozilla.org/

https://mozilla.org/

http://a.mozilla.org/

http://a.b.mozilla.org/

https://b.mozilla.org/path/

ws://ws.mozilla.org/

wss://secure.mozilla.org/something

ftp://mozilla.org/
(unmatched scheme)

http://mozilla.com/
(unmatched host)

http://firefox.org/
(unmatched host)

*://mozilla.org/

Match all HTTP, HTTPS and WebSocket URLs that are hosted at exactly "mozilla.org/".

http://mozilla.org/

https://mozilla.org/

ws://mozilla.org/

wss://mozilla.org/

ftp://mozilla.org/
(unmatched scheme)

http://a.mozilla.org/
(unmatched host)

http://mozilla.org/a
(unmatched path)

ftp://mozilla.org/

Match only "ftp://mozilla.org/".

ftp://mozilla.org

http://mozilla.org/
(unmatched scheme)

ftp://sub.mozilla.org/
(unmatched host)

ftp://mozilla.org/path
(unmatched path)

https://*/path

Match HTTPS URLs on any host, whose path is "path".

https://mozilla.org/path

https://a.mozilla.org/path

https://something.com/path

http://mozilla.org/path
(unmatched scheme)

https://mozilla.org/path/
(unmatched path)

https://mozilla.org/a
(unmatched path)

https://mozilla.org/
(unmatched path)

https://*/path/

Match HTTPS URLs on any host, whose path is "path/".

https://mozilla.org/path/

https://a.mozilla.org/path/

https://something.com/path/

http://mozilla.org/path/
(unmatched scheme)

https://mozilla.org/path
(unmatched path)

https://mozilla.org/a
(unmatched path)

https://mozilla.org/
(unmatched path)

https://mozilla.org/*

Match HTTPS URLs only at "mozilla.org", with any path.

https://mozilla.org/

https://mozilla.org/path

https://mozilla.org/another

https://mozilla.org/path/to/doc

http://mozilla.org/path
(unmatched scheme)

https://mozilla.com/path
(unmatched host)

https://mozilla.org/a/b/c/

Match only this URL.

https://mozilla.org/a/b/c/ Anything else.

https://mozilla.org/*/b/*/

Match HTTPS URLs hosted on "mozilla.org", whose path contains a component "b" somewhere in the middle.

https://mozilla.org/a/b/c/

https://mozilla.org/d/b/f/

https://mozilla.org/a/b/c/d/

https://mozilla.org/b/*/
(unmatched path)

https://mozilla.org/a/b/
(unmatched path)

file:///blah/*

Match any FILE URL whose path begins with "blah".

file:///blah/

file:///blah/bleh

file:///bleh/
(unmatched path)

Invalid match patterns

Invalid pattern Reason
resource://path/ Unsupported scheme.
https://mozilla.org No path.
https://mozilla.*.org/ "*" in host must be at the start.
https://*zilla.org/ "*" in host must be the only character or be followed by ".".
http*://mozilla.org/ "*" in scheme must be the only character.
*://* Empty path: this should be "*://*/*".
file://* Empty path: this should be "file:///*".

Browser compatibility

ChromeEdgeFirefoxFirefox for AndroidOpera
Basic support Yes144848 Yes
scheme: Wildcard * scheme Yes144848 Yes
scheme: * matches ws and wss No ?5555 No
scheme.http Yes144848 Yes
scheme.https Yes144848 Yes
scheme.ws No ?5555 No
scheme.wss No ?5555 No
scheme.ftp Yes144848 Yes
scheme.ftps No No No1 No1 No
scheme.file Yes144848 Yes
scheme.data No ?482482 No

1. See bug 1463440

2. Doesn’t support injection of content scripts or stylesheets.

Converting Match Patterns to Regular Expressions

All match patterns can be represented by regular expressions. This code converts a match pattern to a regular expression:

/**
 * Transforms a valid match pattern into a regular expression
 * which matches all URLs included by that pattern.
 *
 * @param  {string}  pattern  The pattern to transform.
 * @return {RegExp}           The pattern's equivalent as a RegExp.
 * @throws {TypeError}        If the pattern is not a valid MatchPattern
 */
function matchPatternToRegExp(pattern) {
    if (pattern === '') {
        return (/^(?:http|https|file|ftp|app):\/\//);
    }

    const schemeSegment = '(\\*|http|https|ws|wss|file|ftp)';
    const hostSegment = '(\\*|(?:\\*\\.)?(?:[^/*]+))?';
    const pathSegment = '(.*)';
    const matchPatternRegExp = new RegExp(
        `^${schemeSegment}://${hostSegment}/${pathSegment}$`
    );

    let match = matchPatternRegExp.exec(pattern);
    if (!match) {
         throw new TypeError(`"${pattern}" is not a valid MatchPattern`);
    }

    let [, scheme, host, path] = match;
    if (!host) {
        throw new TypeError(`"${pattern}" does not have a valid host`);
    }

    let regex = '^';

    if (scheme === '*') {
        regex += '(http|https)';
    } else {
        regex += scheme;
    }

    regex += '://';

    if (host && host === '*') {
        regex += '[^/]+?';
    } else if (host) {
        if (host.match(/^\*\./)) {
            regex += '[^/]*?';
            host = host.substring(2);
        }
        regex += host.replace(/\./g, '\\.');
    }

    if (path) {
        if (path === '*') {
            regex += '(/.*)?';
        } else if (path.charAt(0) !== '/') {
            regex += '/';
            regex += path.replace(/\./g, '\\.').replace(/\*/g, '.*?');
            regex += '/?';
        }
    }

    regex += '$';
    return new RegExp(regex);
}

문서 태그 및 공헌자

태그: 
최종 변경: wbamberg,