Nstproxy 现已升级为 Nstdata。了解此次变化。 周一至周五 09:00 - 18:00（UTC+08:00） 公司地址
19H MAXGRAND PLAZA NO.3 TAI YAU STREET SAN PO KONG, KOWLOON HONG KONG
©2026 NST LABS TECH LTD. 保留所有权利。Kai WatanabeScraping Infrastructure Evangelist
如何使用 HTTPX 和代理：2026 年终极指南
TL;DR
- HTTPX 0.28.1 使用单数的
proxy= 参数；移除的 proxies= 参数在当前稳定版本的 HTTPX 中会引发 TypeError。
- 使用一个长久存在的
httpx.Client 或 httpx.AsyncClient，以便代理请求能够重用连接并干净地关闭。
- 即使目标 URL 是 HTTPS，HTTPX 通常也会连接到 HTTP 代理；
http:// 代理方案并不是错误。
- 使用
mounts= 进行按方案或按主机路由，并在环境代理变量不应影响进程时使用 trust_env=False。
- SOCKS 支持需要
httpx[socks] 额外功能和 socks5:// 或 socks5h:// 代理 URL。
- 将 Nstdata 通道凭证保存在秘密存储中，在仪表板中生成当前会话参数，并仅针对公共或授权目标进行测试。
使用带有代理的 HTTPX 是什么意思？
使用带有代理的 HTTPX 意味着 Python 将 HTTP 请求发送到代理网关，而不是直接连接到目标。网关转发请求或创建隧道，然后将目标的响应返回给 HTTPX 客户端。Nstdata 代理网关 可以提供这种中介路由，以进行授权区域测试、公共数据收集、价格监控、广告验证和网络诊断。
HTTPX 是一个具有同步和异步 API 的 Python HTTP 客户端。目前的HTTPX 代理文档支持通过 proxy= 使用单个代理，并通过传输装载进行高级路由。这一区别很重要，因为为较旧 HTTPX 版本编写的示例通常使用 proxies=，而在 HTTPX 0.28.1 中已经不再有效。
代理改变了网络路由，而不是权限模型。使用公共或授权目标，尊重合同和技术限制，最小化保留的IP 地址数据，并且绝不要使用代理路由来规避访问控制或收集私人信息。
你应该使用哪个版本的 HTTPX 和先决条件？
HTTPX 0.28.1 是截至 2026 年 8 月 6 日的当前稳定 PyPI 发布版本，而 PyPI 上显示的 1.0 包是开发预发布版本。锁定稳定发布版本使示例能够重复运行，并避免无声地转向预发布 API。PyPI上的HTTPX包页面 将 0.28.1 识别为稳定的发布版本。
python -m venv .venv
source .venv/bin/activate
python -m pip install "httpx==0.28.1"
如果需要 SOCKS 代理支持，请安装可选的额外功能：
python -m pip install "httpx[socks]==0.28.1"
你还需要代理方案、网关主机、端口和任何所需的凭证。对于 Nstdata，从经过身份验证的仪表板中复制生成的用户名和通道密码；不要推断或公开实时凭证字符串。
快速浏览
创建通道，生成当前代理凭证，并在将 HTTPX 示例添加到应用程序之前，以公共 IP 端点为目标进行测试。
如何通过代理发送一次性 HTTPX 请求？
一次性 HTTPX 请求通过单一的 proxy= 参数接受代理 URL。这是最简短的有用测试：
import httpx
response = httpx.get(
"https://api.ipify.org?format=json",
proxy="http://PROXY_HOST:PROXY_PORT",
timeout=20.0,
)
response.raise_for_status()
print(response.json())
代理 URL以 http:// 开头，即使目标是 HTTPS。HTTPX 首先连接到代理，然后正常地请求它打开到 HTTPS 目标的隧道。将代理 URL 更改为 https:// 告诉 HTTPX 在客户端与代理之间使用 TLS，这是不同的能力，当前的 HTTPX 未必可靠支持。
仅使用小型 IP 信息响应来验证路由。返回的 IP 是操作数据，因此将其从共享构建日志中屏蔽，仅在测试需要时保留。
为什么要使用 HTTPX 客户端进行重复的代理请求？
httpx.Client 是进行重复代理请求的正确默认选择，因为它拥有一个连接池和共享配置。上下文管理器还确保在块结束时关闭连接：
import httpx
proxy_url = "http://PROXY_HOST:PROXY_PORT"
with httpx.Client(
```python
proxy=proxy_url,
timeout=httpx.Timeout(20.0, connect=10.0),
trust_env=False,
) as client:
response = client.get("https://api.ipify.org?format=json")
response.raise_for_status()
print(response.json())
trust_env=False 使得这个例子在忽略 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、证书和相关环境配置时变得可预测。只有在部署打算管理这些变量时才移除它。一个稳定的客户端也使得超时、头信息、限制、cookies 和代理路由在一个地方可见，而不是分散在多个调用中。
如何安全地对 HTTPX 代理进行认证？
HTTPX 代理认证将百分比编码的凭证放在代理 URL 的用户信息部分。从经过批准的秘密存储或环境中读取原始值，编码保留字符，并避免打印完成的 URL：
import os
from urllib.parse import quote
import httpx
proxy_user = quote(os.environ["PROXY_USER"], safe="")
proxy_password = quote(os.environ["PROXY_PASSWORD"], safe="")
proxy_url = (
f"http://{proxy_user}:{proxy_password}@"
"PROXY_HOST:PROXY_PORT"
)
with httpx.Client(proxy=proxy_url, timeout=20.0) as client:
response = client.get("https://api.ipify.org?format=json")
response.raise_for_status()
百分比编码防止字符如 @、:、/ 和 # 被解析为 URL 结构。环境变量减少了意外的源代码提交，但仍然可能出现在进程诊断、崩溃报告或子进程中。使用经过批准的秘密机制进行部署，如果 Channel 密码泄露，立即轮换它。
如何使用 Nstdata 配置 HTTPX？
HTTPX 通过将生成的 Channel 用户名和密码放入标准 HTTP 代理 URL 来连接 Nstdata。Nstdata 当前的公共文档定义了 Channel、代理类型、位置、会话持续时间和会话 ID 作为其生成的代理参数的一部分。请从仪表板复制完整的当前用户名，而不是从旧教程中组装变化敏感的值。
以下代码块需要私人 Nstdata Channel 凭证，并故意不在本文中使用真实账户执行：
import os
from urllib.parse import quote
import httpx
username = quote(os.environ["NSTDATA_USERNAME"], safe="")
password = quote(os.environ["NSTDATA_PASSWORD"], safe="")
gateway = os.environ["NSTDATA_GATEWAY"]
port = os.environ["NSTDATA_PORT"]
proxy_url = f"http://{username}:{password}@{gateway}:{port}"
with httpx.Client(proxy=proxy_url, timeout=20.0) as client:
response = client.get("https://api.ipify.org?format=json")
response.raise_for_status()
print(response.json())
Nstdata Residential Prime Proxies 在 HTTPX 工作负载需要管理的轮换住宅流量时非常实用，而不是手动维护的代理列表。生成的网关 URL 可以与 HTTPX 的普通 proxy= 接口配合使用，因此应用程序不需要特定于提供程序的 SDK。Channel 和会话参数允许操作员选择请求是应该轮换还是保持连续性，这取决于当前产品配置。该产品适用于授权的区域 QA、公共网络监控、广告验证和价格收集等与住宅路由相关的场景。在设计工作负载之前，请确认仪表板中的当前目标、库存、套餐和会话选项。
- 与 HTTPX 兼容的接口： 生成的 HTTP 或 SOCKS5 网关可以插入
httpx.Client 和 httpx.AsyncClient，而无需更改请求语义。
- 会话控制： 新的提供者定义的会话 ID 可以请求不同的会话，而保留的会话值可以在仪表板支持的选择下保持连续性。
- 操作分离： Channel 将资源和使用边界与应用代码区分开，同时秘密保持在代码库之外。
如何使用 HTTPX AsyncClient 代理？
httpx.AsyncClient 使用相同的单一 proxy= 参数，并且必须使用 async with 或 aclose() 关闭。异步形式在程序已经有事件循环并在等待多个独立的网络操作时非常有用：
import asyncio
import httpx
async def fetch_ip() -> dict:
async with httpx.AsyncClient(
proxy="http://PROXY_HOST:PROXY_PORT",
timeout=20.0,
trust_env=False,
) as client:
response = await client.get("https://api.ipify.org?format=json")
response.raise_for_status()
return response.json()
print(asyncio.run(fetch_ip()))
异步I/O并不意味着无限并发是安全的。限制任务数量，使用显式连接限制，遵循目标速率策略，仅重试瞬时故障。为每个请求创建新的AsyncClient会丢弃连接池并增加不必要的握手。
如何通过不同的HTTPX代理路由不同的URL？
HTTPX在需要不同传输的不同URL模式时使用mounts=。映射完整的URL方案，如http://和https://，而不是Requests库中使用的http和https键：
import httpx
proxy_url = "http://PROXY_HOST:PROXY_PORT"
mounts = {
"http://": httpx.HTTPTransport(proxy=proxy_url),
"https://": httpx.HTTPTransport(proxy=proxy_url),
}
with httpx.Client(mounts=mounts, timeout=20.0, trust_env=False) as client:
response = client.get("https://api.ipify.org?format=json")
response.raise_for_status()
两个传输故意使用http://代理URL。挂载键与目标方案匹配；传输的代理URL描述了客户端与代理之间的连接。HTTPX传输路由指南同样支持方案、域、端口和通配符模式。
当内部服务必须绕过代理时，使用直接传输或更具体的挂载。测试路由优先级，因为HTTPX选择最具体的匹配URL模式。
HTTPX代理环境变量如何工作？
HTTPX默认读取HTTP_PROXY、HTTPS_PROXY、ALL_PROXY和NO_PROXY。这在容器和管理工作中很方便，因为操作拥有网络路由：
export HTTP_PROXY="http://PROXY_HOST:PROXY_PORT"
export HTTPS_PROXY="http://PROXY_HOST:PROXY_PORT"
export NO_PROXY="localhost,127.0.0.1,.internal.example"
python app.py
import httpx
with httpx.Client(
proxy="http://PROXY_HOST:PROXY_PORT",
trust_env=False,
) as client:
response = client.get("https://example.com")
当脚本使用意外代理时，尽早检查环境变量。还要检查容器定义、服务管理器、CI秘密和shell配置文件；代码可能正确，而部署配置改变了路由。
如何在HTTPX中使用SOCKS5？
HTTPX在安装socksio依赖项后使用SOCKS代理。使用SOCKS代理URL配置客户端：
import httpx
with httpx.Client(
proxy="socks5://PROXY_USER:PROXY_PASSWORD@PROXY_HOST:PROXY_PORT",
timeout=20.0,
) as client:
response = client.get("https://api.ipify.org?format=json")
response.raise_for_status()
当已安装的HTTPX版本和代理应通过代理解析目标主机名时，使用socks5h://。明确测试DNS行为；不要假设仅选择SOCKS5会将名称解析移离本地机器。
应如何轮换代理并重试失败的请求？
代理轮换应是有限的、可观察的，并与故障类型相关联。407是身份验证问题，连接超时可能标识网关路径，目标429是速率限制响应，应减缓工作量而不是触发无限轮换。
对于托管的轮换网关，根据其当前文档更改提供者定义的会话值，而不是重新构建一个大的本地代理列表。网关轮换和应用程序侧列表之间的区别在Nstdata指南中介绍了Python中的轮换代理。一个反向连接代理同样呈现一个网关，同时通过上游代理资源路由。
设置显式连接、读取、写入和池超时。仅重试幂等操作，除非应用程序有验证的幂等性机制，限制尝试次数，增加退避，并记录最终错误类别而不记录凭据。
常见HTTPX代理错误及修复
大多数HTTPX代理故障源于参数过时、不正确的代理方案、缺失的额外模块、身份验证、环境覆盖或TLS配置。下表区分了这些边界：
| 症状 | 可能原因 | 纠正措施 |
|---|
unexpected keyword argument 'proxies' | 代码针对HTTPX 0.28之前的版本 | 将一个代理替换为proxy=或使用mounts=的高级映射 |
握手期间出现ProxyError | 代理URL使用不支持的https:// | 确认代理是否期待http://进行CONNECT隧道 |
HTTP 407 | 代理拒绝了身份验证 | 重新生成凭据并验证百分比编码 |
| SOCKS 导入错误 | 可选依赖缺失 | 在同一环境中安装 httpx[socks] |
| 请求绕过显式路由 | 环境或挂载优先级 | 设置 trust_env=False 并检查最具体的挂载 |
| 证书验证失败 | 错误的端点、CA、时钟或拦截策略 | 修复信任路径；不全球禁用验证 |
HTTP 403 或 429 | 目标策略或速率响应 | 确认授权、降低速率并检查响应头 |
达到目标的 HTTP 请求 仍然可能收到应用程序错误。raise_for_status() 区分目标 HTTP 失败和成功响应，而 HTTPX 异常则识别 DNS、连接、代理、超时和 TLS 边界。
结论
2026 年可靠的 HTTPX 代理模式是可重用客户端上的 proxy=、用于选择性路由的 mounts=，以及在配置必须明确时设置 trust_env=False。仅在需要时安装 SOCKS 附加组件，安全编码凭证，关闭每个客户端，并在重试之前分类失败。对于 Nstdata，在仪表板中生成当前通道凭证并将每个完成的代理 URL 视为秘密。
使用 Nstdata 尝试 HTTPX
创建一个通道，生成当前代理，并在连接到生产工作流之前针对公共或授权端点运行经过验证的 HTTPX 模式。
常见问题
HTTPX 0.28.1 使用单一的 proxy= 参数来处理一个代理，使用 mounts= 进行高级路由。将移除的 proxies= 参数传递给 httpx.Client 会引发 TypeError。
问：HTTPX 能否对 HTTP 和 HTTPS 目标使用相同的代理？
是的，一个 http:// 代理 URL 可以将 HTTP 和 HTTPS 目标路由到一起。HTTPS 目标通常在与目标执行 TLS 之前通过 HTTP 代理使用 CONNECT 隧道。
在代理 URL 中网关主机之前放置百分比编码的凭证：http://USER:PASSWORD@HOST:PORT。从批准的秘密存储中获取原始值，切勿打印完成的 URL。
是的，HTTPX 支持 SOCKS，前提是安装了 httpx[socks]。使用 socks5:// URL，或当需要代理方主机名解析时测试 socks5h://。
是的，httpx.AsyncClient(proxy=PROXY_URL) 支持异步代理请求。重用一个客户端，绑定并发，并通过 async with 关闭它。
HTTPX 可能在遵循环境变量或更具体的传输挂载。检查 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY 和挂载优先级，然后在代理必须明确时使用 trust_env=False。
使用带代理的 HTTPX 是网络配置上的选择，但许可取决于目标、数据、司法管辖区、合同和目的。使用公共或授权资源，遵守适用的条款和法律，限制请求量，并为受监管的数据工作流获取法律建议。
Sep. 1st 2026
立即访问住宅、数据中心、IPv6 与 ISP 高质量代理池。
