chrome.proxy

refresh date: 2026-09-25 robots: noindex

说明

权限

清单

必须在扩展程序清单中声明“代理”权限，才能使用代理设置 API。例如：

{
  "name": "My extension",
  ...
  "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 对象中指定的网址检索，也可以直接从 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 地址字面的网址。从概念上讲，这与第一种情况类似，但增加了用于处理 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>"

示例

以下代码为与除 foobar.com 之外的所有服务器的 HTTP 连接设置了 SOCKS 5 代理，并为所有其他协议使用了直接连接。这些设置适用于常规窗口和无痕式窗口，因为无痕式窗口会继承常规窗口的设置。另请参阅 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 元素。

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