Python requests SSL/TLS握手失败排查与解决方案

1. 项目概述：当Python requests遇上SSL版本号错误

如果你用Python的requests库写过网络请求，特别是访问一些HTTPS接口或者爬取数据，大概率遇到过SSL相关的报错。这些错误信息五花八门，什么SSLError: [SSL: WRONG_VERSION_NUMBER]、SSLError: [SSL: TLSV1_ALERT_PROTOCOL_VERSION]，或者更直白的SSLError: [SSL: UNSUPPORTED_PROTOCOL]。表面上看是SSL版本不匹配，但背后往往是你本地网络环境、目标服务器配置、甚至是操作系统底层库之间的一场“混战”。很多新手一看到这种错误就懵了，直接去搜“如何关闭SSL验证”，然后加上verify=False。这确实能让代码跑起来，但相当于开车不系安全带，把整个通信过程暴露在风险之下，是绝对不推荐的。

这篇文章，我就以一个踩过无数坑的老兵身份，带你把这些“坑人”的网络环境问题彻底理清楚。我们不止要解决“SSL版本号错误”这一个报错，更要理解它背后的成因，并掌握一套完整的排查和修复方法论。无论是你公司内网有代理、防火墙，还是目标服务器用了老旧的TLS 1.0，或者是你的Python环境本身SSL模块就有问题，我们都能找到对症下药的办法。告别盲目的verify=False，让我们安全、稳定地发起每一次HTTPS请求。

2. 核心问题拆解：SSL/TLS握手失败的根源

SSL版本号错误，本质上是一次失败的TLS握手。要理解它，我们得先简单过一下HTTPS连接建立的过程。当你用requests发起一个https://请求时，底层（通常是urllib3）会尝试与服务器建立一条加密的TLS连接。这个过程就像两个人见面握手，需要先对一下“暗号”（协议版本），再交换“信物”（证书），最后才能开始加密聊天。

2.1 TLS协议版本演进与兼容性

TLS是SSL的继任者，我们常说的SSL 3.0、TLS 1.0、TLS 1.1、TLS 1.2、TLS 1.3，就是不同的“暗号”版本。出于安全考虑，老旧的、有漏洞的版本（如SSL 2.0/3.0, TLS 1.0/1.1）正在被现代浏览器和库逐渐废弃。requests库及其底层的urllib3、OpenSSL库，会维护一个它们认为安全的默认协议列表。

问题往往出在这里：你的客户端（Python环境）支持的协议列表，和服务器端支持的协议列表没有交集。比如，你的Python链接了一个只支持TLS 1.2及以上版本的现代OpenSSL，而你要访问的服务器是一个老旧的内部系统，只支持TLS 1.0。客户端说：“嗨，我只会用TLS 1.2和1.3握手。”服务器说：“我只懂TLS 1.0。”双方无法就沟通语言达成一致，握手失败，于是你就看到了WRONG_VERSION_NUMBER或UNSUPPORTED_PROTOCOL的错误。

2.2 Python环境与系统OpenSSL的绑定

这是另一个重灾区。Python的ssl模块是对系统OpenSSL库的一个封装。你在Mac上用Homebrew安装的Python，在Windows上用官方安装包装的Python，在Linux上用系统包管理器（apt,yum）装的Python，它们背后链接的OpenSSL版本可能天差地别。

一个经典的错误是：ImportError: Can‘t connect to HTTPS URL because the SSL module is not available.这通常发生在从源码编译Python时，没有正确链接到系统的OpenSSL开发库。你的Python解释器根本就没“SSL能力”，requests自然无法工作。

即使ssl模块可用，版本也可能很老。你可以在Python中运行以下代码来检查：

import ssl print(ssl.OPENSSL_VERSION)

如果输出的版本号非常古老（比如OpenSSL 1.0.x），那么它可能不支持新的TLS 1.3，或者包含一些已知的安全漏洞，导致与一些严格的安全服务器连接失败。

2.3 中间网络设备的干扰（代理、防火墙、防毒软件）

企业网络环境是SSL问题的温床。很多公司为了安全审计或流量管理，会部署中间人（MITM）代理或防火墙。当你访问外网时，流量需要先经过这些设备。

• HTTP代理：如果你设置了HTTP_PROXY/HTTPS_PROXY环境变量，或是在代码中指定了proxies参数，requests会通过代理服务器转发请求。如果这个代理服务器本身配置有问题（比如SSL拦截证书不受信任、代理支持的TLS版本过低），错误就会体现在客户端。
• 透明代理/防火墙：有些网络设备会透明地拦截HTTPS流量，用自己的证书重新加密后再发往目的地。这相当于在你的通信链中插入了一个“中间人”。如果你的系统或Python的信任库（CA证书包）里没有安装这个中间人设备的根证书，SSL证书验证就会失败，报错可能是CERTIFICATE_VERIFY_FAILED。更隐蔽的情况是，这些设备可能不支持最新的TLS扩展，导致握手异常。
• 防病毒软件：一些安全软件也会进行HTTPS扫描，其原理类似透明代理，也可能引入证书信任问题。

2.4 服务器端配置问题

有时候问题不在你，而在服务器。比如：

1. 服务器证书配置错误：证书过期、证书域名不匹配（hostname doesn‘t match）、证书链不完整。
2. 服务器SSL/TLS配置不当：禁用了所有安全的加密套件，或者只开启了有漏洞的协议版本。
3. 服务器使用了自签名证书或私有CA颁发的证书：你的客户端默认不信任这些证书颁发机构。

3. 手把手排查流程：从现象到根因

当遇到SSL错误时，不要慌，按以下步骤系统性排查，大部分问题都能定位。

3.1 第一步：精确解读错误信息

requests抛出的SSLError通常包含很关键的信息。首先，把完整的错误堆栈打印出来。

import requests import traceback try: response = requests.get('https://你的问题网址') except requests.exceptions.SSLError as e: print("错误类型:", type(e)) print("错误信息:", e) # 打印更底层的错误原因（如果有） if hasattr(e, '__cause__') and e.__cause__: print("底层原因:", e.__cause__) traceback.print_exc()

关注错误信息中的关键词：

• WRONG_VERSION_NUMBER/UNSUPPORTED_PROTOCOL: 强烈指向客户端与服务器支持的TLS协议版本不匹配。
• CERTIFICATE_VERIFY_FAILED: 证书验证失败。可能是证书不受信任、过期、域名不匹配。
• [SSL: TLSV1_ALERT_PROTOCOL_VERSION]: 同样是协议版本问题，服务器明确拒绝了客户端的协议提议。
• [SSL: SSLV3_ALERT_HANDSHAKE_FAILURE]: 握手失败，原因可能更多样，包括协议版本、加密套件等。

3.2 第二步：使用外部工具进行独立验证

在动Python代码之前，先用系统命令行工具测试，这能帮你判断问题是出在Python环境还是更底层的网络。

使用OpenSSL s_client命令（Linux/Mac）:

openssl s_client -connect 目标主机:443 -servername 目标主机名 -tls1_2

这个命令尝试用TLS 1.2连接。你可以替换-tls1_2为-tls1_3、-tls1_1或-tls1来测试不同版本。观察输出：

• 如果连接成功，会打印出服务器的证书链和会话信息。
• 如果失败，会给出错误信息，例如unsupported protocol。
• 特别有用的参数是-showcerts，可以完整展示服务器发送的证书链。

使用curl命令:

curl -v https://目标主机

-v参数会输出详细的握手过程。关注类似* SSL connection using TLSv1.2 / AES256-GCM-SHA384这样的行，它告诉你最终协商成功的协议和加密套件。如果curl成功而requests失败，那问题几乎肯定在Python这边。

3.3 第三步：诊断Python的SSL环境

在Python交互环境中执行以下诊断脚本：

import sys, ssl, requests print(f"Python版本: {sys.version}") print(f"OpenSSL版本: {ssl.OPENSSL_VERSION}") print(f"Requests版本: {requests.__version__}") # 查看requests使用的urllib3版本 import urllib3 print(f"urllib3版本: {urllib3.__version__}") # 查看默认的SSL上下文支持的协议 ctx = ssl.create_default_context() print(f"默认SSL上下文协议: {ctx.protocol}") # 查看具体支持的协议版本（Python 3.7+） if hasattr(ssl, 'HAS_TLSv1_3'): print(f"支持TLS 1.3: {ssl.HAS_TLSv1_3}") # 可以通过以下方式查看上下文选项（部分） print(f"SSL上下文选项: {ctx.options}")

这个输出能告诉你你的“武器库”里有哪些TLS协议可用。

3.4 第四步：在代码中启用详细日志

urllib3（requests的底层）提供了非常详细的HTTP/HTTPS日志，能让你看到握手过程的每一个字节（夸张了点，但确实详细）。这是定位复杂问题的杀手锏。

import logging import http.client # 将日志级别调到DEBUG，这可能会输出大量信息 http.client.HTTPConnection.debuglevel = 1 logging.basicConfig() logging.getLogger().setLevel(logging.DEBUG) requests_log = logging.getLogger("requests.packages.urllib3") requests_log.setLevel(logging.DEBUG) requests_log.propagate = True # 现在再发起请求，你会在控制台看到详细的SSL握手和HTTP报文信息 try: response = requests.get('https://httpbin.org/status/200', timeout=5) except Exception as e: print(e)

从日志中，你可以清晰地看到ClientHello（客户端打招呼）和ServerHello（服务器回应）里声明的协议版本，以及最终协商确定的版本。如果握手在某个环节失败，日志会停在那里，给你明确的线索。

4. 针对性解决方案与实战配置

根据排查结果，我们采取不同的解决策略。再次强调，除非在绝对可控、无安全风险的内部测试环境，否则不要使用verify=False。

4.1 方案一：调整客户端支持的SSL/TLS协议版本

如果确认是协议版本不匹配，我们可以通过自定义SSL上下文来指定requests使用的协议。

方法A：使用requests的verify参数指定SSL上下文（推荐）

import ssl import requests from requests.adapters import HTTPAdapter from urllib3.poolmanager import PoolManager # 创建一个自定义的适配器，继承自HTTPAdapter class CustomSSLAdapter(HTTPAdapter): def init_poolmanager(self, *args, **kwargs): # 创建一个使用自定义SSL上下文的PoolManager context = ssl.create_default_context(ssl.Purpose.SERVER_AUTH) # 禁用不安全的低版本协议，只启用TLS 1.2和1.3 context.minimum_version = ssl.TLSVersion.TLSv1_2 # 或者，如果你必须连接一个只支持TLS 1.0的老旧服务器（不推荐） # context.minimum_version = ssl.TLSVersion.TLSv1 # context.maximum_version = ssl.TLSVersion.TLSv1 # 同时限制最高版本，确保只用TLS 1.0 kwargs['ssl_context'] = context return super().init_poolmanager(*args, **kwargs) # 使用这个适配器 session = requests.Session() adapter = CustomSSLAdapter() # 将这个适配器挂载到session，对所有HTTPS请求生效 session.mount('https://', adapter) try: response = session.get('https://老旧服务器地址') print(response.status_code) except requests.exceptions.SSLError as e: print(f"连接失败: {e}")

关键点：

• ssl.create_default_context()创建了一个安全的默认SSL上下文。
• context.minimum_version和context.maximum_version（Python 3.7+）可以精确控制协议版本范围。这是最规范的做法。
• 对于更老的Python版本，你可能需要直接设置context.options，例如context.options |= ssl.OP_NO_SSLv2 | ssl.OP_NO_SSLv3来禁用不安全的SSL版本，但这不如设置版本范围直观。

方法B：直接修改requests使用的urllib3默认上下文（全局影响）不推荐，因为它会影响该Python进程中所有使用requests的请求，但有时在简单脚本中很直接。

import requests import urllib3 # 创建一个自定义的SSL上下文 import ssl ctx = ssl.create_default_context() ctx.minimum_version = ssl.TLSVersion.TLSv1_2 # 创建一个使用该上下文的HTTPS连接池管理器 https = urllib3.PoolManager(ssl_context=ctx) # 猴子补丁，让requests使用我们这个自定义的连接池 # **注意：这会改变requests的默认行为，请谨慎使用** requests.adapters.HTTPAdapter.init_poolmanager = lambda self, *args, **kwargs: https

4.2 方案二：处理证书验证问题

证书错误非常常见，尤其是在企业内网或开发测试环境。

场景1：服务器使用自签名证书你需要获取服务器的自签名证书（通常是.crt或.pem文件），然后在请求时指定其路径。

response = requests.get('https://内网服务器', verify='/path/to/your/self_signed_certificate.crt')

或者，如果你有多个证书，可以将它们放在一个文件夹里，并将verify指向该文件夹（需用OpenSSL的c_rehash工具处理该文件夹）。

场景2：信任私有CA颁发的证书如果你的公司有自己的私有证书颁发机构（CA），你需要将私有CA的根证书添加到信任链中。可以将根证书文件路径传给verify参数，或者更一劳永逸地，将其添加到系统或Python使用的证书包中。

查找requests使用的默认证书包路径：

import requests print(requests.certs.where())

输出的路径（如/usr/local/lib/python3.9/site-packages/certifi/cacert.pem）就是requests默认信任的证书文件。你可以将私有CA的根证书内容追加到这个文件末尾（注意备份原文件）。但更好的做法是，不修改系统文件，而是在代码中指定：

response = requests.get('https://公司内部系统', verify='/path/to/company_root_ca.pem')

4.3 方案三：配置代理与处理网络拦截

如果你的请求必须经过代理，正确的配置至关重要。

配置HTTP/HTTPS代理：

import requests proxies = { 'http': 'http://proxy_user:proxy_pass@proxy_host:proxy_port', 'https': 'http://proxy_user:proxy_pass@proxy_host:proxy_port', # 注意：很多HTTP代理也用于HTTPS隧道 # 或者，如果代理支持HTTPS # 'https': 'https://proxy_user:proxy_pass@proxy_host:proxy_port', } # 如果代理需要独立的SSL验证（例如提供了代理CA证书） # 你可以为代理连接单独创建一个适配器，但这比较复杂。 # 更常见的是，如果公司代理进行了SSL拦截，你需要将代理的根证书提供给`verify`参数。 # 但requests的`verify`参数是针对目标服务器的，不是代理。 # 处理代理SSL拦截，通常需要配置系统或浏览器信任代理CA，而requests会继承系统信任库。 # 如果不行，可能需要使用更底层的urllib3或配置环境变量。 response = requests.get('https://example.com', proxies=proxies, timeout=10)

重要提示：如果公司代理进行了SSL中间人拦截，你很可能需要在你的系统（或Python环境）中安装并信任代理服务器提供的根证书。否则，requests在通过代理建立到目标服务器的HTTPS隧道时，依然会因证书不受信任而失败。这个证书通常由公司IT部门提供。

4.4 方案四：升级或修复Python的SSL环境

如果诊断发现是Python的ssl模块本身有问题（比如ImportError或版本太旧），你需要修复Python环境。

• Windows/Mac 使用官方安装包或conda：通常能解决大部分问题。Anaconda或Miniconda自带的Python环境通常有完整的SSL支持。
• Linux 使用包管理器安装：使用apt install python3 python3-pip或yum install python3 python3-pip安装的Python，一般链接了系统的OpenSSL。
• 源码编译Python：确保在编译前安装了OpenSSL的开发库。
  • Ubuntu/Debian:sudo apt-get install libssl-dev
  • CentOS/RHEL:sudo yum install openssl-devel然后在编译Python时，配置步骤可能会自动找到OpenSSL。如果仍有问题，可以尝试指定路径：./configure --with-openssl=/usr/local/ssl（根据你的OpenSSL安装位置调整）。

5. 高级技巧与最佳实践

5.1 创建健壮的、可复用的会话（Session）对象

对于需要频繁发送请求的应用，使用requests.Session()是最佳实践。它可以复用TCP连接，提升性能，并且方便统一设置超时、重试、适配器等配置。

下面是一个集成了自定义SSL、重试机制、超时和代理的健壮会话示例：

import requests from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry import ssl class RobustSession: def __init__(self, proxy=None, custom_ca_bundle=None, min_tls_version=ssl.TLSVersion.TLSv1_2): self.session = requests.Session() # 1. 自定义SSL适配器 class CustomSSLAdapter(HTTPAdapter): def init_poolmanager(self, *args, **kwargs): context = ssl.create_default_context(cafile=custom_ca_bundle) context.minimum_version = min_tls_version kwargs['ssl_context'] = context return super().init_poolmanager(*args, **kwargs) adapter = CustomSSLAdapter() self.session.mount('https://', adapter) self.session.mount('http://', adapter) # 对HTTP也挂载，保持一致性 # 2. 配置重试策略（对连接错误、超时、5xx状态码进行重试） retry_strategy = Retry( total=3, # 总重试次数 backoff_factor=1, # 重试等待时间：{backoff factor} * (2 ** ({重试次数} - 1)) 秒 status_forcelist=[500, 502, 503, 504], # 遇到这些状态码也重试 allowed_methods=["GET", "POST"] # 只对GET和POST方法重试 ) adapter_with_retry = HTTPAdapter(max_retries=retry_strategy) self.session.mount('https://', adapter_with_retry) self.session.mount('http://', adapter_with_retry) # 3. 设置默认超时（连接超时，读取超时） self.session.request = functools.partial(self.session.request, timeout=(3.05, 27)) # 4. 设置代理 if proxy: self.session.proxies.update({ 'http': proxy, 'https': proxy, }) # 5. 设置一些默认请求头（可选） self.session.headers.update({ 'User-Agent': 'MyRobustClient/1.0', 'Accept': 'application/json', }) def get(self, url, **kwargs): return self.session.get(url, **kwargs) def post(self, url, **kwargs): return self.session.post(url, **kwargs) # ... 可以封装其他方法 # 使用示例 # session = RobustSession(proxy='http://corp-proxy:8080', custom_ca_bundle='./company_ca.pem') # resp = session.get('https://api.example.com/data')

5.2 使用在线工具辅助诊断

有时候，从外部视角看服务器配置很有帮助。你可以使用像SSL Labs（ssllabs.com）的SSL Server Test这样的在线工具，输入你的目标域名，它会给你一份详细的报告，包括服务器支持的协议版本、加密套件、证书链等信息。这能帮你确认问题是否出在服务器端。

5.3 依赖库版本管理

保持requests、urllib3、certifi（CA证书包）的更新。旧版本可能包含已知的bug或缺少对新协议的支持。使用pip list --outdated查看过期包，并用pip install -U requests urllib3 certifi进行更新。但在生产环境中升级前，务必在测试环境充分验证，因为新版本可能引入不兼容的变更。

6. 常见问题排查速查表

下表汇总了典型的SSL错误现象、可能原因和快速应对措施。

7. 总结与个人心得

处理Python requests的SSL问题，本质上是一个“缩小包围圈”的调试过程。先从最宽泛的网络层和工具层（curl/openssl）验证，排除服务器和基础网络的问题；再聚焦到Python环境本身，检查版本和模块；最后深入到代码层，通过日志和自定义配置来精确调整。记住，verify=False永远是最后迫不得已的手段，它会让你对中间人攻击毫无防备。

在我多年的实践中，企业内网环境是最容易出问题的，根源往往是那个“透明”的网络设备。养成习惯，在新环境中运行脚本前，先用最简单的requests.get(‘https://httpbin.org/status/200‘)测试一下基本HTTPS连通性。如果失败，立刻按本文的流程走一遍，大部分时候都能在几分钟内定位问题。

另一个心得是关于依赖管理。对于需要部署到多种环境（开发、测试、生产）的项目，将requests、urllib3、certifi的版本在requirements.txt或pyproject.toml中锁死，能避免很多因依赖库自动升级带来的意外。尤其是在容器化部署时，一个固定的、经过测试的基础镜像加上锁定的依赖版本，能极大提高部署的确定性。

最后，SSL/TLS协议在不断发展，安全要求也越来越高。保持学习，关注像TLS 1.3的普及、旧版本协议的废弃时间表（如RFC 8996建议在2024年禁用TLS 1.0/1.1），及时调整你的客户端配置，才能让你的应用在未来的网络环境中依然畅通无阻。