周一至周五 09:00 - 18:00（UTC+08:00） 
©2026 NST LABS TECH LTD. 保留所有权利。Marcus ChenProduct & Network Architect
如何使用 HTTPX 代理：2026 完整指南
TL;DR
- HTTPX 0.28.1 使用
proxy=，而不是已删除的 proxies= 参数。 当 HTTP 和 HTTPS 目标需要不同的传输时，请使用 mounts=。
- 持久的
Client 或 AsyncClient 通常比重复的顶层调用更好。 客户端重用连接，集中超时，并具有明确的清理边界。
- 经过身份验证的代理 URL 必须对用户名和密码进行编码。 诸如空格、
@ 和 : 等保留字符会影响 URL 解析。
- HTTPX 默认读取
HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 和 NO_PROXY。 当应用配置必须忽略机器级代理设置时，设置 trust_env=False。
- 代理轮换需要一个有界的客户端池和接受检查。 单靠随机选择无法检测到死路、状态为 200 的错误页面或意外数据。
什么是 HTTPX 代理？
HTTPX 代理是一种在 HTTPX Python 客户端中配置的中介，以便请求通过另一个网络端点到达目标。官方 HTTPX 代理文档 通过 proxy= 支持单个代理，并通过装载的传输字典支持高级路由。
HTTPX 是一个通用的 Python HTTP 客户端，具有同步和异步 API。代理配置改变网络路径；HTTPX 仍然负责连接池、超时、重定向、TLS 验证、响应流和状态处理。因此，像 Nstproxy Residential Prime Proxies 这样的管理路由可以通过标准的 HTTPX 设置附加，而不改变解析或消耗响应的业务逻辑。
使用 HTTPX 代理进行授权的价格监控、位置检查、公共页面测试、受控企业出口或隔离独立作业。代理并不会授权访问目标，纠正无效选择器或证明响应包含预期内容。
您需要了解的 HTTPX 代理 API 更改
HTTPX 0.28 删除了已弃用的 proxies= 参数，因此当前代码必须使用 proxy= 或 mounts=。 确定 0.28.1 是测试时的最新版本，并记录了在 0.28 系列中的删除。
| 旧模式 | HTTPX 0.28.1 模式 | 用例 |
|---|
httpx.Client(proxies=proxy_url) | httpx.Client(proxy=proxy_url) | 所有请求的一个端点 |
httpx.get(url, proxies=...) | httpx.get(url, proxy=...) | 一个独立的请求 |
以 proxies= 传递的代理字典 | mounts={"http://": HTTPTransport(...), ...} | 按目标方案的不同路由 |
挂载键上的方案描述目标 URL。代理 URL 内的方案描述与代理的连接。对于许多 HTTP 网关，http:// 和 https:// 目标均正确地使用 http://proxy-host:port 端点，因为 HTTPS 目标通过 CONNECT 隧道。
先决条件
示例使用 Python 3.12.13 和 HTTPX 0.28.1 执行。请在虚拟环境中安装固定版本：
python -m pip install httpx==0.28.1
准备一个授权目标，并在受保护的运行时配置中存储代理秘密。示例使用 PROXY_URL、TARGET_URL、PROXY_USERNAME、PROXY_PASSWORD 和 PROXY_URLS。请勿提交完整的凭证包含 URL 或将其包含在应用日志中。
每个示例设置了明确的超时。HTTPX 区分连接、读取、写入和池超时；从观察到的延迟进行调整，而不是去除限制。当合法的检查代理需要 CA 证书时，请保持 TLS 验证启用并安装批准的 CA 证书。
通过Nstproxy路由HTTPX请求
创建一个经过身份验证的端点，将其附加到HTTPX客户端，并验证返回的路由。
创建一个HTTPX代理路由
|
|
详细教程：如何使用HTTPX与代理
您可以通过五种当前模式使用带有代理的HTTPX：一个客户端级别的端点、编码的身份验证、异步客户端池、环境变量或挂载的传输。下面所有的Python代码块都是针对专门构建的本地端点运行的。响应返回非秘密路由标记，这确认了流量通过预期的代理，而不仅仅是确认HTTPX返回了响应。
方法1：使用一个与同步客户端的代理
当顺序请求共享一个端点时，使用同步的Client。将trust_env=False使显式路由具有权威性，同时上下文管理器在任务完成后关闭池中的连接。
import os
import httpx
proxy_url = os.environ["PROXY_URL"]
target_url = os.environ["TARGET_URL"]
timeout = httpx.Timeout(15.0, connect=5.0)
with httpx.Client(proxy=proxy_url, timeout=timeout, trust_env=False) as client:
response = client.get(target_url)
response.raise_for_status()
if response.headers.get("content-type", "").split(";", 1)[0] != "application/json":
raise ValueError("期望一个JSON响应")
data = response.json()
if data.get("route") != "basic-18480":
raise ValueError(f"意外的路由: {data}")
print(data)
测试打印了route: basic-18480并保留了代理接收到的绝对目标URL。将固定的路由值替换为您的诊断端点或提供者会话可以验证的标记。
顶级的httpx.get(..., proxy=...)对于一次性调用是有效的，但重复的顶级调用无法重用一个客户端池。为多页作业优先使用一个客户端。Nstproxy的Python网页抓取项目指南解释了响应验证在更大提取管道中的适用位置。
方法2：配置认证的HTTPX代理
通过在构建URL之前对每个凭据组件进行百分比编码来使用认证的代理。编码可以防止保留字符被解析为分隔符。
import os
from urllib.parse import quote
import httpx
username = quote(os.environ["PROXY_USERNAME"], safe="")
password = quote(os.environ["PROXY_PASSWORD"], safe="")
host = os.environ["PROXY_HOST"]
port = os.environ["PROXY_PORT"]
proxy_url = f"http://{username}:{password}@{host}:{port}"
with httpx.Client(proxy=proxy_url, timeout=10.0, trust_env=False) as client:
response = client.get(os.environ["TARGET_URL"])
response.raise_for_status()
data = response.json()
if data.get("route") != "auth-18481":
raise ValueError(f"意外的路由: {data}")
print({"route": data["route"], "authenticated": data["authenticated"]})
实时检查使用了包含空格的用户名和包含 @ 和 : 的密码。代理因缺失凭据拒绝了请求，返回了407，然后在HTTPX提供了编码值后返回了 authenticated: True 和路由 auth-18481。
不要打印 proxy_url：它包含可恢复的凭据。请记录路由ID、状态、延迟和失败类别。重复的407是配置失败，而不是无限重试循环的原因。
方法 3：轮换可重用的 AsyncClient 实例
当独立请求可以通过多个端点运行时，请使用有界的 AsyncClient 池。每个端点一个客户端可以保持连接重用，并使路由与客户端之间的关系显式。
import asyncio
import itertools
import os
import httpx
async def fetch(client: httpx.AsyncClient, target_url: str) -> dict:
response = await client.get(target_url)
response.raise_for_status()
data = response.json()
if "route" not in data:
raise ValueError("响应未包含路由标记")
return data
async def main() -> None:
proxy_urls = [value.strip() for value in os.environ["PROXY_URLS"].split(",") if value.strip()]
if len(proxy_urls) < 2:
raise ValueError("PROXY_URLS 必须包含至少两个端点")
clients = [
httpx.AsyncClient(proxy=proxy_url, timeout=10.0, trust_env=False)
for proxy_url in proxy_urls
]
try:
client_cycle = itertools.cycle(clients)
tasks = [fetch(next(client_cycle), os.environ["TARGET_URL"]) for _ in range(4)]
results = await asyncio.gather(*tasks)
print([result["route"] for result in results])
finally:
await asyncio.gather(*(client.aclose() for client in clients))
asyncio.run(main())
输出顺序交替为 basic-18480、rotate-18482、basic-18480 和 rotate-18482。可以观察到轮询选择，避免意外重复选择，但这不是健康策略。在使用更大的池之前，请添加并发限制、失败计数器、冷却期和最大重试预算。 Python 代理轮换指南 涵盖了更广泛应用层面的端点选择。
除非操作是幂等的或携带应用幂等性密钥，否则不要自动通过另一路由重放状态变化的请求。对于有状态的浏览，保持相同的客户端、Cookies 和粘性路由一起。
方法 4：使用代理环境变量
HTTPX 默认读取代理环境变量，这对平台管理的路由很有用。 官方 HTTPX 环境变量文档 定义了 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 和 NO_PROXY。
export HTTP_PROXY="http://proxy.example:9000"
export HTTPS_PROXY="http://proxy.example:9000"
python app.py
import os
import httpx
response = httpx.get(os.environ["TARGET_URL"], timeout=10.0)
response.raise_for_status()
data = response.json()
if data.get("route") != "basic-18480":
raise ValueError(f"意外的路由: {data}")
print(data["route"])
执行的程序在Python中未带代理参数返回了 basic-18480。当一个目标意外直接访问时，请检查 NO_PROXY。如果程序必须忽略主机设置，请构造一个 trust_env=False 的客户端；该选择还会忽略其他派生自环境的配置，诸如证书路径。
方法 5：使用 HTTPTransport 挂载进行路由
当路由依赖于目标方案或 URL 的子集时，请使用 mounts=。这是旧代理字典的当前替代方案。
import os
import httpx
proxy_url = os.environ["PROXY_URL"]
mounts = {
"http://": httpx.HTTPTransport(proxy=proxy_url),
"https://": httpx.HTTPTransport(proxy=proxy_url),
}
with httpx.Client(mounts=mounts, timeout=10.0, trust_env=False) as client:
response = client.get(os.environ["TARGET_URL"])
response.raise_for_status()
data = response.json()
if data.get("route") != "basic-18480":
raise ValueError(f"意外的路由: {data}")
print(data["route"])
HTTP挂载在本地运行中产生了 basic-18480。保持挂载键的特定性并测试应用程序使用的每种方案。HTTPX 还通过 httpx[socks] 附加功能提供可选的 SOCKS 支持；安装该附加功能并仅在端点实际上支持 SOCKS 时使用文档中记录的 SOCKS URL。
如何验证 HTTPX 代理
在三个层次上验证 HTTPX 代理：网络路由、响应语义和提取的输出。首先从经过授权的 IP 反射或诊断端点开始，并确认观察到的退出或会话标记。然后要求可接受的状态、内容类型和可识别的页面字段。最后验证您的应用程序打算保留的记录。
raise_for_status() 会拒绝 4xx 和 5xx 响应，但 HTTP 200 仍然可以包含代理错误页面、同意屏幕、登录页面或替代语言。测试稳定的语义字段并拒绝空的或不可信的结果。官方的 HTTPX 异常层次结构 有助于将超时、传输故障、代理错误和状态失败分离，以便为有限的重试规则提供支持。
重试应针对瞬态连接、超时和网关故障。不要无限重试 401、403、407 或无效内容。Nstproxy 的代理服务器错误指南 提供了用于路由级故障排除的实用分类法。
选择 Nstproxy 的 HTTPX 路由
Nstproxy 住宅高级代理为需要住宅路由、可选择位置和当前产品表面上的旋转或粘性会话的 HTTPX 工作负载提供标准认证端点。当您的 Python 代码已经处理 HTTP 请求和验证时，结合非常强大，而网络路由必须保持可配置在应用程序逻辑之外。按需收费和套餐计费模式使团队可以在测量接受的流量后选择运营模型，而不是重写 HTTPX 集成。将该产品用于授权的本地化检查、价格监控、广告验证和公共数据工作流；在增加流量之前测试准确的目标和会话行为。
- 标准客户端集成： 通过
proxy= 或挂载的 HTTPTransport 附加生成的端点；基本路由不需要特定于提供者的 Python SDK。
- 会话感知路由： 为独立请求选择旋转行为，或为依赖于 cookie 的流程选择粘性会话。
- 计量计费选择： 根据观察的流量和接受率比较当前的住宅高级套餐和按需计费模型。
代理路由不执行解析、去重或架构验证。将这些接受规则保留在应用程序中，监控每个接受记录的成本，而不仅仅是请求计数。
常见的 HTTPX 代理错误及解决方案
| 症状 | 可能原因 | 实用修复 |
|---|
TypeError 提到 proxies | 代码针对的是旧的 HTTPX API | 用 proxy= 替换一个端点；对高级路由使用 mounts=。 |
407 代理身份验证要求 | 缺少或格式错误的凭据 | 分别编码用户名/密码，并在不记录 URL 的情况下验证主机和端口。 |
ProxyError 或 ConnectTimeout | 端点无法访问或使用了错误的协议 | 确认方案、DNS、端口和网络可达性；仅重试瞬态故障。 |
| 直接 IP 出现 | 匹配 NO_PROXY 或未使用明确的客户端 | 检查环境变量，并在必须使用显式配置时设置 trust_env=False。 |
| 通过 HTTP 代理的 HTTPS 失败 | CONNECT 或 CA 信任错误配置 | 确认网关支持隧道，并安装批准的 CA；不要禁用 TLS 检查。 |
| 异步套接字累积 | 客户端未经过清理而创建 | 复用边界客户端，总是调用 aclose() 或使用 async with。 |
| 状态 200 但数据错误 | 响应是替代或软错误页面 | 验证内容类型、稳定标记和最终提取的架构。 |
结论
生产环境 HTTPX 代理设置使用现代的 proxy= 或 mounts= API，保护的凭据，明确的超时，可复用的客户端和响应接受测试。使用一个同步客户端来实现稳定的路由，小心编码认证端点，并仅在独立工作需要多个路由时旋转有限的 AsyncClient 实例。
从一个已授权的目标开始，并验证其路由和语义响应。在分类故障和证明清理成功后添加轮换；如果端点健康、池和路由规则超出应用程序级选择，稍后考虑 Nstproxy 代理管理器。
体验 Nstproxy — 立即开始您的免费试用
常见问题
问：HTTPX 仍然支持 proxies= 参数吗？
不支持。HTTPX 0.28 移除了 proxies=；对于一个端点使用 proxy=，对于更复杂的路由使用带代理的 mounts=。
问：HTTPX 可以使用 AsyncClient 的代理吗？
可以。将 proxy= 传递给 httpx.AsyncClient，复用分配给的端点，并使用 async with 或 aclose() 关闭。
问：为什么 HTTP 代理 URL 针对 HTTPS 目标仍然以 http:// 开头？
代理 URL 方案描述了与代理的连接，而目标通过 CONNECT 隧道使用 HTTPS。因此，HTTP 网关可以在没有 https:// 代理 URL 的情况下提供 HTTPS 目的地。
创建一个带有 trust_env=False 的 Client 或 AsyncClient。HTTPX 将忽略从进程环境继承的代理和相关配置。
问：我应该为每个请求创建一个新的 AsyncClient 吗？
不应该。重用一组有限的客户端，以便 HTTPX 可以池化连接，并将每个客户端与一个端点或会话策略关联。
可以。安装官方可选依赖项 httpx[socks]，并为实际实现该协议的端点配置一个 socks5:// 或支持的 SOCKS URL。
Marcus Chen
Aug. 20th 2026
立即访问住宅、数据中心、IPv6 与 ISP 高质量代理池。
