chrome.proxy

說明

權限

資訊清單

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

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

物件和屬性

Proxy 設定定義在 proxy.ProxyConfig 物件中。視 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，排除個別伺服器，不透過 Proxy 傳輸。這份清單可能包含下列項目：

[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>"

範例

下列程式碼會為所有伺服器的 HTTP 連線設定 SOCKS 5 Proxy，但 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,
)