chrome.proxy

说明

您可以使用 chrome.proxy API 管理 Chrome 的代理设置。此 API 依赖于类型 API 的 ChromeSetting 原型 来获取和设置代理配置。

权限

proxy

此权限会触发警告。

清单

您必须在 扩展程序清单 中声明“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>"

示例

以下代码为 HTTP 连接设置了 SOCKS 5 代理，但 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() {}
);

下一个代码段会查询当前有效的代理设置。有效代理设置可以由其他扩展程序或政策确定。如需了解详情，请参阅 Types API 文档。

chrome.proxy.settings.get(
  {'incognito': false},
  function(config) {
    console.log(JSON.stringify(config));
  }
);

请注意，传递给 set() 的 value 对象与传递给 get() 的回调函数的 value 对象并不相同。后者将包含 rules.proxyForHttp.port 元素。

类型

Mode

Chrome 54 及更高版本

枚举

“direct”

“auto_detect”

“pac_script”

“fixed_servers”

“system”

PacScript

一个用于保存代理自动配置信息的对象。这些字段中应恰好有一个非空。

属性

• data

  字符串 可选

  PAC 脚本。

• mandatory

  布尔值 （可选）

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

• url

  字符串 可选

  要使用的 PAC 文件的网址。

ProxyConfig

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

属性

• mode

  Mode

  “direct”= 永不使用代理“auto_detect”= 自动检测代理设置“pac_script”= 使用指定的 PAC 脚本“fixed_servers”= 手动指定代理服务器“system”= 使用系统代理设置

• pacScript

  PacScript 可选

  此配置的代理自动配置 (PAC) 脚本。用于“pac_script”模式。

• rules

  ProxyRules 可选

  描述此配置的代理规则。用于“fixed_servers”模式。

ProxyRules

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

属性

• bypassList

  字符串数组 可选

  要连接的服务器列表，不使用代理服务器。

• fallbackProxy

  ProxyServer 可选

  用于其他所有内容或未指定任何特定 proxyFor... 的代理服务器。

• proxyForFtp

  ProxyServer 可选

  用于 FTP 请求的代理服务器。

• proxyForHttp

  ProxyServer 可选

  用于 HTTP 请求的代理服务器。

• proxyForHttps

  ProxyServer 可选

  用于 HTTPS 请求的代理服务器。

• singleProxy

  ProxyServer 可选

  用于所有按网址请求（即 http、https 和 ftp）的代理服务器。

ProxyServer

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

属性

• host

  字符串

  代理服务器的主机名或 IP 地址。主机名必须采用 ASCII 格式（Punycode 格式）。尚不支持 IDNA。

• port

  数字 可选

  代理服务器的端口。默认端口取决于方案。

• 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

  • details

    对象

    • details

      字符串

      有关错误的更多详细信息，例如 JavaScript 运行时错误。

    • error

      字符串

      错误说明。

    • fatal

      布尔值

      如果为 true，则表示错误很严重，网络事务已中止。否则，将改用直接连接。