按协议为 HTTPX 配置 HTTP 与 SOCKS 代理-未完纪

HTTPX 可以通过 proxy 参数使用 HTTP 代理。这个参数既可以在初始化客户端时设置，也可以传给 httpx.get(..., proxy=...) 这样的顶层 API。配置之前，需要有一台可达的代理服务器；客户端参数不会替你启动代理服务。

本文完整翻译并整理 HTTPX 官方文档的 Proxies 页面，覆盖 HTTP 代理、按目标协议路由、认证、转发与隧道以及 SOCKS。原文未标注固定发行版本；这里沿用核对时文档中的 proxy、mounts 和 HTTPTransport 接口。所有示例仅做静态审查，没有安装依赖或发送网络请求。

按目标协议选择传输；代理 URL 的协议与目标协议独立。原创示意：未完纪稿件整理。

使用一个 HTTP 代理

如果希望 HTTP 和 HTTPS 请求都经过 http://localhost:8030，把代理 URL 传给客户端即可：

import httpx

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

localhost:8030 是示例地址，表示运行 Python 程序的这台机器上的代理端口。它不是 HTTPX 自带的服务。代码中的 ... 是放置业务请求的位置，整段示例只展示客户端配置。

按目标协议选择不同代理

更复杂的路由可以使用 mounts 字典。例如，让 HTTP 请求经过本机 8030 端口，让 HTTPS 请求经过本机 8031 端口：

import httpx

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

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

字典的键匹配的是目标网址的协议。值是带有代理配置的传输对象，不是简单的 URL 字符串。关于更细的匹配方式，可以继续阅读官方文档的 Routing 一节。

这里最容易混淆的是："https://" 对应的代理地址通常仍应写成 "http://..."，这不是拼写错误。目标使用 HTTPS，只说明客户端最终要与目标网站建立 TLS 连接；代理 URL 的协议描述的则是客户端如何连接代理服务器。多数 HTTP 代理接受普通 HTTP 连接，只有代理自身确实支持 TLS 时，才考虑以 HTTPS 连接代理。不能仅因为目标是 HTTPS，就把代理地址改成 https://。

在代理 URL 中提供认证信息

代理用户名和密码可以放在 URL 的 userinfo 部分，也就是主机名前面的 username:password@：

import httpx

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

这里的用户名和密码都是占位值。整理说明：实际凭据不应直接提交到源码、复制进公开日志或截图；含有 @、: 等 URL 保留字符的值，也不能直接把未经处理的文本拼进去。认证的具体保护程度还取决于代理连接和认证机制。原文的写法展示的是参数位置，并不意味着 HTTP 代理地址会自动加密客户端到代理的整条连接。

代理究竟怎样转交请求

通过代理发送 HTTP 请求时，可以先把过程分为两步：

客户端先连接代理服务器。
代理代表客户端与目标服务器交换数据。

第二步有两种不同的实现机制。

转发：Forwarding

在转发模式下，代理替客户端向目标服务器发起请求，再把从目标收到的响应交还给客户端。客户端把请求交给代理，后续由代理完成。

隧道：Tunnelling

在隧道模式下，代理替客户端建立到目标服务器的 TCP 连接。客户端随后通过这条连接发送请求并接收响应。这就是 HTTP 隧道。

它解释了为什么普通 HTTP 代理也能用于访问 HTTPS 网站：代理提供通向目标服务器的 TCP 通道，客户端在该通道中与目标服务器完成 TLS 握手，然后交换 HTTPS 数据。就普通、未进行 TLS 拦截的隧道而言，TLS 的端点仍是客户端与目标服务器。访问 HTTPS 目标和用 HTTPS 连接代理，是两件不同的事。

这一点也决定了排查顺序：先确认代理端口可达、代理支持所需的转发或隧道方式，再检查认证和目标连接。遇到具体报错时，原文建议参阅 HTTPX 代理故障排查。不要用关闭目标证书校验来掩盖代理协议或连通性配置错误。

配置 SOCKS 代理

HTTPX 底层使用的 httpcore 也支持 SOCKS 代理。这是可选功能，需要额外的第三方依赖。原文给出的安装命令是 pip install httpx[socks]；这里改为带引号并指定 Python 解释器的写法，以避免某些 Shell 把方括号当作通配符：

python -m pip install "httpx[socks]"

这条命令会从当前配置的软件包索引安装或调整环境中的包，请在为项目准备的环境中执行，并按项目要求固定版本。本次没有执行安装。

装好 SOCKS 支持后，就可以使用 socks5:// 代理 URL：

import httpx

with httpx.Client(proxy="socks5://user:pass@host:port") as client:
    ...

user、pass、host 和 port 均需要按实际代理配置替换，尤其 port 必须换成有效端口。原文最后一例只创建客户端；这里改成上下文管理器，以便使用完毕后关闭客户端资源，代理配置含义没有改变。

来源与整理说明

原文：Proxies — HTTPX，作者署名为 HTTPX 项目及文档贡献者，页面未列出个人作者或单篇发布日期。中文翻译与技术图由本稿整理制作，核对日期为 2026 年 10 月 5 日。

本稿保留原文全部技术章节，补入 import httpx、代理服务前提、凭据处理说明和静态审查限制；SOCKS 安装命令与客户端生命周期的改动已在相应位置说明。配图是重新绘制的技术示意，不是原站截图。

HTTPX 版权与 BSD 3-Clause 许可

Copyright © 2019, [Encode OSS Ltd](https://www.encode.io/).
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

* Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

文章版权归作者所有，未经允许请勿转载。

THE END