chrome.proxy

refresh date: 2026-09-25 robots: noindex

說明

使用 chrome.proxy API 管理 Chrome 的 Proxy 設定。這個 API 仰賴 ChromeSetting 類型的 API 原型，來取得及設定 Proxy 設定。

權限

proxy

這項權限會觸發警告。

資訊清單

您必須在擴充功能資訊清單中宣告「proxy」權限，才能使用 Proxy 設定 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 物件中指定的網址擷取，或從 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，通訊埠會從配置衍生。預設通訊埠如下：

配置	通訊埠
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>"

範例

下列程式碼會為 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 元素。

類型

Mode

Chrome 54 以上版本

列舉

"direct"

"auto_detect"

"pac_script"

"fixed_servers"

"system"

PacScript

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

屬性

• 資料

  字串 選填

  PAC 指令碼。

• 必填

  布林值 選填

  如果設為 True，無效的 PAC 指令碼會阻止網路堆疊改回直接連線。預設值為 false。

• 網址

  字串 選填

  要使用的 PAC 檔案網址。

ProxyConfig

封裝完整 Proxy 設定的物件。

屬性

• 模式

  眾數

  「direct」= 永不使用 Proxy 「auto_detect」= 自動偵測 Proxy 設定 「pac_script」= 使用指定的 PAC 指令碼 「fixed_servers」= 手動指定 Proxy 伺服器 「system」= 使用系統 Proxy 設定

• pacScript

  PacScript 選填

  這項設定的 Proxy 自動設定 (PAC) 指令碼。請在「pac_script」模式中使用這個值。

• 規則

  ProxyRules 選用

  說明這項設定的 Proxy 規則。這項設定適用於「fixed_servers」模式。

ProxyRules

封裝所有通訊協定 Proxy 規則集的物件。請使用「singleProxy」或「proxyForHttp」、「proxyForHttps」、「proxyForFtp」和「fallbackProxy」的子集。

屬性

• bypassList

  string[] 選填

  不透過 Proxy 伺服器連線的伺服器清單。

• fallbackProxy

  ProxyServer 選填

  用於其他所有項目的 Proxy 伺服器，或未指定任何特定 proxyFor... 時使用的 Proxy 伺服器。

• 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 伺服器的通訊埠。預設為取決於配置的通訊埠。

• 架構

  Scheme 選填

  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

  函式

  callback 參數如下：

  (details: object) => void

  • 詳細資料

    物件

    • 詳細資料

      字串

      錯誤的其他詳細資料，例如 JavaScript 執行階段錯誤。

    • 錯誤

      字串

      錯誤說明。

    • fatal

      布林值

      如果為 true，表示發生嚴重錯誤，網路交易已取消。否則會改用直接連線。