HarmonyOS —— Remote Communication Kit 定制代理（ProxyConfiguration）实战笔记

前面你已经看了 DNS（DnsConfiguration）、数据传输（TransferConfiguration），这一篇就把“第三兄弟”——代理配置 ProxyConfiguration 补上，一起把 HarmonyOS 远场通信框架里网络请求“底层三件套”搞清楚。

---

一、ProxyConfiguration 是干嘛用的？

在 HarmonyOS 的远场通信框架（Remote Communication Kit）里，每一次 HTTP 请求其实都可以决定：

“这次请求要不要走代理？
如果走，用谁的代理？系统的？还是我自己配的 Web 代理？”

这个“用不用代理、用什么代理”的统一入口，就是 ProxyConfiguration。
它支持三种模式：

1. 'system'：使用系统代理
2. 'no-proxy'：完全不走代理
3. WebProxy 对象：自定义 Web 代理设置

你可以把它脑补成类似浏览器里的网络设置：

• 跟随系统 → 'system'
• 直连网络 → 'no-proxy'
• 指定 HTTP(S) 代理 → WebProxy

---

二、设备与版本限制（老熟人了）

文档里这句你已经很熟悉了，和 DNS / Transfer 是同一套：

• 支持设备：
  • Phone
  • 2in1
  • Tablet
  • Wearable
• 从 5.1.1(19) 开始：
  • 新增支持 TV 设备

直接背成一条：

ProxyConfiguration 支持 Phone / 2in1 / Tablet / Wearable，自 5.1.1(19) 起新增 TV 支持。

---

三、三种代理模式：什么时候用哪个？

1. 'no-proxy'：完全不走代理

适用场景：

• 某些接口必须直连后端（例如内网接口、特殊网络环境）；
• 环境里已经有系统代理，但你不想这条请求被代理拦/转发；
• 调试排查问题时，想先排除代理因素。

核心配置代码：

import { rcp } from '@kit.RemoteCommunicationKit';
import { BusinessError } from '@kit.BasicServicesKit';

// 创建会话
const session = rcp.createSession();

// 定义请求 URL
const requestURL = 'https://example.com';

// 配置请求的 proxy 方式为 'no-proxy'
const configuration: rcp.Configuration = {
  proxy: 'no-proxy'
};

// 定义 request，并把配置挂上去
const request = new rcp.Request(requestURL, 'GET');
request.configuration = configuration;

// 发起请求
session.fetch(request).then((response: rcp.Response) => {
  console.info(`Response success, ${response}`);
  session.close();
}).catch((err: BusinessError) => {
  console.error(`The error code is ${err.code}, error message is ${JSON.stringify(err)}`);
  session.close();
});

一句话记忆：

有系统代理也当没这回事，我这条请求一定要走直连。

---

2. 'system'：使用系统代理

适用场景：

• 设备上已经配置了系统级代理（比如企业 Wi-Fi、调试代理等），
  你只想跟着系统走，不用额外折腾；
• 快速部署、通用场景，最懒、但最不容易出错的方案。

配置代码：

import { rcp } from '@kit.RemoteCommunicationKit';
import { BusinessError } from '@kit.BasicServicesKit';

const session = rcp.createSession();
const requestURL = 'https://example.com';

// 使用系统代理
const configuration: rcp.Configuration = {
  proxy: 'system'
};

const request = new rcp.Request(requestURL, 'GET');
request.configuration = configuration;

session.fetch(request).then((response: rcp.Response) => {
  console.info(`Response success, ${response}`);
  session.close();
}).catch((err: BusinessError) => {
  console.error(`The error code is ${err.code}, error message is ${JSON.stringify(err)}`);
  session.close();
});

一句话记忆：

交给系统帮我决定走哪个代理，我自己不操心。

---

3. WebProxy：自定义代理设置（重点）

第三种模式是对象形式的 WebProxy 配置，适合这些场景：

• 公司有 统一的 HTTP/HTTPS 代理（比如统一出口、防火墙等）；
• 只希望部分域名走代理，部分域名直连；
• 需要特定的隧道策略（createTunnel）来优化 HTTPS 访问。

示例配置：

import { rcp } from '@kit.RemoteCommunicationKit';
import { BusinessError } from '@kit.BasicServicesKit';

const session = rcp.createSession();
const requestURL = 'https://example.com';

// 自定义 WebProxy 配置
const configuration: rcp.Configuration = {
  proxy: {
    url: 'https://www.example.com',  // 代理服务器地址
    createTunnel: 'always',          // 隧道策略
    exclusions: [                    // 不通过代理的地址/域名列表
      'https://www.example1.com',
      'https://www.example2.com'
    ]
  }
};

const request = new rcp.Request(requestURL, 'GET');
request.configuration = configuration;

session.fetch(request).then((response: rcp.Response) => {
  console.info(`Response success, ${response}`);
  session.close();
}).catch((err: BusinessError) => {
  console.error(`The error code is ${err.code}, error message is ${JSON.stringify(err)}`);
  session.close();
});

几个关键字段帮你翻译一下：

• url
  代理服务器地址（HTTP/HTTPS），相当于“所有请求先发给这个代理”。
• createTunnel
  隧道策略，示例里用的是 'always'：
  一般可以理解为——对 HTTPS 等场景总是通过 CONNECT 建立隧道，保证端到端安全（具体可再查 WebProxy 配置文档的枚举值）。
• exclusions
  这里列出来的 URL / 域名，不走代理，直接直连。
  典型场景：
  • 公司自己内网服务直连；
  • 某些本地域名访问不想绕代理。

一句话记忆：

WebProxy = “我自己指定代理服务器 + 哪些地址走代理 / 哪些绕过”。

---

四、三种模式的对比总结（考试/面试用的小表）

模式	配置写法	是否走代理	典型场景
no-proxy	proxy: 'no-proxy'	❌ 不走代理	内网直连、绕开系统代理、排查问题
system	proxy: 'system'	✅ 跟随系统设置	快速接入、默认安全选择
WebProxy	proxy: { url, createTunnel, exclusions }	✅ 按自定义规则	企业统一出口、需要精细控制代理策略

---

五、一句顶一页的记忆版

• ProxyConfiguration 负责的就是：

  会话/请求的“走哪条代理通道”。

• 三种模式：

  • 不走代理：'no-proxy'
  • 跟随系统：'system'
  • 完全自定义：WebProxy 对象（url + createTunnel + exclusions）

• 设备支持：

  Phone / 2in1 / Tablet / Wearable，5.1.1(19) 起新增 TV。