说明
使用 chrome.proxy
API 管理 Chrome 的代理设置。此 API 依赖 ChromeSetting 类型 API 原型来获取和设置代理配置。
权限
proxy
清单
{
"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
对象中指定的网址,或直接从data
元素中获取proxy.PacScript
对象中指定的任何 ID。除此之外,此模式不允许使用任何其他参数, 在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
对象与传递到 的 value
对象不同
回调函数 get()
。后者将包含 rules.proxyForHttp.port
元素。
类型
Mode
枚举
"direct"
“auto_detect”
“pac_script”
“fixed_servers”
“system”
PacScript
包含代理自动配置信息的对象。必须有一个字段为非空字段。
属性
-
数据
字符串(可选)
PAC 脚本。
-
必填
布尔值(可选)
如果为 true,无效的 PAC 脚本将阻止网络堆栈回退到直接连接。默认值为 false。
-
网址
字符串(可选)
要使用的 PAC 文件的网址。
ProxyConfig
封装了完整代理配置的对象。
属性
-
模式
“direct”= 从不使用代理 “auto_detect”= 自动检测代理设置 “pac_script”= 使用指定的 PAC 脚本 “fixed_servers”= 手动指定代理服务器 “system”= 使用系统代理设置
-
pacScript
PacScript 可选
此配置的代理自动配置 (PAC) 脚本。将此用于“pac_script”模式。
-
规则
ProxyRules 可选
描述此配置的代理规则。将此用于“fixed_servers”模式。
ProxyRules
用于封装所有协议的一组代理规则的对象。使用“singleProxy”或“proxyForHttp”“proxyForHttps”“proxyForFtp”的子集和“fallbackProxy”
属性
-
bypassList
string[] 选填
要在没有代理服务器的情况下连接的服务器列表。
-
fallbackProxy
ProxyServer 可选
用于其他任何用途或未指定任何特定 agentFor... 的代理服务器。
-
proxyForFtp
ProxyServer 可选
用于 FTP 请求的代理服务器。
-
proxyForHttp
ProxyServer 可选
要用于 HTTP 请求的代理服务器。
-
proxyForHttps
ProxyServer 可选
用于 HTTPS 请求的代理服务器。
-
singleProxy
ProxyServer 可选
要用于所有 Per-网址 请求(即 http、https 和 ftp)的代理服务器。
ProxyServer
用于封装单个代理服务器规范的对象。
属性
-
主机
字符串
代理服务器的主机名或 IP 地址。主机名必须采用 ASCII(Punycode 格式)。目前尚不支持 IDNA。
-
端口
编号(选填)
代理服务器的端口。默认为取决于 scheme 的端口。
-
方案
Scheme 可选
代理服务器本身的架构(协议)。默认值为“http”。
Scheme
枚举
“http”
“https”
"quic"
"socks4"
"socks5"
属性
settings
要使用的代理设置。此设置的值为 ProxyConfig 对象。
类型
types.ChromeSetting<ProxyConfig>
事件
onProxyError
chrome.proxy.onProxyError.addListener(
callback: function,
)
通知有关代理错误。
参数
-
callback
函数
callback
参数如下所示:(details: object) => void
-
详细信息
对象
-
详细信息
字符串
有关错误的其他详细信息,例如 JavaScript 运行时错误。
-
错误
字符串
错误说明。
-
fatal
布尔值
如果为 true,则错误为严重,网络事务已中止。否则,系统会改用直接连接。
-
-