chrome.proxy

Aktualisierungsdatum: 2026-09-25 robots: noindex

Beschreibung

Berechtigungen

Manifest

Sie müssen die Berechtigung „proxy“ im Erweiterungsmanifest deklarieren, um die Proxy-Einstellungen-API verwenden zu können. Beispiel:

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

Objekte und Attribute

Proxy-Einstellungen werden in einem proxy.ProxyConfig-Objekt definiert. Je nach den Chrome-Proxy-Einstellungen können die Einstellungen proxy.ProxyRules oder eine proxy.PacScript enthalten.

Proxy-Modi

Das Attribut mode eines ProxyConfig-Objekts bestimmt das allgemeine Verhalten von Chrome in Bezug auf die Proxy-Nutzung. Sie kann die folgenden Werte annehmen:

direct

Im direct-Modus werden alle Verbindungen direkt ohne Proxy erstellt. In diesem Modus sind keine weiteren Parameter im ProxyConfig-Objekt zulässig.

auto_detect

Im Modus auto_detect wird die Proxykonfiguration durch ein PAC-Skript bestimmt, das unter http://wpad/wpad.dat heruntergeladen werden kann. In diesem Modus sind keine weiteren Parameter im ProxyConfig-Objekt zulässig.

pac_script

Im Modus pac_script wird die Proxykonfiguration durch ein PAC-Script bestimmt, das entweder über die URL abgerufen wird, die im Objekt proxy.PacScript angegeben ist, oder direkt aus dem Element data stammt, das im Objekt proxy.PacScript angegeben ist. Außerdem sind in diesem Modus keine weiteren Parameter im ProxyConfig-Objekt zulässig.

fixed_servers

Im Modus fixed_servers wird die Proxykonfiguration in einem proxy.ProxyRules-Objekt codiert. Die Struktur wird unter Proxyregeln beschrieben. Außerdem sind im fixed_servers-Modus keine weiteren Parameter im ProxyConfig-Objekt zulässig.

system

Im Modus system wird die Proxykonfiguration vom Betriebssystem übernommen. In diesem Modus sind keine weiteren Parameter im ProxyConfig-Objekt zulässig. Der system-Modus unterscheidet sich davon, dass keine Proxykonfiguration festgelegt wird. Im letzteren Fall greift Chrome nur dann auf die Systemeinstellungen zurück, wenn keine Befehlszeilenoptionen die Proxykonfiguration beeinflussen.

Proxyregeln

Das Objekt proxy.ProxyRules kann entweder ein singleProxy-Attribut oder eine Teilmenge von proxyForHttp, proxyForHttps, proxyForFtp und fallbackProxy enthalten.

Im ersten Fall wird HTTP-, HTTPS- und FTP-Traffic über den angegebenen Proxyserver geleitet. Anderer Traffic wird direkt gesendet. Im letzteren Fall ist das Verhalten etwas subtiler: Wenn ein Proxyserver für das HTTP-, HTTPS- oder FTP-Protokoll konfiguriert ist, wird der entsprechende Traffic über den angegebenen Server geleitet. Wenn kein solcher Proxyserver angegeben ist oder der Traffic ein anderes Protokoll als HTTP, HTTPS oder FTP verwendet, wird fallbackProxy verwendet. Wenn keine fallbackProxy angegeben ist, wird der Traffic direkt ohne Proxyserver gesendet.

Proxyserver-Objekte

Ein Proxyserver wird in einem proxy.ProxyServer-Objekt konfiguriert. Die Verbindung zum Proxyserver (definiert durch das Attribut host) verwendet das im Attribut scheme definierte Protokoll. Wenn kein scheme angegeben ist, wird standardmäßig http für die Proxyverbindung verwendet.

Wenn in einem proxy.ProxyServer-Objekt kein port definiert ist, wird der Port aus dem Schema abgeleitet. Die Standardports sind:

Umgehungsliste

Einzelne Server können mit der bypassList vom Proxying ausgeschlossen werden. Diese Liste kann die folgenden Einträge enthalten:

[SCHEME://]HOST_PATTERN[:PORT]

Alle Hostnamen, die dem Muster HOST_PATTERN entsprechen. Ein führendes "." wird als "*." interpretiert.

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

Muster	Übereinstimmungen	Stimmt nicht überein
".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]

Entspricht URLs, die IP-Adressliterale sind. Konzeptionell ähnelt dies dem ersten Fall, es gibt jedoch Sonderfälle für die Kanonisierung von IP-Literalen. Beispiel: Der Abgleich mit „[0:0:0::1]“ entspricht dem Abgleich mit „[::1]“, da die kanonische Darstellung von IPv6 intern erfolgt.

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

IP_LITERAL/PREFIX_LENGTH_IN_BITS

Entspricht jeder URL, die ein IP-Literal (IP_LITERAL) im angegebenen Bereich enthält. Der IP-Bereich (PREFIX_LENGTH_IN_BITS) wird in CIDR-Notation angegeben.

Entspricht jeder URL, die ein IP-Literal im angegebenen Bereich enthält. Der IP-Bereich wird in CIDR-Notation angegeben. Beispiele: "192.168.1.1/16", "fefe:13::abc/33"

<local>

Der Literalstring <local> stimmt mit einfachen Hostnamen überein. Ein einfacher Hostname enthält keine Punkte und ist kein IP-Literal. example und localhost sind beispielsweise einfache Hostnamen, example.com, example. und [::1] jedoch nicht.

Beispiel: "<local>"

Beispiele

Im folgenden Code wird ein SOCKS 5-Proxy für HTTP-Verbindungen zu allen Servern außer foobar.com festgelegt und für alle anderen Protokolle werden direkte Verbindungen verwendet. Die Einstellungen gelten für normale und Inkognitofenster, da Inkognitofenster Einstellungen von normalen Fenstern übernehmen. Weitere Informationen finden Sie in der Dokumentation zur Types API.

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

Mit dem folgenden Code wird ein benutzerdefiniertes PAC-Script festgelegt.

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

Mit dem nächsten Snippet werden die aktuell gültigen Proxy-Einstellungen abgefragt. Die effektiven Proxy-Einstellungen können durch eine andere Erweiterung oder durch eine Richtlinie festgelegt werden. Weitere Informationen finden Sie in der Dokumentation zur Types API.

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

Das value-Objekt, das an set() übergeben wird, ist nicht mit dem value-Objekt identisch, das an die Callback-Funktion von get() übergeben wird. Letzteres enthält ein rules.proxyForHttp.port-Element.

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