chrome.proxy

描述 使用 chrome.proxy API 管理百度浏览器的代理服务器设置。该模块依赖于类型 API 中的 ChromeSetting 原型,用于获取和设置代理服务器配置。
可用版本 从 Chrome 13 开始支持。
权限 "proxy"

清单文件

您必须在应用的清单文件中声明 "proxy"(代理服务器)权限来使用代理服务器设置 API。例如:

      {
        "name": "我的应用",
        ...
        "permissions": [
          "proxy"
        ],
        ...
      }
      

对象和属性

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

代理服务器模式

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

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 模式与不设置代理服务器配置不同,在后一种情况下,百度浏览器只有在没有任何命令行选项影响代理服务器配置的情况下才会使用系统设置。

代理服务器规则

proxy.ProxyRules 对象可以包含一个 singleProxy 属性或者 proxyForHttpproxyForHttpsproxyForFtpfallbackProxy 这些属性中的一个子集。

在第一种情况下,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 地址的 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 元素。

摘要

类型
ProxyServer
ProxyRules
PacScript
ProxyConfig
属性
settings
事件
onProxyError

类型

ProxyServer

包含单个代理服务器信息的对象。
属性
enum of "http", "https", "quic", "socks4", or "socks5" (可选)
scheme

代理服务器自己的协议,默认为 "http"。

string host

代理服务器的 URL,必须为 ASCII 主机名(以 Punycode 的格式),暂时还不支持 IDNA。

integer (可选)
port

代理服务器的端口,默认值与协议相关。

ProxyRules

包含用于所有协议的代理规则的对象。仅使用 "singleProxy" 属性或者使用以下属性(及其子集):"proxyForHttp"、"proxyForHttps"、"proxyForFtp" 和 "fallbackProxy"。
属性
ProxyServer (可选)
singleProxy

用于所有 URL 请求(即 HTTP、HTTPS 和 FTP)的代理服务器。

ProxyServer (可选)
proxyForHttp

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

ProxyServer (可选)
proxyForHttps

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

ProxyServer (可选)
proxyForFtp

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

ProxyServer (可选)
fallbackProxy

用于其他协议或者未指定 proxyFor... 的协议的代理服务器。

array of string (可选)
bypassList

不通过代理服务器连接的服务器列表。

PacScript

包含代理自动配置信息的对象。以下前两个属性中有且只有一个非空。
属性
string (可选)
url

要使用的 PAC 文件 URL。

string (可选)
data

PAC 脚本内容。

boolean (可选)
mandatory

如果为 true,无效的 PAC 脚本将不会使网络栈回退到直接连接方式。默认为 false。

ProxyConfig

包含完整代理配置的对象。
属性
ProxyRules (可选)
rules

描述该配置的代理规则。请在 "fixed_servers" 模式下使用该属性。

PacScript (可选)
pacScript

该配置下的代理服务器自动配置(PAC)脚本。请在 "pac_script" 模式下使用该属性。

enum of "direct", "auto_detect", "pac_script", "fixed_servers", or "system" mode

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

属性

types.ChromeSetting chrome.proxy.settings 使用的代理服务器设置,这一设置的值是一个 ProxyConfig 对象。

事件

onProxyError

通知代理服务器错误。

addListener

chrome.proxy.onProxyError.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数:

function(object details) {...};
object details
boolean fatal

如果为 true,该错误是致命的,网络连接将终止。否则,将改用直接连接。

string error

错误描述。

string details

有关错误的其他详情,例如 JavaScript 运行时错误。