chrome.proxy

refresh date: 2026-09-25 robots: noindex

Descrizione

Autorizzazioni

Manifest

Per utilizzare l'API delle impostazioni del proxy, devi dichiarare l'autorizzazione "proxy" nel manifest dell'estensione. Ad esempio:

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

Oggetti e proprietà

Le impostazioni del proxy sono definite in un oggetto proxy.ProxyConfig. A seconda delle impostazioni del proxy di Chrome, le impostazioni potrebbero contenere proxy.ProxyRules o un proxy.PacScript.

Modalità proxy

L'attributo mode di un oggetto ProxyConfig determina il comportamento complessivo di Chrome in relazione all'utilizzo del proxy. Può assumere i seguenti valori:

direct

In modalità direct, tutte le connessioni vengono create direttamente, senza alcun proxy coinvolto. Questa modalità non consente ulteriori parametri nell'oggetto ProxyConfig.

auto_detect

In modalità auto_detect la configurazione del proxy è determinata da uno script PAC che può essere scaricato all'indirizzo http://wpad/wpad.dat. Questa modalità non consente ulteriori parametri nell'oggetto ProxyConfig.

pac_script

In modalità pac_script, la configurazione del proxy è determinata da uno script PAC recuperato dall'URL specificato nell'oggetto proxy.PacScript o preso letteralmente dall'elemento data specificato nell'oggetto proxy.PacScript. Inoltre, questa modalità non consente ulteriori parametri nell'oggetto ProxyConfig.

fixed_servers

In modalità fixed_servers, la configurazione del proxy è codificata in un oggetto proxy.ProxyRules. La sua struttura è descritta in Regole proxy. Oltre a questo, la modalità fixed_servers non consente ulteriori parametri nell'oggetto ProxyConfig.

system

In modalità system, la configurazione del proxy viene presa dal sistema operativo. Questa modalità non consente ulteriori parametri nell'oggetto ProxyConfig. Tieni presente che la modalità system è diversa dall'impostazione di nessuna configurazione proxy. In quest'ultimo caso, Chrome ripristina le impostazioni di sistema solo se nessuna opzione della riga di comando influisce sulla configurazione del proxy.

Regole proxy

L'oggetto proxy.ProxyRules può contenere un attributo singleProxy o un sottoinsieme di proxyForHttp, proxyForHttps, proxyForFtp e fallbackProxy.

Nel primo caso, il traffico HTTP, HTTPS e FTP viene inviato tramite proxy attraverso il server proxy specificato. L'altro traffico viene inviato direttamente. In quest'ultimo caso, il comportamento è leggermente più sottile: se un server proxy è configurato per il protocollo HTTP, HTTPS o FTP, il traffico corrispondente viene inviato tramite proxy attraverso il server specificato. Se non viene specificato alcun server proxy o il traffico utilizza un protocollo diverso da HTTP, HTTPS o FTP, viene utilizzato fallbackProxy. Se non viene specificato alcun fallbackProxy, il traffico viene inviato direttamente senza un server proxy.

Oggetti server proxy

Un server proxy è configurato in un oggetto proxy.ProxyServer. La connessione al server proxy (definito dall'attributo host) utilizza il protocollo definito nell'attributo scheme. Se non viene specificato alcun scheme, la connessione proxy viene impostata per impostazione predefinita su http.

Se non è definito alcun port in un oggetto proxy.ProxyServer, la porta viene derivata dallo schema. Le porte predefinite sono:

Lista di bypass

I singoli server possono essere esclusi dal proxy con bypassList. Questo elenco potrebbe contenere le seguenti voci:

[SCHEME://]HOST_PATTERN[:PORT]

Corrispondono a tutti i nomi host che corrispondono al pattern HOST_PATTERN. Un "." iniziale viene interpretato come un "*.".

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

Pattern	Corrisponde a	Non corrisponde a
".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" e "foofoobar.com"

[SCHEME://]IP_LITERAL[:PORT]

Corrispondono agli URL che sono valori letterali di indirizzi IP. A livello concettuale, questo caso è simile al primo, ma con casi speciali per gestire la canonizzazione dei valori letterali IP. Ad esempio, la corrispondenza con "[0:0:0::1]" è uguale alla corrispondenza con "[::1]" perché la canonizzazione IPv6 viene eseguita internamente.

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

IP_LITERAL/PREFIX_LENGTH_IN_BITS

Trova qualsiasi URL contenente un valore letterale IP (IP_LITERAL) all'interno dell'intervallo specificato. L'intervallo IP (PREFIX_LENGTH_IN_BITS) è specificato utilizzando la notazione CIDR.

Trova qualsiasi URL contenente un indirizzo IP letterale all'interno dell'intervallo specificato. L'intervallo IP è specificato utilizzando la notazione CIDR. Esempi: "192.168.1.1/16", "fefe:13::abc/33"

<local>

La stringa letterale <local> corrisponde ai nomi host semplici. Un nome host semplice è un nome che non contiene punti e non è un valore letterale IP. Ad esempio, example e localhost sono nomi host semplici, mentre example.com, example. e [::1] non lo sono.

Esempio: "<local>"

Esempi

Il seguente codice imposta un proxy SOCKS 5 per le connessioni HTTP a tutti i server, ad eccezione di foobar.com, e utilizza connessioni dirette per tutti gli altri protocolli. Le impostazioni si applicano alle finestre normali e a quelle di navigazione in incognito, in quanto queste ultime ereditano le impostazioni dalle finestre normali. Consulta anche la documentazione dell'API 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() {}
);

Il seguente codice imposta uno script PAC personalizzato.

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() {}
);

Lo snippet successivo esegue una query sulle impostazioni del proxy attualmente attive. Le impostazioni del proxy effettive possono essere determinate da un'altra estensione o da una policy. Per ulteriori dettagli, consulta la documentazione dell'API Types.

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

Tieni presente che l'oggetto value passato a set() non è identico all'oggetto value passato alla funzione di callback di get(). Quest'ultimo conterrà un elemento rules.proxyForHttp.port.

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