chrome.proxy

清单文件

您必须在扩展程序的清单文件中声明 "proxy"（代理服务器）权限来使用代理服务器设置 API。例如：

      {
        "name": "我的扩展程序",
        ...
        "permissions": [
          "proxy"
        ],
        ...
      }
      

对象和属性

代理服务器设置定义在 proxy.ProxyConfig 对象中。取决于 Chrome 浏览器的代理服务器设置，设置可以包含 proxy.ProxyRules 对象或者一个 proxy.PacScript 对象。

代理服务器模式

ProxyConfig 对象的 mode 属性决定 Chrome 浏览器使用代理服务器的整体行为。它可以为以下值：

direct

在 direct 模式下所有连接都直接建立，不涉及任何代理服务器。使用这一模式时不允许 ProxyConfig 对象中包含其他任何参数。

auto_detect

在 auto_detect 模式下，代理服务器配置通过下载自 http://wpad/wpad.dat 的一个 PAC 脚本确定。使用这一模式时不允许 ProxyConfig 对象中包含其他任何参数。

pac_script

在 pac_script 模式下代理服务器配置由一个 PAC 脚本确定，它既可以从 proxy.PacScript 对象中指定的 URL 获取，也可以直接来自 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 属性，端口将使用协议的默认值。默认端口分别为：

例外列表

个别的服务器可以通过 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 地址的 URL。
概念上这和第一种情况相似，但是特别之处在于它会处理 IP 地址规范化的情况。例如匹配"[0:0:0::1]"与匹配"[::1]"是相同的，因为在内部会自动进行 IPv6 规范化。
例如："127.0.1", "[0:0::1]", "[::1]", "http://[::1]:99"

<ip-literal>/<prefix-length-in-bits>

匹配包含指定范围内 IP 地址的任何 URL，IP 范围使用 CIDR 记号表示。
例如："192.168.1.1/16", "fefe:13::abc/33"

<local>

匹配本机地址。本机地址包括主机为 "127.0.0.1"、"::1"或 "localhost" 的地址。
例如："<local>"

例子

以下代码为除了 foobar.com 以外的所有 HTTP 连接设置 SOCKS 5 代理，并为所有其他协议使用直接连接。这些设置应用于普通窗口和隐身窗口，因为隐身窗口从普通窗口继承设置。同时请参见类型 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() {});
      

下一个代码片段查询当前有效的代理服务器设置，有效代理服务器设置可以由另一个扩展程序或者其他策略确定。有关细节请参见类型 API。

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

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

摘要

示例扩展程序

• Proxy Extension API Sample – Set Chrome-specific proxies; a demonstration of Chrome's Proxy API