OkHttp 代理设置：2026年测试过的三种 Java 方法

TL;DR

OkHttp代理是在OkHttpClient.Builder上配置的，而不是在单个Request上。 使用.proxy(proxy)来指定一个明确的路由，或者不设置它，让proxySelector选择路由。
需要身份验证的代理需要proxyAuthenticator，它用Proxy-Authorization响应407挑战。 当该头部已存在时停止，这样错误的凭据就无法造成身份验证循环。
重用OkHttpClient实例，而不是每个请求创建一个。 少量预构建的客户端池提供可预测的端点轮换，而不会丢弃连接池和线程池。
HTTPS仍然通过HTTP代理使用CONNECT。 保持TLS验证启用，因为代理更改的是路由，而不是目标证书的要求。
在扩展之前验证路由。 比较观察到的出口IP，验证响应，并将代理连接错误与目标HTTP错误分开分类。

什么是OkHttp代理？

OkHttp代理是由OkHttpClient为出站HTTP和HTTPS连接选择的中介服务器。应用程序将流量发送到代理，代理将其转发到目标并返回响应。OkHttp仍然处理请求、响应、池、超时和TLS；代理控制网络路由和目标可见的源IP。

OkHttp使用Java的java.net.Proxy模型。当前的官方OkHttp代理API表示，显式的proxy优先于proxySelector。如果未设置显式代理，选择器可以从系统或应用程序策略中选择一个。传递Proxy.NO_PROXY强制进行直接连接。

这种标准配置可与内部网关、调试代理或托管端点（例如Nstdata Residential Prime Proxies）一起使用。代理更改路由；它不授予访问资源的权限，也不会替换特定于目标的速率限制和条款。

为什么与OkHttp使用代理？

当Java或Android应用程序需要受控的出站流量、本地化QA、广告验证、公共数据收集或流量类别之间的分离时，使用OkHttp的代理非常有用。它也可以使网络路径可重现：代码识别所选路线，而操作可以在部署之外更改端点。

会话模型应遵循工作流程。属于一个登录或结账流程的多个请求可能需要稳定的路由，而无关的检查可以使用轮换。Nstdata的IP轮换概述解释了该网络模式；应用程序仍需有限的并发、响应验证和重试限制。

import java.net.InetSocketAddress;
import java.net.Proxy;
import java.time.Duration;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

public final class BasicProxy {
    public static void main(String[] args) throws Exception {
        String proxyHost = requireEnv("PROXY_HOST");
        int proxyPort = Integer.parseInt(requireEnv("PROXY_PORT"));
        String targetUrl = System.getenv().getOrDefault(
                "TARGET_URL", "https://httpbin.org/ip");

        Proxy proxy = new Proxy(
                Proxy.Type.HTTP,
                new InetSocketAddress(proxyHost, proxyPort));

        OkHttpClient client = new OkHttpClient.Builder()
                .proxy(proxy)
                .connectTimeout(Duration.ofSeconds(5))
                .callTimeout(Duration.ofSeconds(15))
                .build();

        Request request = new Request.Builder().url(targetUrl).build();
        try (Response response = client.newCall(request).execute()) {
            if (!response.isSuccessful()) {
                throw new IllegalStateException("意外的状态: " + response.code());
            }
            System.out.println(response.body().string());
        }
    }

    private static String requireEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException(name + " 是必需的");
        }
        return value;
    }
}
```java

执行的测试返回了 HTTP 200，并在本地代理上显示了 `GET http://example.test/ip HTTP/1.1`。对于 HTTPS 目标，OkHttp 首先请求 HTTP 代理通过 CONNECT 创建一个隧道，然后通过该隧道执行 TLS 连接。不要禁用证书验证以解决路由或本地 CA 问题。

### 方法 2：添加代理用户名和密码认证

当端点需要基本的代理身份验证时，请使用 `proxyAuthenticator`。身份验证器在代理返回 `407 代理身份验证需要` 后运行；它应该添加凭据一次，如果相同请求已经有了该头部则停止。
```java
import java.net.InetSocketAddress;
import java.net.Proxy;

import java.time.Duration;
import okhttp3.Credentials;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

public final class AuthenticatedProxy {
    public static void main(String[] args) throws Exception {
        String proxyHost = requireEnv("PROXY_HOST");
        int proxyPort = Integer.parseInt(requireEnv("PROXY_PORT"));
        String proxyUser = requireEnv("PROXY_USER");
        String proxyPassword = requireEnv("PROXY_PASSWORD");
        String targetUrl = System.getenv().getOrDefault(
                "TARGET_URL", "https://httpbin.org/ip");

        Proxy proxy = new Proxy(
                Proxy.Type.HTTP,
                new InetSocketAddress(proxyHost, proxyPort));

        OkHttpClient client = new OkHttpClient.Builder()
                .proxy(proxy)
                .proxyAuthenticator((route, response) -> {
                    if (response.request().header("Proxy-Authorization") != null) {
                        return null;
                    }
                    String credential = Credentials.basic(proxyUser, proxyPassword);
                    return response.request().newBuilder()
                            .header("Proxy-Authorization", credential)
                            .build();
                })
                .connectTimeout(Duration.ofSeconds(5))
                .callTimeout(Duration.ofSeconds(15))
                .build();

        Request request = new Request.Builder().url(targetUrl).build();
        try (Response response = client.newCall(request).execute()) {
            if (!response.isSuccessful()) {
                throw new IllegalStateException("意外的状态: " + response.code());
            }
            System.out.println(response.body().string());
        }
    }

    private static String requireEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) {
            throw new IllegalArgumentException(name + " 是必需的");
        }
        return value;
    }
}

实时运行报告的代理端口为 `18180` 和 `18182`，顺序如此。在生产环境中，在每个客户端旁边存储一个非秘密的端点ID，按ID记录成功与延迟，并暂时隔离那些反复失败的端点。如果端点URL中嵌入凭证，请勿打印出来。 ## 显式代理 vs ProxySelector 使用`.proxy(proxy)`进行固定客户端策略，使用`proxySelector`进行目标意识路由。选择器可以针对不同的URI返回不同的Java `Proxy`值，并接收`connectFailed`通知。JDK的<a href="https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/net/Proxy.html" rel="nofollow noopener"><strong>java.net.Proxy 文档</strong></a>定义了HTTP、SOCKS和直接代理表示。请勿同时配置两者并期望它们合并。OkHttp仅在显式代理为null时咨询`proxySelector`。如果服务必须绕过代理以访问内部主机，则可以创建直接客户端或实现一个选择器，其`select(URI)`方法为这些主机返回`Proxy.NO_PROXY`。这种方式比依赖不显眼的机器级设置更清晰。 `ProxySelector`可以提供备用路由，但它不是自动的请求逐一轮换引擎。连接重用和路由恢复会影响使用哪个路由。对于网络级别的轮换，请使用提供者网关，或在每个应用调用必须有可审计的端点选择时使用故意的客户端池。 ## 如何验证OkHttp代理通过同时检查路由和响应来验证OkHttp代理。向授权的IP反射端点发送一个直接请求和一个通过代理的请求，然后比较报告的源地址。仅凭成功状态并不能证明代理处理了该调用。验证响应状态、内容类型和所需的主体字段。中介或目标可以返回带有HTTP 200的HTML块页面。[HTTP请求词汇表](https://www.nstdata.io/glossary/http-request)是请求/响应边界的一个有用参考。接下来，测试失败模式。使用无效端口确认连接超时、使用无效凭证确认有限的407结果，以及使用慢速授权目标确认调用超时。OkHttp事件监听器可以记录DNS、连接、TLS和响应时间，而不暴露机密。关于同一路由的另一种语言的视图，见[Guzzle代理指南](https://www.nstdata.io/blog/guzzle-proxy)，提供了一个有用的交叉检查。 ## 为OkHttp选择Nstdata路由 Nstdata Residential Prime Proxies适合需要经过身份验证的住宅路由的OkHttp应用程序，当前产品工作流提供会话和位置控制。Java只需要一个标准的主机、端口、用户名和密码；不需要特定于供应商的SDK来建立代理连接。查看[当前住宅高级计费模型](https://www.nstdata.io/pricing/residential)，并在选择生产路由之前测试确切的目标。 - **当提供者处理轮换时，优先选择一个网关。**这将保持OkHttp配置小并保留客户端重用。 - **对多请求会话使用粘性行为。**在所需的会话窗口内将相关调用保持在一个路由上。 - **仅在需要端点级控制时使用应用程序池。** 增加健康跟踪、有界重试和非秘密路由标识符，然后再增加并发性。 Android应用程序可以使用相同的OkHttp构建器API，但在移动二进制文件中传输长期代理凭证是有风险的。尽可能使用短期凭证或服务器端网络层。有关平台级替代方案，请参阅[Android代理服务器评论](https://www.nstdata.io/blog/best-proxy-server-for-android)。 ## 常见OkHttp代理错误和修复当连接层与目标响应分离时，修复OkHttp代理错误最简单。 | 症状 | 可能原因 | 实际修复 | |---|---|---| | `407 代理身份验证所需` | 缺少或被拒绝的代理凭证 | 确认用户名/密码，使用`proxyAuthenticator`，并在头部已经尝试后停止。 | | 连接超时或`ConnectException` | 错误的主机/端口、无法访问的路由或网络策略 | 验证端点并保持较短的`connectTimeout`；不要无限期重试。 | | TLS握手失败 | 无效的信任配置、中断或主机名不匹配 | 修复CA或路由；保持证书和主机名验证启用。 | | 代理似乎未使用 | 显式的 `Proxy.NO_PROXY`、选择器策略或其他客户端处理了调用 | 记录一个非秘密的客户端/路由 ID，并比较直接与代理退出 IP 的结果。 | | `403` 或 `429` | 目标拒绝或限制了请求 | 降低请求速率，确认授权，并遵循目标的规则。 | | 重复的 407 尝试 | 身份验证器在凭据已失效后返回新的请求 | 当 `Proxy-Authorization` 已存在时返回 `null`。 | 仅重试临时故障并使用退避策略。对于改变状态的请求，在重试之前添加幂等性保护。一个新的代理 IP 无法将无效请求转变为有效请求。 ## 结论最干净的 OkHttp 代理设置是针对一个稳定路由的显式 `Proxy`、用于 407 挑战的 `proxyAuthenticator` 或用于可审计的端点轮换的小池可重用客户端。将凭据保持在源之外，使用有限时间的超时，保留 TLS 验证，并确认出口路由和响应语义。从一个授权的目标和一个端点开始。记录成功的基线，然后仅在应用程序能够识别失败的路由并做出故意回退决定时，才添加轮换或选择逻辑。 ## 体验 Nstdata — 今天开始您的免费试用创建一个经过身份验证的端点，连接一个可重用的 OkHttp 客户端，并在扩展之前验证观察到的路由。 <a style="margin: 8px; display: inline-block; text-decoration: none; border-left-width: 0px;" href="https://app.nstdata.io/auth/login?utm_source=official&utm_medium=blog&utm_campaign=/okhttp-proxy/"> <div style="font-weight:bold; max-width:400px; padding:12px 40px; background:#646AEE; border-radius:5px; border:2px solid #646AEE; color:#fff; font-size:18px;"> 免费试用 Nstdata → </div> </a> ## 常见问题 **问：如何在 OkHttp 中设置代理？** 创建一个带有代理类型和 `InetSocketAddress` 的 `java.net.Proxy`，然后将其传递给 `new OkHttpClient.Builder().proxy(proxy).build()`。重用生成的客户端用于共享该路由的调用。 **问：如何在 OkHttp 中添加代理用户名和密码？** 配置 `proxyAuthenticator`，并返回一个后续请求，其中包含 `Proxy-Authorization`，通常使用 `Credentials.basic(user, password)` 构建。如果该头已经存在，则返回 `null` 以防止重复失败的尝试。 **问：OkHttp 是否支持通过 HTTP 代理使用 HTTPS？** 是的。OkHttp 使用 HTTP CONNECT 方法通过代理创建隧道，然后与目标执行 TLS。代理路由并不意味着可以禁用证书或主机名验证。 **问：显式的 OkHttp 代理是否会覆盖 ProxySelector？** 是的。OkHttp 的显式 `proxy` 设置具有优先权；只有在显式代理为 null 时才会咨询 `proxySelector`。当客户端必须始终直接连接时，使用 `Proxy.NO_PROXY`。 **问：我是否应该为每个轮转的请求创建一个新的 OkHttpClient？** 不。构建一组有限的可重用客户端——每个端点或路由策略一个——并在它们之间选择。这可以保留连接池，避免重复创建执行资源。

如何在 OkHttp 中使用代理（2026 完整指南）

TL;DR

什么是OkHttp代理？

为什么与OkHttp使用代理？

热门文章

如何使用 Axios 和代理：2026 完整指南

如何使用 HTTPX 代理：2026 完整指南

前提条件

通过 Nstdata 连接 OkHttp

如何使用 Proxy 与 OkHttp

方法 1：配置一个显式代理

方法3：轮换一组代理端点