Skip to content

代理

HTTPX 支持通过 proxy 参数设置 HTTP 代理，该参数可以在客户端初始化时或通过顶级 API 函数如 httpx.get(..., proxy=...) 传递。

代理工作原理示意图（来源：维基百科）。左侧的"Internet"部分可能代表您的 HTTPX 客户端通过代理请求 example.com。

HTTP 代理

要将所有流量（HTTP 和 HTTPS）路由到位于 http://localhost:8030 的代理，只需将代理 URL 传递给客户端...

with httpx.Client(proxy="http://localhost:8030") as client:
    ...

对于更高级的用例，可以传递一个 mounts 字典。例如，要将 HTTP 和 HTTPS 请求分别路由到两个不同的代理（分别位于 http://localhost:8030 和 http://localhost:8031），可以传递一个代理 URL 字典：

proxy_mounts = {
    "http://": httpx.HTTPTransport(proxy="http://localhost:8030"),
    "https://": httpx.HTTPTransport(proxy="http://localhost:8031"),
}

with httpx.Client(mounts=proxy_mounts) as client:
    ...

有关代理路由的详细信息，请参阅 路由 部分。

注意

在大多数情况下，https:// 键对应的代理 URL 应该 使用 http:// 方案（这不是拼写错误！）。

这是因为 HTTP 代理需要与代理服务器建立初始连接。虽然您的代理可能支持通过 HTTPS 进行连接，但大多数代理仅支持通过 HTTP 进行连接。

更多信息请参阅 FORWARD 与 TUNNEL。

认证

代理凭据可以通过代理 URL 的 userinfo 部分传递。例如：

with httpx.Client(proxy="http://username:password@localhost:8030") as client:
    ...

代理机制

Note

本节介绍高级代理概念和功能。

转发(FORWARD)与隧道(TUNNEL)模式

通常，通过代理发起HTTP请求的流程如下：

  1. 客户端连接到代理（初始连接请求）。
  2. 代理代表您将数据传输到服务器。

第二步的具体执行方式取决于使用的两种代理机制之一：

  • 转发模式：代理为您发出请求，并返回从服务器获取的响应。
  • 隧道模式：代理代表您建立到服务器的TCP连接，客户端复用该连接发送请求和接收响应。这种机制被称为HTTP隧道。通过这种方式，您可以从HTTP代理访问使用HTTPS的网站（客户端通过与服务器在代理提供的TCP连接上进行TLS握手来"升级"连接至HTTPS）。

代理问题排查

如果在设置代理时遇到问题，请参考我们的问题排查指南。

SOCKS代理

除了HTTP代理外，httpcore还支持使用SOCKS协议的代理。这是可选功能，需要额外安装第三方库才能使用。

您可以使用pip安装SOCKS支持：

$ pip install httpx[socks]

现在可以配置客户端通过SOCKS协议代理发起请求：

httpx.Client(proxy='socks5://user:pass@host:port')