說明
使用 chrome.proxy
API 管理 Chrome 的 Proxy 設定。這個 API 會使用 API 類型的 ChromeSetting 原型取得及設定 Proxy 設定。
權限
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
,通訊埠就會衍生自配置。預設通訊埠如下:
架構 | 通訊埠 |
---|---|
http | 80 |
https | 443 |
socks4 | 1080 |
socks5 | 1080 |
略過清單
個別伺服器可能會遭到 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
元素。
類型
Mode
列舉
"auto_detect"
"pac_script"
"fixed_servers"
PacScript
保留 Proxy 自動設定資訊的物件。其中一個欄位不可為空白。
屬性
-
資料或曾存取這類資料的人員
字串 選用
PAC 指令碼。
-
必要
布林值 (選用)
如果為 true,無效的 PAC 指令碼會防止網路堆疊改回直接連線。預設值為 false。
-
url
字串 選用
要使用的 PAC 檔案網址。
ProxyConfig
封裝完整 Proxy 設定的物件。
屬性
-
模式
'direct' = 永不使用 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 伺服器,或是未指定任何特定 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
列舉
"http"
"quic"
"socks4"
"socks5"
屬性
settings
要使用的 Proxy 設定。這項設定的值是 ProxyConfig 物件。
活動
onProxyError
chrome.proxy.onProxyError.addListener(
callback: function,
)
通知 Proxy 錯誤。
參數
-
回呼
功能
callback
參數如下所示:(details: object) => void
-
詳細資料
物件
-
詳細資料
字串
錯誤的其他詳細資料,例如 JavaScript 執行階段錯誤。
-
錯誤
字串
錯誤說明。
-
fatal
boolean
如果為 true,代表錯誤已嚴重,且網路交易已取消。否則,系統會改用直接連線。
-
-