Python requests 配置 HTTP、HTTPS、SOCKS5 代理：参数、认证与排错
在 Python 接口联调、网络排障和页面可用性测试中，requests配置代理是一个常见需求。很多示例只给出一段proxies={...}，但真实项目里更容易出错的地方是协议写法、认证格式、DNS 解析、超时参数和错误分类。
本文讨论requests的代理配置和调试方法，不涉及任何非授权访问或高频请求场景。
一、requests 代理配置的基本结构
requests通过proxies参数指定不同协议使用的代理出口：
import requests proxies = { "http": "http://127.0.0.1:8080", "https": "http://127.0.0.1:8080", } response = requests.get( "https://httpbin.org/ip", proxies=proxies, timeout=(5, 15), ) print(response.status_code) print(response.text)这里最容易误解的是"https"这个键。它表示“访问 HTTPS URL 时使用哪个代理”，不代表代理服务器本身一定要用https://连接。
很多 HTTP 代理访问 HTTPS 站点时，会通过CONNECT方法建立隧道，所以代理地址仍然可能是：
"https": "http://127.0.0.1:8080"是否支持https://proxy-host:port，要看代理服务端和客户端库是否支持客户端到代理之间的 TLS。
二、带用户名密码的代理怎么写
如果代理需要认证，可以把用户名和密码写入代理 URL：
from urllib.parse import quote username = quote("user@example") password = quote("p@ss:word") proxy_url = f"http://{username}:{password}@127.0.0.1:8080" proxies = { "http": proxy_url, "https": proxy_url, }这里使用quote()是为了处理用户名或密码里的特殊字符。否则@、:、#等字符可能导致 URL 解析错误。
实际项目中，不建议把账号密码直接写入代码。更常见的方式是从环境变量读取：
import os proxy_url = os.getenv("PROXY_URL") proxies = {"http": proxy_url, "https": proxy_url} if proxy_url else None三、SOCKS5 代理需要额外依赖
requests默认不直接支持 SOCKS。使用 SOCKS5 前，需要安装额外依赖：
pip install "requests[socks]"配置示例：
import requests proxies = { "http": "socks5h://127.0.0.1:1080", "https": "socks5h://127.0.0.1:1080", } response = requests.get( "https://httpbin.org/ip", proxies=proxies, timeout=(5, 15), ) print(response.json())socks5://和socks5h://的区别主要在 DNS：
| 写法 | DNS解析位置 |
|---|---|
socks5:// | 通常由本地客户端解析 |
socks5h:// | 通常交给代理端解析 |
如果你希望目标域名由代理端解析，通常应使用socks5h://。
四、Session 复用适合一组连续请求
如果同一个任务要连续访问多个 URL，可以使用requests.Session()复用连接和默认配置：
import requests proxy_url = "http://127.0.0.1:8080" with requests.Session() as session: session.proxies.update({ "http": proxy_url, "https": proxy_url, }) for url in [ "https://httpbin.org/ip", "https://httpbin.org/headers", ]: response = session.get(url, timeout=(5, 15)) print(url, response.status_code)Session适合连续请求，但不要误解为“请求一定使用同一个出口”。出口是否变化取决于代理服务本身的调度规则。
五、超时参数建议分开设置
不要只写timeout=30。更建议使用二元组：
timeout=(5, 15)含义是：
- 5 秒连接超时；
- 15 秒读取超时。
这样更容易判断问题发生在哪一层。如果连接阶段就超时，通常要检查代理地址、端口、认证和链路；如果读取阶段超时，说明连接已经建立，但目标响应或中间链路过慢。
六、错误类型怎么排查
可以按下面方式捕获错误：
import requests try: response = requests.get( "https://httpbin.org/ip", proxies=proxies, timeout=(5, 15), ) print("status:", response.status_code) except requests.exceptions.ProxyError as exc: print("proxy error:", exc) except requests.exceptions.ConnectTimeout as exc: print("connect timeout:", exc) except requests.exceptions.ReadTimeout as exc: print("read timeout:", exc) except requests.exceptions.SSLError as exc: print("ssl error:", exc) except requests.RequestException as exc: print("request error:", type(exc).__name__, exc)常见含义如下：
| 错误 | 常见原因 |
|---|---|
ProxyError | 代理地址、端口、认证或协议不正确 |
ConnectTimeout | 连接代理或连接目标站点超时 |
ReadTimeout | 连接已建立，但读取响应超时 |
SSLError | TLS 握手或证书链异常 |
| HTTP 407 | 代理认证失败 |
| HTTP 429 | 请求频率或目标接口限制 |
不要把所有异常都写成except Exception后直接忽略。错误类型本身就是排查线索。
七、一个最小可复用函数
下面函数适合放在测试脚本里，用于快速验证代理配置。
import requests def fetch_with_proxy(url: str, proxy_url: str | None = None) -> dict: proxies = None if proxy_url: proxies = { "http": proxy_url, "https": proxy_url, } try: response = requests.get( url, proxies=proxies, timeout=(5, 15), ) return { "ok": True, "status_code": response.status_code, "text": response.text[:200], } except requests.RequestException as exc: return { "ok": False, "error_type": type(exc).__name__, "error": str(exc), }调用方式：
result = fetch_with_proxy( "https://httpbin.org/ip", "http://127.0.0.1:8080", ) print(result)八、调试时建议记录这些字段
为了后续复盘，建议把结果记录成结构化日志：
target_url proxy_scheme status_code elapsed_ms error_type timestamp如果涉及 SOCKS5，还可以记录使用的是socks5://还是socks5h://，避免 DNS 解析位置造成误判。
九、总结
requests配置代理并不复杂，真正容易出错的是协议理解、认证格式、DNS 解析和错误分类。
开发测试时建议做到三点：代理地址从环境变量读取，超时参数分连接和读取两段设置，异常日志按类型记录。这样后续排查会比只看“请求失败”清楚得多。