人人都会AI编程

13.2 代理配置与网络环境适配

更新时间：2026-07-11

企业环境中，桌面应用往往运行在复杂的网络条件下：公司内网需要经过 HTTP 代理才能访问外部接口，部分服务器仅在内网可达，甚至有些部署环境完全离线。Electron 应用如果不能灵活适配这些场景，轻则功能异常，重则完全无法启动。本节从实际工程角度出发，梳理代理配置的常见手段和环境适配的最佳实践。

13.2.1 让应用自动跟随系统代理

大部分企业用户的系统已经配置好了全局代理。Electron 默认使用 Chromium 的网络栈，而 Chromium 能够读取系统代理设置，但在某些情况下需要显式开启。

方法一：启动时通过命令行参数

在创建 BrowserWindow 或启动 app 时，可以设置 --proxy-server 参数。但这种硬编码方式不灵活，只适合固定代理地址的场景：

app.commandLine.appendSwitch('proxy-server', 'http://proxy.company.com:8080');

方法二（推荐）：使用 session.setProxy

通过 Electron 的 session 模块，可以将代理设置应用到整个应用或特定窗口的会话中，并支持复杂的 PAC 脚本与自动检测：

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

app.whenReady().then(() => {
  // 设置为系统代理（遵循 OS 级别的代理配置）
  session.defaultSession.setProxy({
    mode: 'system'
  });
});

mode 支持以下值：

  • 'direct'：直连，不使用代理
  • 'auto_detect'：自动检测（WPAD）
  • 'pac_script'：使用 PAC 脚本
  • 'fixed_servers'：固定代理服务器
  • 'system'：使用系统的代理设置（Windows 从 IE/设置 读取，macOS 从网络偏好读取）

获取系统代理的实际值

有时候你需要知道用户当前使用的具体代理地址（例如用于自定义网络请求），可以通过 session.resolveProxy 查询一个 URL 最终匹配到的代理：

const proxy = await session.defaultSession.resolveProxy('https://api.example.com');
console.log(proxy); // "PROXY proxy:8080" 或 "DIRECT"

13.2.2 手动配置代理与认证

企业代理常常需要用户名和密码验证，简单的 --proxy-server 参数无法处理认证。Electron 提供了 login 事件来处理这类场景。

方式一：监听 login 事件实现认证

当代理或服务器请求认证时，应用会触发 app 或 BrowserWindow 的 login 事件。你可以在其中提供凭据，甚至弹出一个自定义登录窗口让用户输入：

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

app.on('login', (event, webContents, request, authInfo, callback) => {
  event.preventDefault(); // 阻止默认的空凭据尝试
  // 从安全存储或用户输入中获取用户名密码
  const username = 'your_username';
  const password = 'your_password';
  callback(username, password);
});

authInfo 包含了 scheme（basic、digest、ntlm、negotiate）、realm 和 isProxy 等字段，可以根据需要判断是否为代理认证。

方式二：直接设置包含凭据的代理 URL

在 session.setProxy 的 fixed_servers 模式下，也可以将账号密码直接写入 URL（注意这种方式会将凭据以明文硬编码，不建议在生产环境长期使用）：

session.defaultSession.setProxy({
  mode: 'fixed_servers',
  proxyRules: 'http=user:pass@proxy.company.com:8080;https=proxy.company.com:8080'
});

13.2.3 PAC 脚本与企业网分流

大型企业通常使用 PAC（代理自动配置）脚本自动决定哪些请求走代理，哪些直连。Electron 可以通过设置 pacScript 来使用本地或远程的 PAC 文件。

使用远程 PAC 脚本

session.defaultSession.setProxy({
  mode: 'pac_script',
  pacScript: 'https://internal.company.com/proxy.pac'
});

使用本地 PAC 脚本

也可以将 PAC 脚本内嵌到应用资源中：

const pacContent = `
function FindProxyForURL(url, host) {
  if (shExpMatch(host, "*.internal.corp")) return "DIRECT";
  return "PROXY proxy.company.com:8080";
}`;

session.defaultSession.setProxy({
  mode: 'pac_script',
  pacScript: `data:text/javascript;base64,${Buffer.from(pacContent).toString('base64')}`
});

这种方式避免了外部依赖，离线环境也能生效，适合企业内部分发。

13.2.4 应对完全离线的部署环境

某些企业网络彻底切断外网，甚至连 NPM 依赖都需要在离线构建机上完成。此时 Electron 应用本身虽无需联网，但应用内的某些自动更新、统计埋点、CDN 资源加载等功能可能引发错误或长时间超时。

策略 1：条件性禁用网络请求

可以在主进程启动时检查网络连通性，然后动态关闭无关的网络模块：

const isOnline = require('is-online'); // 轻量检测模块

app.whenReady().then(async () => {
  const online = await isOnline();
  if (!online) {
    // 关闭自动更新检查
    autoUpdater.autoDownload = false;
    // 使用本地缓存资源
    BrowserWindow.addDevToolsExtension(null); // 示例
  }
});

策略 2：本地化所有外部依赖

将应用所需的外部资源（字体、图片、帮助文档等）全部打包进 resources 目录，确保渲染进程不依赖任何 CDN。在开发阶段就需要建立严格的资源管理规范，所有静态文件使用相对路径或 file:// 协议加载。

策略 3：离线缓存与 Service Worker

如果你的渲染进程是一个标准的 Web 应用，可以考虑注册 Service Worker 实现接口数据的离线缓存，使应用在断网时仍能展示历史数据，并提示用户当前为离线模式。

13.2.5 统一网络配置入口

为了让企业管理员或终端用户能够调整网络行为，建议在应用内部提供一个“网络设置”面板，集中管理代理、证书等参数。你可以：

  1. 将用户自定义的代理配置持久化到本地文件（如 JSON 或 electron-store）。
  2. 应用启动时读取配置，并调用 session.setProxy 动态应用。
  3. 提供“使用系统代理” / “手动配置” / “直接连接”三个选项，满足不同场景。

这样，即使用户更换办公环境（比如从公司内网切换到家庭网络），也无需修改代码或重启应用，只需切换设置即可。

13.2.6 常见问题与排错

问题 1：Chromium 的“不安全”证书错误

内网环境经常使用自签名证书或非公共 CA 签发的证书。Electron 默认拒绝这些证书。可以在 app 的 certificate-error 事件中添加例外处理：

app.on('certificate-error', (event, webContents, url, error, certificate, callback) => {
  event.preventDefault();
  // 仅在确认安全的内部域名下信任
  if (url.startsWith('https://internal.company.com')) {
    callback(true); // 信任证书
  } else {
    callback(false);
  }
});

警告：切勿无条件信任所有证书，这会引入严重的安全风险。

问题 2：WebSocket 连接复用代理设置

Electron 的 setProxy 配置同样影响 WebSocket 连接，但有时需要显式调整。如果发现 WebSocket 在代理后无法连接，检查代理是否支持 WebSocket 协议，或者尝试使用 --ignore-certificate-errors-spki-list 等参数进行调试。

问题 3：login 事件不触发

部分代理类型（如 NTLM/SSPI）的认证流程可能绕过 login 事件。这时可以尝试传递 --auth-server-whitelist 命令行参数，或者使用 app.commandLine.appendSwitch 来指定需要认证的域名。

总体来说，为 Electron 应用构建完善的网络环境适配能力，核心在于灵活运用 session.setProxy 和 login 事件，并预留出可控的配置界面。这不仅能让应用在企业防火墙内通畅运行，也能在离线、内网、VPN 切换等动态环境中保持稳定，真正达到生产级桌面应用的可靠性要求。