Electron ProxyConfig 深度解析：proxy 五种模式、proxyRules 语法与 setProxy 源码实现

本文以 Electron API 文档中的 ProxyConfig 对象 为主体，完整讲解该结构的 mode、pacScript、proxyRules、proxyBypassRules 四个字段、规则语法与默认取值逻辑，并结合 Session::SetProxy 的 C++ 实现、命令行开关与 测试用例 说明其底层行为，帮助你在应用中正确配置代理、理解规则优先级并在排障时验证代理是否真正生效。

ProxyConfig 对象概述

ProxyConfig 是 Session.setProxy(config) 和 app.setProxy(config) 接收的参数结构，用于描述 Electron（底层即 Chromium 网络栈）应当采用何种代理策略。它由四个字段组成，除字段间的默认取值规则外，其余均为可选：

字段	类型	必填	说明
mode	string	否	代理模式，取 direct、auto_detect、pac_script、fixed_servers、system 之一
pacScript	string	否	PAC 文件的 URL
proxyRules	string	否	指定使用哪些代理服务器的规则字符串
proxyBypassRules	string	否	指定哪些 URL 绕过代理的规则字符串

mode 的默认逻辑在文档中有明确定义，也是 源码实现 中可逐一印证的行为：

• 若显式指定了 pacScript，默认模式为 pac_script；
• 否则默认模式为 fixed_servers。

文档还特别指出：当 mode 未指定、而 pacScript 与 proxyRules 同时提供时，proxyRules 会被忽略，pacScript 配置生效。也就是说 PAC 优先于静态规则。

mode：五种代理模式逐条解读

mode 决定网络栈决定“走不走代理、走哪个代理”的策略类型：

• direct：直接连接模式。所有连接都不经过任何代理直接创建。
• auto_detect：自动检测模式。代理配置由可通过 http://wpad/wpad.dat 下载的 PAC 脚本决定（WPAD 自动发现机制）。
• pac_script：PAC 脚本模式。代理配置由 pacScript 字段指定 URL 处的 PAC 脚本决定。这是指定了 pacScript 时的默认模式。
• fixed_servers：固定服务器模式。代理配置由 proxyRules 字段指定。这是指定了 proxyRules 时的默认模式。
• system：系统模式。代理配置取自操作系统。

文档中对 system 模式有一条容易被忽略的澄清：系统模式与“完全不设置代理配置”并不等价。后者的行为是只有当没有任何命令行选项影响代理配置时，Electron 才回退到系统设置；而显式指定 mode: 'system' 会主动从操作系统读取代理，语义更强。这一点与 命令行开关 中的 --proxy-server / --no-proxy-server 相互呼应：只要这些开关存在，网络栈就会遵循它们，而不会走系统配置。

无效 mode 的运行时行为

从 Session::SetProxy 的实现看，mode 会经过 ProxyPrefs::StringToProxyMode 解析，解析失败时 Promise 会以 "Invalid mode, must be one of direct, auto_detect, pac_script, fixed_servers or system" 拒绝。这一点在 spec/api-session-spec.ts 中有对应断言：

await expect(customSession.setProxy(config)).to.eventually.be.rejectedWith(/Invalid mode/);

即传错 mode 不会静默降级，而是能显式捕获的异常，利于在启动阶段尽早暴露配置错误。

proxyRules：BNF 语法与八个典型示例

proxyRules 是固定服务器模式的核心，必须遵循以下文法：

proxyRules = schemeProxies[";"<schemeProxies>]
schemeProxies = [<urlScheme>"="]<proxyURIList>
urlScheme = "http" | "https" | "ftp" | "socks"
proxyURIList = <proxyURL>[","<proxyURIList>]
proxyURL = [<proxyScheme>"://"]<proxyHost>[":"<proxyPort>]

文法含义：整条规则由若干 schemeProxies 以 ; 串联；每一项可选地以 urlScheme= 前缀限定作用协议；值部分是一个以 , 分隔的 proxyURL 列表，天然表达“主备回退”顺序；proxyURL 可省略 proxyScheme（省略即按 HTTP 代理处理）与端口（省略即用该协议默认端口）。

文档给出的八个示例覆盖了文法的典型组合，逐一解读如下：

规则	语义
http=foopy:80;ftp=foopy2	http:// URL 走 HTTP 代理 foopy:80，ftp:// URL 走 foopy2:80
foopy:80	所有 URL 都走 HTTP 代理 foopy:80
foopy:80,bar,direct://	所有 URL 先走 foopy:80，不可用则回退 bar，再不可用则直连
socks4://foopy	所有 URL 走 SOCKS v4 代理 foopy:1080
http=foopy,socks5://bar.com	http URL 走 foopy，不可用则回退 SOCKS5 代理 bar.com
http=foopy,direct://	http URL 走 foopy，不可用则直连
http=foopy;socks=foopy2	http URL 走 foopy，其余 URL 走 socks4://foopy2

注意两个容易踩坑的细节：其一，http=foopy;socks=foopy2 中第二项未写 http 前缀，socks 前缀只限定协议匹配，其余协议（含 https）落入 socks=foopy2；其二，direct:// 是列表中的合法“成员”，用于表达“最终放弃代理、直连”，而不仅仅是省略规则。

proxyBypassRules：五类绕过规则语法

proxyBypassRules 是逗号分隔的规则列表，共五种形态：

1. 主机名模式：[ URL_SCHEME "://" ] HOSTNAME_PATTERN [ ":" <port> ] 匹配所有符合 HOSTNAME_PATTERN 的主机名。例如：foobar.com、*foobar.com、*.foobar.com、*foobar.com:99、https://x.*.y.com:99。
2. 域名后缀："." HOSTNAME_SUFFIX_PATTERN [ ":" PORT ] 匹配特定域名后缀。例如：.google.com、.com、http://.google.com。
3. IP 字面量：[ SCHEME "://" ] IP_LITERAL [ ":" PORT ] 匹配 URL 直接是 IP 地址字面量的情况。例如：127.0.1、[0:0::1]、[::1]、http://[::1]:99。
4. CIDR 网段：IP_LITERAL "/" PREFIX_LENGTH_IN_BITS 以 CIDR 记法匹配落在给定区间内的 IP 字面量。例如：192.168.1.1/16、fefe:13::abc/33。
5. <local>：匹配本地地址，其含义是主机是否匹配 127.0.0.1、::1 或 localhost。

测试用例 中还展示了一个文档未展开的特殊写法 <-loopback>：它用于移除内置的 localhost 隐式绕过规则，从而让回环地址也走代理——这是调试代理本身（例如代理部署在本机时）的关键技巧：

const config = {
  proxyRules: 'http=myproxy:80',
  proxyBypassRules: '<-loopback>'
};
await customSession.setProxy(config);

源码实现：setProxy 如何落到 Chromium 网络栈

字段解析与默认 mode

Session::SetProxy 的解析流程与文档描述完全一致：

std::string mode, proxy_rules, bypass_list, pac_url;

options.Get("pacScript", &pac_url);
options.Get("proxyRules", &proxy_rules);
options.Get("proxyBypassRules", &bypass_list);

ProxyPrefs::ProxyMode proxy_mode = ProxyPrefs::MODE_FIXED_SERVERS;
if (!options.Get("mode", &mode)) {
  // pacScript takes precedence over proxyRules.
  if (!pac_url.empty()) {
    proxy_mode = ProxyPrefs::MODE_PAC_SCRIPT;
  } else {
    proxy_mode = ProxyPrefs::MODE_FIXED_SERVERS;
  }
} else {
  if (!ProxyPrefs::StringToProxyMode(mode, &proxy_mode)) {
    promise.RejectWithErrorMessage(
        "Invalid mode, must be one of direct, auto_detect, pac_script, "
        "fixed_servers or system");
    return handle;
  }
}

源码注释 // pacScript takes precedence over proxyRules. 直接印证了文档中“pacScript 与 proxyRules 同时提供时忽略 proxyRules”的默认规则。

写入 pref 并映射为 Chromium ProxyConfig

解析完成后，配置通过 createProxyConfig 转换为 Chromium 的 ProxyConfigDictionary 并写入内存 pref store：

browser_context_->in_memory_pref_store()->SetValue(
    proxy_config::prefs::kProxy,
    base::Value{
        createProxyConfig(proxy_mode, pac_url, proxy_rules, bypass_list)},
    WriteablePrefStore::DEFAULT_PREF_WRITE_FLAGS);

createProxyConfig 按模式分派到 Chromium 的对应构造器：CreateDirect()、CreateSystem()、CreateAutoDetect()、CreatePacScript(pac_url, /*pac_mandatory=*/true) 或 CreateFixedServers(proxy_server, bypass_list)。值得注意的是 PAC 模式下 pac_mandatory 恒为 true，即 PAC 脚本不可用时会按配置策略强制处理而非静默降级。

另外从源码结构看还有一个细节：SetProxy 开头检查 browser_context_->in_memory_pref_store()，若不存在则直接 Resolve 而不做任何事——可以推断，对不具备内存 pref store 的会话（如持久化分区），运行时动态改代理不生效，这类场景应改用命令行开关在启动时注入代理。

相关配套 API

• ses.forceReloadProxyConfig()：实现于 ForceReloadProxyConfig，调用底层 NetworkContext::ForceReloadProxyConfig，用于强制重新加载代理配置（例如 PAC 更新后）。
• ses.resolveProxy(url)：返回指定 URL 最终解析出的代理字符串（形如 PROXY myproxy:80），测试用例 用它验证配置真正生效：

const config = { proxyRules: 'http=myproxy:80' };
await customSession.setProxy(config);
const proxy = await customSession.resolveProxy('http://example.com/');
expect(proxy).to.equal('PROXY myproxy:80');

• ses.closeAllConnections()：Session 文档 明确提示，修改代理后可能需要调用它关闭在途连接，防止连接池中被复用的旧 socket 仍经由旧代理发出请求。这是“改了 setProxy 却感觉没生效”的常见原因之一。

与命令行开关的配合关系

ProxyConfig 是运行时 API，而代理还可以由 命令行开关 在进程启动时决定（--proxy-server=address:port、--no-proxy-server、--proxy-pac-url 等）。结合 system 模式的文档说明可以得出配置优先级的实用认知：

1. 显式 setProxy（或启动时的 pref 设置）作用于对应 Session 的网络上下文；
2. 命令行开关会影响全局代理判定；未设置任何代理配置时，Electron 仅在无命令行选项干预的情况下才回退系统设置；
3. 需要“跟随系统代理”时显式传 mode: 'system'，比“什么都不设”的语义更明确、更可预测。

实用示例

按上文文法组合一个完整的 setProxy 调用：

const { session } = require('electron');

const ses = session.defaultSession;

await ses.setProxy({
  mode: 'fixed_servers',
  proxyRules: 'http=proxy.corp:8080,https=proxy.corp:8080,direct://',
  proxyBypassRules: 'localhost,*.corp,192.168.0.0/16'
});

// 验证解析结果
console.log(await ses.resolveProxy('http://example.com/')); // PROXY proxy.corp:8080

若使用 PAC 脚本，则可省略 mode（由 pacScript 推导为 pac_script 模式）：

await ses.setProxy({
  pacScript: 'http://proxy.corp/proxy.pac'
});

小结

ProxyConfig 用四个字段覆盖了 Chromium 网络栈的全部代理策略：mode 选择策略类型（默认时 pacScript 优先于 proxyRules，否则落到 fixed_servers），proxyRules 以 scheme=host:port[,fallback...] 文法表达按协议、带回退顺序的静态代理，proxyBypassRules 以主机名/后缀/IP/CIDR/<local> 五类规则定义绕行集合。从 electron_api_session.cc 的实现可见，这些字段最终经 ProxyPrefs 校验后写入 kProxy pref 并映射为 ProxyConfigDictionary；resolveProxy 与 forceReloadProxyConfig 则提供了验证与刷新手段。掌握这套结构后，无论是企业代理环境、本地调试代理还是 PAC 动态策略，都能在 Electron 应用中准确落地。