chrome.proxy

refresh date: 2026-09-25 robots: noindex

Descripción

Permisos

Manifiesto

Debes declarar el permiso "proxy" en el manifiesto de la extensión para usar la API de configuración del proxy. Por ejemplo:

{
  "name": "My extension",
  ...
  "permissions": [
    "proxy"
  ],
  ...
}

Objetos y propiedades

La configuración del proxy se define en un objeto proxy.ProxyConfig. Según la configuración de proxy de Chrome, es posible que la configuración contenga proxy.ProxyRules o un proxy.PacScript.

Modos de proxy

El atributo mode de un objeto ProxyConfig determina el comportamiento general de Chrome con respecto al uso del proxy. Puede tomar los siguientes valores:

direct

En el modo direct, todas las conexiones se crean directamente, sin ningún proxy involucrado. Este modo no permite más parámetros en el objeto ProxyConfig.

auto_detect

En el modo auto_detect, la configuración del proxy se determina mediante una secuencia de comandos PAC que se puede descargar en http://wpad/wpad.dat. Este modo no permite más parámetros en el objeto ProxyConfig.

pac_script

En el modo pac_script, la configuración del proxy se determina mediante una secuencia de comandos PAC que se recupera de la URL especificada en el objeto proxy.PacScript o se toma literalmente del elemento data especificado en el objeto proxy.PacScript. Además, este modo no permite otros parámetros en el objeto ProxyConfig.

fixed_servers

En el modo fixed_servers, la configuración del proxy se codifica en un objeto proxy.ProxyRules. Su estructura se describe en Reglas de proxy. Además de esto, el modo fixed_servers no permite más parámetros en el objeto ProxyConfig.

system

En el modo system, la configuración del proxy se toma del sistema operativo. Este modo no permite más parámetros en el objeto ProxyConfig. Ten en cuenta que el modo system es diferente de no establecer ninguna configuración de proxy. En el último caso, Chrome recurre a la configuración del sistema solo si ninguna opción de la línea de comandos influye en la configuración del proxy.

Reglas de proxy

El objeto proxy.ProxyRules puede contener un atributo singleProxy o un subconjunto de proxyForHttp, proxyForHttps, proxyForFtp y fallbackProxy.

En el primer caso, el tráfico HTTP, HTTPS y FTP se envía a través del servidor proxy especificado. El resto del tráfico se envía directamente. En el último caso, el comportamiento es un poco más sutil: si se configura un servidor proxy para el protocolo HTTP, HTTPS o FTP, el tráfico respectivo se envía a través del servidor especificado. Si no se especifica un servidor proxy de este tipo o el tráfico usa un protocolo diferente de HTTP, HTTPS o FTP, se usa fallbackProxy. Si no se especifica ningún fallbackProxy, el tráfico se envía directamente sin un servidor proxy.

Objetos del servidor proxy

Se configura un servidor proxy en un objeto proxy.ProxyServer. La conexión al servidor proxy (definida por el atributo host) usa el protocolo definido en el atributo scheme. Si no se especifica ningún scheme, la conexión del proxy se establece de forma predeterminada en http.

Si no se define ningún port en un objeto proxy.ProxyServer, el puerto se deriva del esquema. Los puertos predeterminados son los siguientes:

Lista de excepciones

Los servidores individuales se pueden excluir del proxy con bypassList. Esta lista puede contener las siguientes entradas:

[SCHEME://]HOST_PATTERN[:PORT]

Coincide con todos los nombres de host que coinciden con el patrón HOST_PATTERN. Un "." inicial se interpreta como un "*.".

Ejemplos: "foobar.com", "*foobar.com", "*.foobar.com", "*foobar.com:99", "https://x.*.y.com:99".

Patrón	Combinaciones	No coincide
".foobar.com"	"www.foobar.com"	"foobar.com"
"*.foobar.com"	"www.foobar.com"	"foobar.com"
"foobar.com"	"foobar.com"	"www.foobar.com"
"*foobar.com"	"foobar.com", "www.foobar.com", "foofoobar.com"

[SCHEME://]IP_LITERAL[:PORT]

Coincide con las URLs que son literales de direcciones IP. Conceptualmente, es similar al primer caso, pero con casos especiales para controlar la canonización literal de IP. Por ejemplo, la coincidencia con "[0:0:0::1]" es la misma que la coincidencia con "[::1]" porque la canonización de IPv6 se realiza de forma interna.

Ejemplos: 127.0.1, [0:0::1], [::1]:80, https://[::1]:443

IP_LITERAL/PREFIX_LENGTH_IN_BITS

Coincide con cualquier URL que contenga un literal de IP (IP_LITERAL) dentro del rango determinado. El rango de IP (PREFIX_LENGTH_IN_BITS) se especifica con la notación CIDR.

Coincide con cualquier URL que contenga un literal de IP dentro del rango determinado. El rango de IP se especifica con la notación CIDR. Ejemplos: "192.168.1.1/16", "fefe:13::abc/33"

<local>

La cadena literal <local> coincide con nombres de host simples. Un nombre de host simple es aquel que no contiene puntos y no es un literal de IP. Por ejemplo, example y localhost son nombres de host simples, mientras que example.com, example. y [::1] no lo son.

Ejemplo: "<local>"

Ejemplos

El siguiente código establece un proxy SOCKS 5 para las conexiones HTTP a todos los servidores, excepto foobar.com, y usa conexiones directas para todos los demás protocolos. La configuración se aplica a las ventanas normales y de incógnito, ya que las ventanas de incógnito heredan la configuración de las ventanas normales. También consulta la documentación de la API de Types.

var config = {
  mode: "fixed_servers",
  rules: {
    proxyForHttp: {
      scheme: "socks5",
      host: "1.2.3.4"
    },
    bypassList: ["foobar.com"]
  }
};
chrome.proxy.settings.set(
  {value: config, scope: 'regular'},
  function() {}
);

El siguiente código establece una secuencia de comandos PAC personalizada.

var config = {
  mode: "pac_script",
  pacScript: {
    data: "function FindProxyForURL(url, host) {\n" +
          "  if (host == 'foobar.com')\n" +
          "    return 'PROXY blackhole:80';\n" +
          "  return 'DIRECT';\n" +
          "}"
  }
};
chrome.proxy.settings.set(
  {value: config, scope: 'regular'},
  function() {}
);

El siguiente fragmento consulta la configuración de proxy vigente. Otra extensión o una política pueden determinar la configuración de proxy efectiva. Consulta la documentación de la API de Types para obtener más detalles.

chrome.proxy.settings.get(
  {'incognito': false},
  function(config) {
    console.log(JSON.stringify(config));
  }
);

Ten en cuenta que el objeto value que se pasa a set() no es idéntico al objeto value que se pasa a la función de devolución de llamada de get(). Este último contendrá un elemento rules.proxyForHttp.port.

chrome.proxy.onProxyError.addListener(
  callback: function,
)