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 对象中指定的网址检索，或者从 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>"

示例

以下代码设置了 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 对象与传递给 get() 回调函数的 value 对象不同。后者将包含一个 rules.proxyForHttp.port 元素。

类型

Mode

Chrome 54 及更高版本

枚举

"auto_detect"

"pac_script"

PacScript

包含代理自动配置信息的对象。且只能有一个字段不为空。

属性

• data

  字符串（可选）

  PAC 脚本。

• 必填

  布尔值 选填

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

• 网址

  字符串（可选）

  要使用的 PAC 文件的网址。

ProxyConfig

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

属性

• 模式

  Mode

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

• pacScript

  PacScript（可选）

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

• 规则

  ProxyRules 可选

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

ProxyRules

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

属性

• bypassList

  string[] 可选

  无需代理服务器即可连接的服务器列表。

• fallbackProxy

  ProxyServer 可选

  用于其他一切或如果未指定任何具体 proxyFor... 的代理服务器。

• proxyForFtp

  ProxyServer 可选

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

• proxyForHttp

  ProxyServer 可选

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

• proxyForHttps

  ProxyServer 可选

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

• singleProxy

  ProxyServer 可选

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

ProxyServer

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

属性

• 主办方

  string

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

• 端口

  数字可选

  代理服务器的端口。默认为端口，具体取决于架构。

• 方案

  架构（可选）

  代理服务器本身的架构（协议）。默认值为“http”。

Scheme

Chrome 54 及更高版本

枚举

"http"

"https"

"quic"

"socks4"

"socks5"

属性

settings

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

类型

types.ChromeSetting<ProxyConfigProxyConfig>

活动

onProxyError

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

通知代理错误。

参数

• callback

  功能

  callback 参数如下所示：

  (details: object)=>void

  • 明细

    对象

    • 明细

      string

      关于该错误的其他详细信息，例如 JavaScript 运行时错误。

    • error

      string

      错误说明。

    • fatal

      boolean

      如果为 true，则表示错误为严重错误，网络交易已取消。否则，会改用直接连接。