极安代理 - 开发者调试指南：移动端 App 如何调用系统代理 IP？

移动端 App 调试接口、验证地区返回结果或排查网络问题时，经常需要临时切换出口 IP。最省改动的办法，是在 Android 或 iOS 的 Wi-Fi 设置中填写代理服务器，让遵循系统网络配置的 App 自动通过代理访问网络。

不过，系统代理并不是“所有流量强制转发”。浏览器能通过代理访问，不代表目标 App 一定会跟随；HTTPS 证书、证书锁定、自定义网络库、QUIC 等因素，也可能影响最终结果。

## App 调用系统代理，实际上发生了什么？

严格来说，App 通常不需要主动调用一个“系统代理 API”。

开发者在当前 Wi-Fi 网络中配置代理服务器地址和端口后，系统会把这项配置提供给网络请求组件。使用系统标准网络栈、并且没有主动绕过代理的 App，会自动把 HTTP/HTTPS 请求发送给代理服务器，再由代理服务器访问目标接口。

基本链路如下：

> 移动端 App → 系统网络栈 → HTTP/HTTPS 代理 → 目标服务器

需要注意，手机设置中填写的是**代理入口地址和端口**，不一定是目标网站最终看到的出口 IP。

例如，使用固定隧道入口时，开发者可能一直填写同一个 `host:port`，但后端出口 IP会按照产品模式进行调度。使用短效代理时，填写的则可能是具有明确有效期的具体 IP 和端口，到期后需要重新获取。

## 调试前先准备哪些参数？

配置前至少确认以下信息：

- **代理类型**：HTTP、HTTPS还是SOCKS5；
- **服务器地址**：代理 IP或域名，不要把协议、账号和端口全部塞进主机名；
- **端口号**：例如8080、8888或服务商提供的专用端口；
- **认证方式**：IP白名单或用户名、密码；
- **代理用途**：是查看接口流量，还是切换业务请求的出口 IP。

这里有一个容易混淆的地方：

如果使用Charles、mitmproxy等调试工具，手机填写的通常是开发电脑在局域网中的地址，例如：

```text
代理服务器：192.168.1.20
端口：8888
```

此时手机和电脑要连接同一个局域网，并确保电脑防火墙允许该端口接入。

如果使用极安代理提供的远程代理，则填写控制台中取得的代理地址、端口和认证信息。此时主要作用是改变请求出口、测试地区和运营商环境，不等同于自动解密HTTPS内容。

## Android 如何配置系统代理 IP？

不同手机品牌的菜单名称略有区别，通用操作路径是：

1. 打开“设置”，进入“网络和互联网”或“WLAN”；
2. 点击当前已经连接的 Wi-Fi；
3. 选择“修改网络”或进入网络详情；
4. 展开“高级选项”；
5. 将“代理”由“无”改为“手动”；
6. 填写代理主机名、端口和不使用代理的地址；
7. 保存设置，重新打开待调试 App。

如果代理服务运行在开发电脑上，不能填写 `127.0.0.1`。在手机里，`127.0.0.1` 指向的是手机自身，应填写电脑在当前局域网中的 IP。

配置完成后，建议先用手机浏览器访问 IP 查询接口。浏览器显示的出口发生变化，再启动目标 App 测试。如果浏览器能通而 App 不通，问题通常不在代理 IP本身，而在 App 的网络实现或证书策略。

## Android 模拟器该用哪种代理？

Android Emulator提供了两套用途不同的代理机制。

**需要检查 App 的 HTTP/HTTPS 请求时，使用 Android 系统代理。**  
进入模拟器的“设置—网络和互联网—WLAN”，按真机方式填写代理。安装必要的调试证书后，这种方式可以配合Charles等工具检查HTTPS请求。

**需要让模拟器从受限网络访问互联网时，使用模拟器代理。**  
可以在模拟器 Extended Controls 的“Settings—Proxy”中设置，或者启动时传入：

```bash
emulator @MyAvd -http-proxy http://proxy.example.com:8080
```

带账密的写法为：

```bash
emulator @MyAvd -http-proxy http://username:password@proxy.example.com:8080
```

Android官方将两者明确区分：模拟器代理可以转发TCP流量，但HTTPS主要以隧道形式通过，不能依靠它直接进行SSL内容检查。做接口抓包时，不要把“模拟器能联网”误判为“已经能够查看HTTPS明文”。

## iOS 如何配置系统代理 IP？

iPhone或iPad的通用设置路径是：

1. 打开“设置—无线局域网”；
2. 点击当前 Wi-Fi 右侧的信息图标；
3. 下滑找到“配置代理”；
4. 选择“手动”；
5. 填写服务器和端口；
6. 代理需要账密时，打开“鉴定”并填写用户名、密码；
7. 保存设置，重新启动待调试 App。

这项配置通常只对当前 Wi-Fi 生效。切换到另一个 Wi-Fi，或者改用蜂窝网络后，原来的代理配置不会自动覆盖新网络。

普通 App 也不能随意修改整台iPhone的全局代理。Apple提供的 `NEProxySettings` 主要用于VPN配置生效期间的HTTP代理设置，涉及Network Extension、权限和相应的部署方式，不应和用户手动设置的Wi-Fi代理混为一谈。

## 为什么HTTP能通，HTTPS却失败？

HTTPS请求不仅要经过代理，还要完成证书校验。

如果只是通过普通代理改变出口 IP，客户端一般使用CONNECT建立加密隧道，代理无需读取请求明文。但如果开发者希望使用Charles、mitmproxy等工具查看HTTPS内容，调试工具必须动态签发站点证书，手机和App也必须信任对应的调试CA。

Android 7.0及以上环境中，面向较新API级别的App默认不一定信任用户自行安装的CA。自有App可以在Debug构建中使用Network Security Configuration配置仅用于调试的证书：

```xml
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <debug-overrides>
        <trust-anchors>
            <certificates src="@raw/debug_cas" />
        </trust-anchors>
    </debug-overrides>
</network-security-config>
```

同时在`AndroidManifest.xml`中引用：

```xml
<application
    android:networkSecurityConfig="@xml/network_security_config">
</application>
```

这类配置应限定在调试环境，不要为了方便抓包而降低正式版本的证书校验标准。

iOS也需要安装并显式信任调试CA。即使系统已经信任CA，如果App启用了Certificate Pinning，连接仍可能失败。证书固定本来就是为了防止中间人代理，测试时应使用专门的Debug构建处理，而不是修改线上安全逻辑。

## 浏览器代理成功，App为什么还是原来的 IP？

常见原因主要有以下几类。

### App没有继承系统代理

部分App会使用直连Socket、自定义网络引擎，或者在代码中明确指定不使用代理。此时系统Wi-Fi代理只影响浏览器和部分标准请求，无法强制接管该App。

如果调试的是自有Android项目，可以在Debug环境中给OkHttp等客户端显式配置代理：

```kotlin
val proxy = Proxy(
    Proxy.Type.HTTP,
    InetSocketAddress("proxy.example.com", 8080)
)

val client = OkHttpClient.Builder()
    .proxy(proxy)
    .build()
```

这属于App内代理，不是系统代理。它的优点是行为明确、便于自动化测试，但代理参数和认证信息不应硬编码进正式安装包。

### App使用了QUIC或其他UDP协议

普通HTTP代理主要处理HTTP/HTTPS请求，无法覆盖所有UDP流量。部分基于HTTP/3、QUIC或自定义协议的请求可能继续直连，或者直接连接失败。

调试时可以在可控的Debug环境中暂时关闭相关协议，确认问题是否来自传输层差异。

### 代理认证没有正确完成

部分Android系统设置界面只提供主机和端口，不提供统一的账号密码输入框。即使提供认证代理，不同App对`407 Proxy Authentication Required`的处理也不完全一致。

这类情况下可以使用IP白名单认证，或者在自有App的网络客户端中配置代理认证器。采用白名单时，要确认登记的是手机当前网络的实际公网出口，而不是手机的局域网地址。

### 连接没有重新建立

App可能复用了配置代理前已经建立的连接。修改代理后，建议彻底结束App进程再重新打开；仍未生效时，可以断开并重新连接Wi-Fi。

### 代理已过期或地区不匹配

短效代理具有明确的存活时间。配置和排查耗时较长时，可能出现刚测试成功、过几分钟就无法连接的情况。

地区测试还要以目标接口实际识别到的出口为准，不能只看控制台中选择的地区标签。

## 短效代理和隧道代理怎么选？

移动端手动调试更看重“配置是否方便”，不只是IP数量。

**一次性验证某个地区或运营商返回结果**，可以使用短效代理。配置完成后立即测试，并预留足够的有效时间。如果IP到期，需要重新提取并修改手机设置。

**需要反复启动App、切换页面或持续调试**，固定隧道入口通常更省事。手机端只配置一次入口，出口调度由代理服务完成，不需要每次手动替换主机和端口。

**涉及登录、购物车、连续分页等关联操作**，要避免在操作中途频繁更换出口。否则服务端可能把同一会话识别为网络环境异常。此时应选择支持会话保持的模式，让一组连续请求在合理时间内使用同一出口。

极安代理提供短效代理和隧道代理两种接入方式。开发者可以根据测试时长、地区要求和是否需要保持会话选择产品，而不是默认认为“换得越快越适合调试”。

## 一套更快的排查顺序

遇到移动端App无法使用代理时，可以按以下顺序检查：

1. 在电脑端验证代理地址、端口和认证信息是否有效；
2. 手机与本地抓包代理是否处于同一局域网；
3. 手机浏览器通过代理访问是否正常；
4. 目标App是否已经彻底重启；
5. App使用的网络库是否继承系统代理；
6. HTTPS证书是否受信任，是否存在证书锁定；
7. 请求是否使用QUIC、UDP或自定义Socket；
8. 代理是否过期，目标地区和运营商是否正确；
9. 切换回“无代理”，确认故障是否随代理配置消失。

这个顺序可以快速区分四类问题：代理节点不可用、网络不可达、App绕过系统代理，以及HTTPS安全策略阻断。不要一看到请求失败，就立即更换大量代理IP；先确认故障发生在哪一层，排查效率会高很多。

## 常见问题

**Q：手机设置系统代理后，所有App都会走代理吗？**

不会。使用标准系统网络栈的App通常会继承代理，但直连Socket、自定义网络库以及主动忽略代理配置的App可能不会跟随。

**Q：Wi-Fi代理能覆盖手机流量吗？**

通常不能。Android和iOS设置中的HTTP代理与具体Wi-Fi网络绑定，切换到蜂窝网络后需要采用App内代理、合规的VPN方案或受管理设备配置。

**Q：配置代理IP后可以直接看到HTTPS请求内容吗？**

不一定。改变出口只需要建立HTTPS隧道；查看加密内容还需要安装并信任调试CA。App启用证书锁定时，即使安装CA也可能无法解密。

**Q：为什么关闭App再打开仍然没有生效？**

需要进一步检查App是否真正退出、网络库是否忽略系统代理、是否复用后台连接，以及请求是否使用QUIC或其他不经过HTTP代理的协议。

**Q：移动端调试更适合短效代理还是隧道代理？**

短时间、单次地区验证可以使用短效代理；需要长时间反复测试时，固定入口的隧道代理通常更容易配置和维护。最终还要结合目标系统授权、会话时长和实际请求频率选择。

移动端调用系统代理的难点不在“把IP填进哪里”，而在于判断App的请求是否真的进入代理链路。开发者应先用浏览器验证代理连通性，再检查App网络栈、HTTPS证书和传输协议。只有分清系统代理、App内代理和VPN隧道的边界，才能准确判断问题来自代理资源，还是来自客户端实现。