chrome.proxy

说明

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

Chrome 54 及更高版本

枚举

"direct"

“auto_detect”

“pac_script”

“fixed_servers”

“system”

PacScript

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

属性

• 数据

  字符串（可选）

  PAC 脚本。

• 必填

  布尔值（可选）

  如果为 true，无效的 PAC 脚本将阻止网络堆栈回退到直接连接。默认值为 false。

• 网址

  字符串（可选）

  要使用的 PAC 文件的网址。

ProxyConfig

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

属性

• 模式

  Mode

  “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

Chrome 54 及更高版本

枚举

“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，则错误为严重，网络事务已中止。否则，系统会改用直接连接。