本頁面由 Cloud Translation API 翻譯而成。

chrome.proxy

說明

使用 chrome.proxy API 管理 Chrome 的 Proxy 設定。這個 API 需要運用 ChromeSetting 類型 API 原型取得及設定 Proxy 設定。

權限

proxy

資訊清單

您必須宣告「proxy」請使用擴充功能資訊清單中的權限，才能使用 Proxy 設定也能使用 Google Cloud CLI 或 Compute Engine API例如：

{
  "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 物件中指定的網址，或直接從 data 元素取得在 proxy.PacScript 物件中指定。此外，這個模式無法再提供其他參數在 ProxyConfig 物件中。
fixed_servers: 在 fixed_servers 模式下，Proxy 設定會編寫在 proxy.ProxyRules 物件中。結果請參閱「Proxy 規則」一文。除此之外，fixed_servers 模式已無定義 ProxyConfig 物件。
system: 在 system 模式下，Proxy 設定會從作業系統取得。如果使用這個模式， ProxyConfig 物件中其他的參數。請注意，system 模式與沒有 Proxy 設定若是後者，只有在符合以下條件時，Chrome 才會改回使用系統設定沒有任何指令列選項影響 Proxy 設定。

Proxy 規則

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

在第一個情況下，HTTP、HTTPS 和 FTP 流量會透過指定的 Proxy 伺服器進行 Proxy 處理。其他流量第二種情況則略有變動：如果 Proxy 伺服器 HTTP、HTTPS 或 FTP 通訊協定設定時，系統會透過指定的伺服器如果沒有指定這類 Proxy 伺服器，或是流量使用的通訊協定並非 HTTP、HTTPS 或 FTP，會使用 fallbackProxy。如未指定 fallbackProxy，系統會傳送流量無需 Proxy 伺服器

Proxy 伺服器物件

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

如果 proxy.ProxyServer 物件中未定義任何 port，則通訊埠將衍生自配置。預設通訊埠如下：

架構	通訊埠
http	80
https	443
socks4	1080
socks5	1080

略過清單

使用 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>"

範例

下列程式碼會為與 foobar.com 外的所有伺服器設定 HTTP 連線的 SOCKS 5 Proxy，並使用所有其他通訊協定的直接連線。這些設定會套用到一般視窗和無痕式視窗，如無痕式視窗會沿用一般視窗的設定。另請參閱 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 物件與傳入 value 物件不同 get() 的回呼函式。後者包含 rules.proxyForHttp.port 元素。

類型

Mode

Chrome 54 以上版本

列舉

"direct"

"auto_detect"

"pac_script"

"fixed_servers"

「系統」

PacScript

保留 Proxy 自動設定資訊的物件。其中一個欄位不能空白。

屬性

資料

string optional

PAC 指令碼。
必填

布林值選填

若為 true，無效的 PAC 指令碼將使網路堆疊無法轉回直接連線。預設值為 false。
網址

string optional

要使用的 PAC 檔案網址。

ProxyConfig

封裝完整 Proxy 設定的物件。

屬性

模式

模式

「直接」= 不使用 Proxy 「auto_Detect」= 自動偵測 Proxy 設定「pac_script」= 使用指定的 PAC 指令碼「fixed_servers」= 手動指定 Proxy 伺服器「系統」= 使用系統 Proxy 設定
pacScript

PacScript 選用

這項設定的 Proxy 自動設定 (PAC) 指令碼。這將用於「pac_script」模式。
規則

ProxyRules 選用

說明這項設定的 Proxy 規則。將這個數字用於「fixed_servers」模式。

ProxyRules

這個物件會封裝所有通訊協定的 Proxy 規則組合。使用「singleProxy」或 (子集)「proxyForHttp」、「proxyForHttps」、「proxyForFtp」和「fallbackProxy」

屬性

bypassList

string[] 選填

不需 Proxy 伺服器即可連線的伺服器清單。
fallbackProxy

ProxyServer 選用

要使用的 Proxy 伺服器；如果沒有指定 Proxy 伺服器，也未指定任何 ProxyFor...。
proxyForFtp

ProxyServer 選用

用於 FTP 要求的 Proxy 伺服器。
proxyForHttp

ProxyServer 選用

用於 HTTP 要求的 Proxy 伺服器。
proxyForHttps

ProxyServer 選用

用於 HTTPS 要求的 Proxy 伺服器。
singleProxy

ProxyServer 選用

用於個別網址要求 (http、https 和 ftp) 的 Proxy 伺服器。

ProxyServer

封裝單一 Proxy 伺服器規格的物件。

屬性

主機

字串

Proxy 伺服器的主機名稱或 IP 位址。主機名稱必須採用 ASCII 格式 (採用 Punycode 格式)。目前尚不支援 IDNA。
通訊埠

編號選填

Proxy 伺服器的通訊埠。預設為依附於配置的通訊埠。
架構

配置選用

Proxy 伺服器本身的配置 (通訊協定)。預設為「http」。

Scheme

Chrome 54 以上版本

列舉

"http"

"https"

"quic"

"socks4"

"socks5"

屬性

settings

要使用的 Proxy 設定。這項設定的值是 ProxyConfig 物件。

類型

types.ChromeSetting<ProxyConfig>

活動

onProxyError

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

通知 Proxy 錯誤。

參數

回呼

函式

callback 參數如下所示：
```
(details: object) => void
```
- 詳細資料
  
  物件
  - 詳細資料
    
    字串
    
    其他錯誤詳細資料，例如 JavaScript 執行階段錯誤。
  - 錯誤
    
    字串
    
    錯誤說明。
  - fatal
    
    布林值
    
    如為 true，則屬於嚴重錯誤，並取消網路交易。否則，系統會改用直接連線。