chrome.proxy

說明

權限

您必須在擴充功能資訊清單中宣告「Proxy」權限，才能使用 Proxy 設定 API。例如：

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

概念和用法

proxy.ProxyConfig 物件中定義了 Proxy 設定。視 Chrome 的 Proxy 設定而定，設定可能包含 proxy.ProxyRules 或 proxy.PacScript。

Proxy 模式

ProxyConfig 物件的 mode 屬性會決定 Chrome 在 Proxy 用量方面的整體行為。可能接受的值如下：

direct

在 direct 模式中，系統會直接建立所有連線，不必使用任何 Proxy。這個模式不允許 ProxyConfig 物件中的其他參數。

auto_detect

在 auto_detect 模式中，Proxy 設定是由 PAC 指令碼決定，可下載至 http://wpad/wpad.dat，這個模式不允許 ProxyConfig 物件中的進一步參數。

pac_script

在 pac_script 模式中，Proxy 設定是由 PAC 指令碼決定，這個指令碼是從 proxy.PacScript 物件中指定的網址擷取，或是從 proxy.PacScript 物件中指定的 data 元素實際擷取。此外，這個模式不允許在 ProxyConfig 物件中進一步使用參數。

fixed_servers

在 fixed_servers 模式下，系統會將 Proxy 設定寫入 proxy.ProxyRules 物件中。其結構說明請參閱「Proxy 規則」。此外，fixed_servers 模式不允許在 ProxyConfig 物件中進一步使用參數。

system

在 system 模式下，系統會沿用作業系統的 Proxy 設定。這個模式不允許 ProxyConfig 物件中的其他參數。請注意，system 模式與不設定 Proxy 設定不同。在第二種情況下，只有在沒有任何指令列選項影響 Proxy 設定時，Chrome 才會改回使用系統設定。

Proxy 規則

proxy.ProxyRules 物件可包含 singleProxy 屬性，或 proxyForHttp、proxyForHttps、proxyForFtp 和 fallbackProxy 的子集。

在第一種情況中，HTTP、HTTPS 及 FTP 流量都是透過指定的 Proxy 伺服器進行 Proxy 處理。其他流量則是直接傳送。如果是後者，則行為會稍有不同：如果為 HTTP、HTTPS 或 FTP 通訊協定設定了 Proxy 伺服器，則各流量會透過指定的伺服器進行 Proxy 處理。如未指定這類 Proxy 伺服器，或是流量使用的通訊協定與 HTTP、HTTPS 或 FTP 不同，系統會使用 fallbackProxy。如未指定 fallbackProxy，則會在沒有 Proxy 伺服器的情況下直接傳送流量。

Proxy 伺服器物件

Proxy 伺服器是在 proxy.ProxyServer 物件中設定。與 Proxy 伺服器的連線 (由 host 屬性定義) 會使用 scheme 屬性中定義的通訊協定。如未指定 scheme，Proxy 連線會預設為 http。

如果在 proxy.ProxyServer 物件中未定義 port，通訊埠就會衍生自配置。預設通訊埠如下：

略過清單

個別伺服器可能會遭到 bypassList 排除。這份清單可能包含下列項目：

[SCHEME://]HOST_PATTERN[:PORT]

符合所有符合 HOST_PATTERN 模式的主機名稱。開頭的 "." 會解讀為 "*."。

範例："foobar.com", "*foobar.com", "*.foobar.com", "*foobar.com:99", "https://x.*.y.com:99"。

模式	相符	不相符
".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]

比對屬於 IP 位址常值的網址。從概念上來說，這與第一個案例類似，但有特殊案例會處理 IP 常值標準化。舉例來說，「[0:0:0::1]」的比對作業會與「[::1]」的比對結果一樣，因為 IPv6 標準化作業會在內部完成。

範例：127.0.1、[0:0::1]、[::1]:80、https://[::1]:443

IP_LITERAL/PREFIX_LENGTH_IN_BITS

比對指定範圍內任何包含 IP 常值 (IP_LITERAL) 的網址。IP 範圍 (PREFIX_LENGTH_IN_BITS) 是以 CIDR 標記法指定。

比對指定範圍內任何含有 IP 常值的網址。IP 範圍是以 CIDR 標記法指定。範例："192.168.1.1/16", "fefe:13::abc/33"

<local>

文字字串 <local> 與簡易主機名稱相符。簡單的主機名稱為不含點，也不是 IP 常值的字串。例如，example 和 localhost 是簡單的主機名稱，而 example.com、example. 和 [::1] 則不是。

範例："<local>"

示例

下列程式碼會設定 SOCKS 5 Proxy，用於 HTTP 連線到所有伺服器的 HTTP 連線 (foobar.com 除外)，並使用直接連線處理所有其他通訊協定。這些設定會套用到一般視窗和無痕式視窗，因為無痕式視窗會沿用一般視窗的設定。另請參閱 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() {}
);

下列程式碼會設定自訂 PAC 指令碼。

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

下一段程式碼片段會查詢目前有效的 Proxy 設定。有效的 Proxy 設定可由其他擴充功能或政策決定。詳情請參閱 Types API 說明文件。

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

請注意，傳遞至 set() 的 value 物件與傳遞至 get() 回呼函式的 value 物件不同。後者則包含 rules.proxyForHttp.port 元素。

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