Наши волонтёры ещё не перевели данную статью на Русский. Присоединяйтесь к нам и помогите сделать эту работу!
Вы можете также прочитать эту статью на English (US).

This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

Registers a Proxy Auto-Configuration (PAC) file. The file is executed immediately, and its FindProxyForURL() function will be called for any HTTP, HTTPS, or FTP requests.

If PAC files are registered by more than one extension, then requests will be passed initially to the one that was registered first.

  • If the FindProxyForURL() function in the first PAC returns "DIRECT" for a request, then the request will be passed unchanged to the FindProxyForURL() function in the next PAC.
  • If the FindProxyForURL() function in the first PAC proxies the request by returning "PROXY" or some other proxying value, then the proxy URL will be passed to the FindProxyForURL() function in the next PAC.

Each extension can only register a single PAC file: if you call register() twice, the second PAC file will replace the first.

This is an asynchronous function that returns a Promise.

Communicating with PAC files

You can exchange messages between the PAC file and your extension's background page (or any other privileged pages, like popup pages) using runtime.sendMessage() and runtime.onMessage.

To send a message to the PAC file, you must set the toProxyScript option:

// background.js

// Log any messages from the proxy.
browser.runtime.onMessage.addListener((message, sender) => {
  if (sender.url === browser.extension.getURL(proxyScriptURL)) {

let messageToProxy = {
  enabled: true,
  foo: "A string",
  bar: 1234

browser.runtime.sendMessage(messageToProxy, {toProxyScript: true});
// pac.js

browser.runtime.onMessage.addListener((message) => {
  if (message.enabled) {
    browser.runtime.sendMessage("I'm enabled!");

PAC file specification

The basic PAC file syntax is described in the PAC documentation, but the implementation used by the proxy API differs from standard PAC design in several ways, which are described in this section.

FindProxyForURL() return value

The standard FindProxyForURL() returns a string. In Firefox 55 and 56, the PAC file used with the proxy API also returns a string. In Firefox 55 only, you must pass an argument to the "DIRECT" return value, even though it doesn't need an argument.

From Firefox 57 onwards, FindProxyForURL() may still return a string, but may alternatively (and preferably) return an array of proxy.ProxyInfo objects.

If the array contains more than one object, then all ProxyInfo objects after the first one represent failovers: if the proxy at position N in the array is not reachable when its ProxyInfo.failoverTimeout expires, then the browser will try the proxy at position N+1.

For example:

const proxySpecification = [
    type: "socks",
    host: "foo.com",
    port: 1080,
    proxyDNS: true,
    failoverTimeout: 5
    type: "socks",
    host: "bar.com",
    port: 1060,

The first proxy in the array will be tried first. If it does not respond in failoverTimeout seconds, the next will be tried, until the end of the array is reached.

PAC file environment

The global helper functions usually available for PAC files (isPlainHostName(), dnsDomainIs(), and so on) are not available.

Code running in the PAC file does not get access to:

//  pac.js

// send the log message to the background script
browser.runtime.sendMessage(`Proxy-blocker: blocked ${url}`);
// background-script.js

function handleMessage(message, sender) {
  // only handle messages from the proxy script
  if (sender.url != browser.extension.getURL(proxyScriptURL)) {




var registering = browser.proxy.register(
  url   // string


String. URL pointing to the PAC file to load. PAC files must be bundled with the extension, and url must be relative to the extension's manifest.json file.

Return value

A Promise that will be fulfilled with no arguments when the PAC file has been registered, or rejected if there was an error.


const proxyScriptURL = "proxy/proxy-script.js";


Example extensions

Browser compatibility

Update compatibility data on GitHub
ChromeEdgeFirefoxOperaFirefox for Android
registerChrome No support NoEdge No support NoFirefox Full support 56
Full support 56
Full support 55
Alternate Name
Alternate Name Uses the non-standard name: registerProxyScript
Opera No support NoFirefox Android Full support 56
Full support 56
Full support 55
Alternate Name
Alternate Name Uses the non-standard name: registerProxyScript


Full support  
Full support
No support  
No support
Uses a non-standard name.
Uses a non-standard name.


Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.

Метки документа и участники

Внесли вклад в эту страницу: irenesmith, evilpie, mdnwebdocs-bot, wbamberg, andrewtruongmoz
Обновлялась последний раз: irenesmith,