Python / 知识点
Python 开发速查手册
手册条目
处理包安装或网络请求中的证书、代理和连接失败。
排查 SSL 与代理问题
用于定位 pip 安装或 Python HTTP 请求中的证书校验、代理认证、DNS 和超时问题。先保留完整异常,再按错误关键词判断故障层,避免一上来关闭 TLS 校验。
快速定位
下面的脚本只使用标准库,打印 Python 使用的 OpenSSL、默认证书路径、已生效代理,并访问 PyPI 的轻量地址。它能区分本机信任链、代理配置和基础连接问题。
python
import os
import ssl
import urllib.error
import urllib.request
URL = "https://pypi.org/simple/pip/"
def flag(name: str) -> str:
return "set" if os.getenv(name) else "not set"
def main() -> None:
paths = ssl.get_default_verify_paths()
print(f"OpenSSL: {ssl.OPENSSL_VERSION}")
print(f"CA file: {paths.cafile or '<none>'}")
print(f"HTTPS_PROXY: {flag('HTTPS_PROXY')}")
print(f"REQUESTS_CA_BUNDLE: {flag('REQUESTS_CA_BUNDLE')}")
print(f"PIP_CERT: {flag('PIP_CERT')}")
try:
with urllib.request.urlopen(URL, timeout=15) as response:
print(f"HTTP: {response.status}")
print(f"Content-Type: {response.headers.get_content_type()}")
except urllib.error.URLError as exc:
reason = exc.reason
print(f"FAILED: {type(reason).__name__}: {reason}")
if __name__ == "__main__":
main()正常预期输出;版本和证书路径会随环境变化:
text
OpenSSL: <OPENSSL_VERSION>
CA file: <PATH>
HTTPS_PROXY: <set|not set>
REQUESTS_CA_BUNDLE: <set|not set>
PIP_CERT: <set|not set>
HTTP: 200
Content-Type: text/html若最后一行以 FAILED 开头,先看异常类型和原始消息,不要只看上层的“安装失败”或“请求失败”。

按错误类型处理
| 典型错误 | 优先检查 | 安全修复 |
|---|---|---|
CERTIFICATE_VERIFY_FAILED |
系统时间、证书是否过期、服务端是否缺少中间证书、企业代理是否重签名 | 修复服务端证书链;把受信任的企业根证书加入专用 CA 文件,并通过 REQUESTS_CA_BUNDLE 或 PIP_CERT 指定 |
407 Proxy Authentication Required、ProxyError |
代理地址、端口、认证方式、账号中特殊字符是否编码 | 使用组织提供的代理配置或凭据管理器;仅在当前进程注入代理变量 |
Tunnel connection failed |
HTTPS 是否经 HTTP CONNECT、代理是否允许目标域名和端口 | 将 HTTPS 代理写成代理服务器实际支持的协议,常见形式为 http://proxy-host:port |
NameResolutionError、ConnectTimeout |
DNS、路由、防火墙、代理绕过规则 | 先验证域名解析和目标端口,再调整 NO_PROXY 或网络策略 |
ReadTimeout |
连接已建立但响应过慢、代理扫描或服务端拥塞 | 分开设置连接与读取超时,必要时有限重试,不要无限等待 |
配置 CA 与代理
以下是配置片段,必须把占位符替换为真实路径和地址。CA 文件应包含 PEM 格式的完整信任链;代理凭据不要直接写入脚本、仓库或共享终端历史。
bash
export REQUESTS_CA_BUNDLE="<PATH>/corp-ca.pem"
export PIP_CERT="<PATH>/corp-ca.pem"
export HTTPS_PROXY="http://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.corp.example"
python -m pip index versions pip --disable-pip-version-check配置生效且网络可达时,预期输出会列出可用版本;具体版本号会变化:
text
pip (<VERSION>)
Available versions: <VERSION_LIST>requests 还可对单次调用传入 verify="<PATH>/corp-ca.pem" 和 proxies=...。单次显式配置更容易审计,也不会意外影响同一进程中的其他请求。
风险与边界
触发证书错误时使用 verify=False、PYTHONHTTPSVERIFY=0、pip --trusted-host 或全局关闭校验,会让中间人攻击和错误目标证书无法被发现。安全替代方案是修复证书链、安装受控根证书,或仅对明确的内部域名使用专用 CA。
把含账号密码的代理 URL 写进命令行、日志或配置仓库,可能泄露凭据。优先使用系统凭据存储、短期环境变量或无密码的本地代理端点,并对诊断输出做脱敏。
排障清单
- 保存最底层异常、目标 URL、Python 与
pip使用的解释器路径。 - 用最小脚本复现,区分证书、代理、解析、连接和读取超时。
- 检查系统时间、CA 路径、代理变量及大小写版本、
NO_PROXY。 - 修复后重新运行最小请求,再恢复原安装或业务请求。
- 仅在隔离环境做临时绕过,并在验证完成后立即撤销。