chrome.proxy (original) (raw)

说明

权限

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 对象中指定的网址，或直接从 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

包含代理自动配置信息的对象。必须有一个字段为非空字段。

属性

ProxyConfig

封装了完整代理配置的对象。

属性

ProxyRules

用于封装所有协议的一组代理规则的对象。使用“singleProxy”或“proxyForHttp”“proxyForHttps”“proxyForFtp”的子集和“fallbackProxy”

属性

ProxyServer

用于封装单个代理服务器规范的对象。

属性

Scheme

枚举

“http”

“https”

"quic"

"socks4"

"socks5"

属性

settings

要使用的代理设置。此设置的值为 ProxyConfig 对象。

类型

事件

onProxyError

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

通知有关代理错误。

参数