说明
使用 chrome.proxy
API 管理 Chrome 的代理设置。此 API 依赖于 ChromeSetting 类型 API 原型来获取和设置代理配置。
权限
proxy
您必须在扩展程序清单中声明“代理”权限,才能使用代理设置 API。例如:
{
"name": "My extension",
...
"permissions": [
"proxy"
],
...
}
概念和用法
代理设置在 proxy.ProxyConfig
对象中定义。根据 Chrome 的代理设置,这些设置可能包含 proxy.ProxyRules
或 proxy.PacScript
。
代理模式
ProxyConfig 对象的 mode
属性决定了 Chrome 关于代理使用的总体行为。它可以采用以下值:
direct
- 在
direct
模式下,所有连接都是直接创建的,不涉及任何代理。此模式不允许在ProxyConfig
对象中使用更多参数。 auto_detect
- 在
auto_detect
模式下,代理配置由 PAC 脚本决定,可从 http://wpad/wpad.dat 下载。此模式不允许在ProxyConfig
对象中使用更多参数。 pac_script
- 在
pac_script
模式下,代理配置由 PAC 脚本决定,该脚本从proxy.PacScript
对象中指定的网址检索,或者从proxy.PacScript
对象中指定的data
元素直接获取。除此之外,此模式不允许在ProxyConfig
对象中使用更多参数。 fixed_servers
- 在
fixed_servers
模式下,代理配置会编码到proxy.ProxyRules
对象中。代理规则中介绍了其结构。除此之外,fixed_servers
模式不允许在ProxyConfig
对象中使用更多参数。 system
- 在
system
模式下,代理配置从操作系统获取。此模式不允许在ProxyConfig
对象中使用更多参数。请注意,system
模式与未设置代理配置不同。在后一种情况下,只有在没有任何命令行选项影响代理配置时,Chrome 才会回退到系统设置。
代理规则
proxy.ProxyRules
对象可以包含 singleProxy
属性,也可以包含 proxyForHttp
、proxyForHttps
、proxyForFtp
和 fallbackProxy
的子集。
在第一种情况下,HTTP、HTTPS 和 FTP 流量通过指定的代理服务器代理。其他流量则直接发送。在后一种情况下,行为稍显微妙:如果为 HTTP、HTTPS 或 FTP 协议配置了代理服务器,则相应的流量将通过指定的服务器代理。如果未指定此类代理服务器,或者流量使用的协议与 HTTP、HTTPS 或 FTP 不同,则系统会使用 fallbackProxy
。如果未指定 fallbackProxy
,则流量会直接发送,而不使用代理服务器。
代理服务器对象
代理服务器在 proxy.ProxyServer
对象中配置。与代理服务器的连接(由 host
属性定义)使用 scheme
属性中定义的协议。如果未指定 scheme
,则代理连接默认为 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 代理,用于连接到除 foobar.com 以外的所有服务器的 HTTP 连接,并对所有其他协议使用直接连接。这些设置会应用于常规窗口和无痕式窗口,因为无痕式窗口会沿用常规窗口的设置。另请参阅 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() {}
);
下一个代码段会查询当前的有效代理设置。有效代理设置可通过其他扩展程序或政策确定。如需了解详情,请参阅 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"
PacScript
包含代理自动配置信息的对象。且只能有一个字段不为空。
属性
-
data
字符串(可选)
PAC 脚本。
-
必填
布尔值 选填
如果为 true,无效的 PAC 脚本会阻止网络堆栈回退到直接连接。默认值为 false。
-
网址
字符串(可选)
要使用的 PAC 文件的网址。
ProxyConfig
用于封装完整代理配置的对象。
属性
-
模式
'direct' = 从不使用代理 'auto_detect' = 自动检测代理设置 'pac_script' = 使用指定的 PAC 脚本 'Fix_servers' = 手动指定代理服务器 'system' = 使用系统代理设置
-
pacScript
PacScript(可选)
此配置的代理自动配置 (PAC) 脚本。用于“pac_script”模式。
-
规则
ProxyRules 可选
描述此配置的代理规则。将其用于“Fixed_servers”模式。
ProxyRules
用于封装所有协议的代理规则集的对象。请使用“singleProxy”或“proxyForHttp”“proxyForHttps”“proxyForFtp”和“fallbackProxy”的子集。
属性
-
bypassList
string[] 可选
无需代理服务器即可连接的服务器列表。
-
fallbackProxy
ProxyServer 可选
用于其他一切或如果未指定任何具体 proxyFor... 的代理服务器。
-
proxyForFtp
ProxyServer 可选
用于 FTP 请求的代理服务器。
-
proxyForHttp
ProxyServer 可选
用于 HTTP 请求的代理服务器。
-
proxyForHttps
ProxyServer 可选
用于 HTTPS 请求的代理服务器。
-
singleProxy
ProxyServer 可选
适用于所有每个网址请求(即 http、https 和 ftp)的代理服务器。
ProxyServer
封装单个代理服务器规范的对象。
属性
-
主办方
string
代理服务器的主机名或 IP 地址。主机名必须采用 ASCII 格式(采用 Punycode 格式)。尚不支持 IDNA。
-
端口
数字可选
代理服务器的端口。默认为端口,具体取决于架构。
-
方案
架构(可选)
代理服务器本身的架构(协议)。默认值为“http”。
Scheme
枚举
"http"
"https"
"quic"
"socks4"
"socks5"
属性
settings
要使用的代理设置。此设置的值为 ProxyConfig 对象。
类型
types.ChromeSetting<ProxyConfigProxyConfig>
活动
onProxyError
chrome.proxy.onProxyError.addListener(
callback: function,
)
通知代理错误。
参数
-
callback
功能
callback
参数如下所示:(details: object) => void
-
明细
对象
-
明细
string
关于该错误的其他详细信息,例如 JavaScript 运行时错误。
-
error
string
错误说明。
-
fatal
boolean
如果为 true,则表示错误为严重错误,网络交易已取消。否则,会改用直接连接。
-
-