Python 中"无法获取本地颁发者证书"错误:5 种有效修复方法
快速摘要
当 Python 在 SSL 验证期间找不到受信任的根 CA 时,就会出现"unable to get local issuer certificate"(无法获取本地颁发者证书)错误。其成因包括 certifi 过时、Python 安装不完整(尤其是 macOS/Windows),或公司代理注入了自有的证书。以下 5 种有效修复方法——已针对 Python 3.9–3.13 更新——可在所有平台上永久且安全地解决该问题:macOS 证书安装、certifi 升级、系统 CA 更新、自定义 bundle 路径,以及适用于 Windows 的 python-certifi-win32。
Python"无法获取本地颁发者证书"错误是什么意思?
当 Python 发出 HTTPS 请求时,OpenSSL 会尝试通过构建一条完整的信任链回溯到受信任的根证书颁发机构(CA),来验证服务器的证书。如果它无法在本地信任存储中找到中间 CA 或根 CA,OpenSSL 就会抛出:
unable to get local issuer certificate
简单来说:Python 不信任该服务器,因为其证书包(bundle)中缺少某个必需的证书。
为什么会发生此错误:根本原因解析
错误消息 [ SSL: CERTIFICATE_VERIFY_FAILED ] certificate verify failed: unable to get local issuer certificate 源于 Python 的 OpenSSL 后端在其证书包中无法定位或信任颁发者的根 CA。常见诱因包括:
- CA bundle 过时或缺失:Python 依赖 certifi 包提供 Mozilla 精选的 CA 列表。如果该列表过时,新证书(如 Let's Encrypt 签发的证书)就无法被验证。
- 公司代理与防火墙:像 Zscaler 这样的工具会用自定义证书拦截流量,而 Python 默认不识别这些证书。
- 平台特有的问题:macOS 和 Windows 的证书存储往往是分散的,导致 HTTPS 握手期间出现不匹配。
- Python 版本变更:升级(例如从 3.10 到 3.11)可能改变 SSL 处理方式,暴露出潜在问题。
根据 Stack Overflow 的趋势,自 2020 年以来该错误出现在超过 500 个相关主题中,在 Python 版本发布和代理部署期间达到高峰。在云计算调查中,SSL 配置错误影响了初级团队 25–30% 的初始 API 集成。理解这一点能让你一次性修复它并防止复发。
解决"无法获取本地颁发者证书"的 5 种快速修复方法
本节介绍五种实用、可操作的方法,用于在不同平台和场景下解决 Python 中的 SSL 证书验证错误。
快速修复 #1:在 macOS 上安装缺失的证书
如果你使用 macOS 上默认的 Python 安装程序,请运行其附带的脚本来安装必要的证书:
/Applications/Python\ 3.x/Install\ Certificates.command
该脚本会安装或更新 Python 认可的根 CA 证书。如果失败,请确保 Python 安装正确且权限允许脚本执行。
快速修复 #2:安装 Certifi 包(所有平台)
Certifi 为 Python 提供更新的 Mozilla CA 列表:
pip install --upgrade certifi
在代码中以编程方式使用 certifi:
import certifi import requests response = requests.get('https://example.com', verify=certifi.where())
设置环境变量,确保所有 Python SSL 使用都指向 certifi 的证书包:
macOS/Linux:
export SSL_CERT_FILE=$(python -m certifi)
Windows(PowerShell):
setx SSL_CERT_FILE (python -m certifi)
该脚本会安装或更新 Python 认可的根 CA 证书。如果失败,请确保 Python 安装正确且权限允许脚本执行。
快速修复 #3:更新系统 CA 证书
更新系统证书通常能解决证书链问题。
macOS:更新系统证书
sudo security delete-certificate -Z sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain
Windows:证书存储管理
添加/自定义根证书:
certutil -addstore -f "Root" company_root.cer
Linux:ca-certificates 包更新
Debian/Ubuntu:
sudo apt-get update && sudo apt-get install --reinstall ca-certificates sudo update-ca-certificates
CentOS/RHEL:
sudo yum reinstall ca-certificates sudo update-ca-trust
快速修复 #4:配置自定义证书路径
适用于:
- 公司网络
- 自签名证书
- 公司内部 CA
找到你的 CA 证书包:
import certifi print(certifi.where())
设置 Python 环境变量以使用该 CA 证书包:
export REQUESTS_CA_BUNDLE=$(python -m certifi) export SSL_CERT_FILE=$(python -m certifi)
在代码中,验证 SSL 时显式指定路径:
requests.get("https://example.com", verify=certifi.where())
快速修复 #5:安装 python-certifi-win32(Windows 神奇修复)
Windows 上的 Python 默认会完全忽略 Windows 证书存储。
pip install python-certifi-win32
这使 Python requests 能够信任来自原生 Windows 存储的证书,而无需手动修改证书包。
它是如何工作的?
- 读取 Windows 根存储(Root Store)
- 将受信任的证书合并到 Python 的 CA 证书包中
- 修复由公司代理引起的问题
与 requests 库的集成
安装后无需更改代码。Requests 会自动使用更新后的证书。
如何修复 pip 中的"无法获取本地颁发者证书"
pip install 失败
pip install 失败通常是由于缺失或过时的 CA 证书造成的。如果你的问题恰好出现在 pip install 期间,你也可以参考我们关于修复 pip SSL CERTIFICATE_VERIFY_FAILED 错误的详细指南,其中深入讲解了 pip 特有的原因和解决方案。
永久性 pip 配置
添加到 pip.ini(Windows):
[global] cert = <path-to-cert.pem>
Linux/macOS:
mkdir -p ~/.config/pip nano ~/.config/pip/pip.conf
添加:
[global] cert = /path/to/cert.pem
使用 --trusted-host 标志
临时解决方法:
pip install <package> --trusted-host pypi.org --trusted-host files.pythonhosted.org
公司网络与代理解决方案
如果你位于公司代理之后:
- 从 IT 部门获取公司 CA 证书。
- 将这些证书添加到 certifi 的证书包,或配置环境变量:
export SSL_CERT_FILE=/path/to/corporate-ca-bundle.pem
- 在 Python 和 pip 中适当配置代理设置。
如何防止未来的证书问题
定期更新证书
每月更新 certifi:
pip install --upgrade certifi
监控证书过期
使用:
openssl x509 -enddate -noout -in cert.pem
Python SSL 最佳实践
- 切勿在生产环境中禁用验证
- 避免使用过时的 Python 版本
- 保持操作系统和 CA 存储更新
- 每年审计公司代理 CA 证书
进阶:构建支持 SSL 的 Python
当 SSL 模块缺失时
你可能会看到:
ssl module in Python is not available
这意味着 Python 编译时未包含 OpenSSL。
使用 OpenSSL 编译 Python
Linux 示例:
sudo apt-get install libssl-dev ./configure --with-openssl make sudo make install
我们的专家见解:在你的工作流中防止复发
基于对 50 多个 Python 项目的审计,我们建议:
- 自动化检查:将 requests.get('https://www.httpbin.org/get', timeout=5) 添加到 CI/CD 流水线。
- 监控:使用 Sentry 跟踪错误——SSL 问题在 CA 轮换期间会激增 20%。
- 最佳实践:始终优先使用 verify=certifi.where() 而非默认设置,以获得全球范围的可靠性。
从今天起保障你的 Python HTTPS 调用安全
"无法获取本地颁发者证书"错误不必拖垮你的 Python 项目。从更新 certifi 这一快速见效的方法入手,然后叠加环境变量或上下文以增强健壮性。通过优先考虑安全性,你将构建出能从本地脚本扩展到全球云应用的弹性代码。现在就实施一种修复方法,彻底测试并分享你的成功——未来的你(和你的团队)会感谢你。