先说一个结论代码里蹦出[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed这一长串报错大多数情况下不是你的业务代码逻辑出了问题而是当前运行环境里缺少一份能被信任的根证书清单。你向某个 HTTPS 地址发请求服务器把自己的证书递过来本地的证书校验组件核对一番之后直接表示不信任TLS 握手就会停在最后一步于是异常信息里除了证书验证失败之外还会带上“握手失败”的描述。这个问题我在几个项目里都踩过。某次内部报表服务调用另一个团队的结算接口请求发过去就抛这个错当时排查了大半天最后发现只是服务器上的根证书库没更新。还有一次是 Python 爬虫在灰度环境里批量抓数据跑着跑着突然成片报错原因是调试代理工具替换了证书代码里又没把对应 CA 加入信任列表。不同语言、不同框架下的报错原文不完全一样但它们背后的机制是相通的要么证书链断了要么根证书缺失要么中间层的证书被换了。这篇文章把 root cause、排查方法、各语言下的修复方式都捋一遍碰到同类问题可以直接照着处理。1. Cert verify failed 是什么先搞清楚 TLS 握手里发生了什么1.1 报错长什么样通常发生在哪些场景先看几个典型的报错形态。Python 的 requests 或者 urllib3 通常会抛requests.exceptions.SSLError: HTTPSConnectionPool(hostapi.example.com, port443): Max retries exceeded with url: /v1/data (Caused by SSLError(SSLCertVerificationError(1, [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1125))))Node.js 里请求 HTTPS 接口时可能会看到Error: certificate has expired at TLSSocket.onConnectSecure ...用 curl 命令行访问时也可能直接输出curl: (60) SSL certificate problem: unable to get local issuer certificate虽然各家报错措辞不同但关键点都指向同一件事无法获得本地签发者证书也就是无法完成证书链的校验。这说明客户端在验证“对方证书是不是由可信的 CA 签发”时找不到可信的根。这种问题经常出现在这么几个场景里新装好的 Python、Node.js 环境直接跑 HTTPS 请求就报错系统证书库本身不完整。内网服务调用对方使用了私有 CA 签发的证书本机没有信任这个 CA。本地联调时开了抓包代理代理生成的根证书没导入系统信任区。服务器系统时间不对导致证书有效性判断失败。某个服务长期运行系统根证书过期后没有执行系统更新。1.2 TLS 握手的基本流程与证书验证的位置要弄明白这个错需要回顾一下 TLS 握手过程。以 TLS 1.2 为例一次正常的握手大致经过这么几步ClientHello客户端告诉服务器支持的 TLS 版本、加密套件以及一个随机数。ServerHello服务器选择协议版本和加密套件也发一个随机数。服务器发送 Certificate把自己的证书一般是证书链包括叶子证书和中间证书交给客户端。服务器发送 ServerKeyExchange / CertificateRequest按需和 ServerHelloDone。客户端验证服务器证书生成预主密钥pre-master secret用服务器公钥加密后送回。双方各自计算会话密钥交换 ChangeCipherSpec完成握手。CERTIFICATE_VERIFY_FAILED发生在第 5 步也就是客户端验证服务器证书的阶段。客户端拿到服务器传来的证书之后要沿着证书链一层一层往上找信任锚最终必须落到一个本机预先信任的根证书上。任何一环断裂或者某个证书过期、被撤销、主机名不匹配验证都会失败。TLS 1.3 在握手阶段把所有证书消息合并在一起顺序稍有不同但验证逻辑一致。所谓的“握手失败”本质就是验证失败之后客户端拒绝继续协商密钥直接中断连接。所以这个错误看起来是“连接层”报错实际是“信任层”问题。1.3 证书验证失败的几个信任原则理解这个错误还要记住证书验证的三个基本原则链式信任终端实体证书必须由可信 CA 签发。证书链可以一层套一层但最终要能找到本机信任库里的根证书。有效期校验每个证书都有生效时间和失效时间。系统时间超出这个范围验证就会失败。尤其要注意服务器证书本身有效但中间证书或根证书过期同样会导致失败。用途校验证书的扩展项里限制了用途比如只能用于服务端认证。如果请求的连接方式与证书用途不匹配也会报错。很多人在排查时报错定位到了“证书验证失败”就停了其实应该继续追问是哪一层验证失败是找不到根证书还是证书链不完整还是时间不正确还是主机名不匹配这几个方向对应完全不同的修复手段。2. 六大根因定位为什么证书验证会失败2.1 根证书缺失或过期是最常见的原因开发机、测试服务器上的根证书不是一成不变的。操作系统和运行语言各自维护一份证书库。常见的 Linux 发行版安装了ca-certificates包之后根证书会放在/etc/ssl/certs/下并生成一个哈希索引。如果这个包长期没更新新出现的商业 CA 根证书就不会出现在里边客户端自然无法验证新签发的服务器证书。某些国外或国内 CA 在特定时间段启用了新的根证书同时服务器端只发新链不完全兼容旧根。这种情况在老旧镜像里特别容易出现因为镜像构建时打包的系统包快照已经过时。现象就是同样的代码在本机能跑通放到某个服务器或容器的镜像里就报错这就是两个环境的证书库内容不一致。2.2 语言运行环境与系统证书库不同步Python 是一个重灾区。Python 默认使用 OpenSSL 来执行 TLS 连接而 OpenSSL 读取证书库的位置取决于编译参数和运行环境配置。有些 Python 发行版在安装时会附带自己的 OpenSSL 库和证书文件它可能并不读取系统的/etc/ssl/certs而是读取安装目录下的某个证书文件。这就解释了为什么会出现“明明系统配置好了 CAPython 还是报错”的怪现象。你在系统层面信任的根证书跟 Python 进程实际读取的根证书可能是两份完全不同的文件。Node.js 也一样。Node 的 TLS 实现默认使用系统内置的根证书集合但当运行环境中存在NODE_EXTRA_CA_CERTS变量时加载逻辑又会发生变化。如果该文件路径不存在或格式不合法Node 可能退回到不完整的内置证书集合甚至导致额外的验证失败。2.3 系统时间漂移导致的验证失败证书有效期校验依赖一方是相对精确的系统时间。如果服务器或客户端的时间差了很远比如分钟级错误证书的“not before”和“not after”判断就会失败。曾有一个案例一台物理机因为主板 CMOS 电池没电系统时间停在了初始化那一年跑任何 HTTPS 请求全部报证书验证失败。用date命令看了一眼时间立刻反应过来。还有一种隐蔽情况是虚拟机或容器的时区设置正确但硬件时钟偏低。Linux 虚机没有同步硬件时间启动后时间停留在上次关机时间点也会触发这个问题。2.4 本地开启调试代理或抓包工具导致证书被替换客户端与服务器之间如果多了一层代理代理为了解密流量会生成自己的 CA 证书并用这个 CA 动态签发目标域名的证书从而实现中间人解密。Charles、Fiddler、Wireshark 配合的相关 SSL 代理还有浏览器抓包插件都是这种做法。当你开着这种代理代码里的 HTTPS 请求实际拿到的并不是服务器真正的证书而是代理签发的证书。只要代理的根证书没有被加入系统或语言的信任区证书验证一定失败。此时你去看报错的服务器证书信息会发现它指向的域名虽然是目标域名但证书链顶端不是公开的根 CA而是代理自己的根证书。这种情况在本地开发时非常常见不少人折腾半天甚至还会反过来怀疑是服务器证书出了问题。2.5 自签名证书与私有 CA 的信任问题有些内网系统、开发环境、或者私有化交付的软件会使用自签名证书。自签名证书没有上级 CA 为其背书它的信任和权威完全取决于客户端是否提前导入。如果代码所在机器没有导入对应的证书验证必然失败。私有 CA 情况稍微复杂一点。它虽然有自己的根证书和中间证书但公共系统默认不会信任这些私有根。你需要把私有根证书导入操作系统、语言、或者在代码里显式指定。2.6 服务器端证书链不完整客户端验证证书链时需要拿到完整链路。如果服务器只发了叶子证书而没有把中间证书一并发送客户端在本地证书库中找不到对应的上级证书就会提示unable to get local issuer certificate。这种情况适合用openssl s_client直接检查服务器返回的证书链能一眼看出少了一层。3. 实操一套通用的修复流程3.1 先确认到底是谁的证书不信任拿到这个报错之后第一步不是改代码而是验证服务端证书本身。可以先用命令行工具看一眼对方服务器返回的证书链openssl s_client -connect api.example.com:443 -showcerts -servername api.example.com如果verify return code: 0 (ok)说明服务端证书链本身没问题问题大概率出在本机信任库。如果返回不是 0比如unable to get local issuer certificate或unable to verify the first certificate要重点检查服务器发送的证书链是否完整。再检查本机时间date偏差超过几分钟可以直接修正时间后再测。这是成本最低的排查手段。检查当前环境的证书库是否完整也是这里的关键步骤。3.2 更新系统级证书库如果是系统证书库过期在 Debian 系的 Linux 发行版上可以执行sudo apt-get update sudo apt-get install --reinstall ca-certificates sudo update-ca-certificatesupdate-ca-certificates命令会扫描/usr/local/share/ca-certificates/下的自定义证书并重新生成/etc/ssl/certs/下的证书索引。执行完之后大部分的“系统级”报错都能解决。RHEL 系的发行版使用update-ca-trustsudo yum install -y ca-certificates sudo update-ca-trust force-enable sudo update-ca-trust extract更新完系统证书库之后用 curl 再测试一次同一个地址curl https://api.example.com/v1/data如果 curl 已经能连通说明问题确实出在系统信任层。后面再逐个检查语言环境。3.3 Python 环境里利用 certifi 显式指定证书在 Python 里最简单可靠的修复就是把 requests 使用的证书指向 certifi 提供的 CA 包。certifi 是一个维护得很及时的根证书集合它会跟随 requests 等库一起分发。pip install --upgrade certifi然后在代码里显式传入import requests import certifi resp requests.get(https://api.example.com/v1/data, verifycertifi.where())这样 requests 在构建 SSLContext 时会使用 certifi 的 CA 文件而不是默认的 system store。如果项目里用到了 urllib3 的 PoolManager也可以指定 ca_certsimport urllib3 import certifi http urllib3.PoolManager( cert_reqsCERT_REQUIRED, ca_certscertifi.where() ) resp http.request(GET, https://api.example.com/v1/data)如果系统级 CA 已经修好理论上 requests 也会正常工作。但显式指定 certifi 有个好处它不依赖系统目录权限也不怕 Python 环境里的 OpenSSL 配置混乱。我建议在脚本化的项目里直接把它写进公共请求封装里。对于 aiohttp 或 httpx则可以分别参考下面的写法import aiohttp import certifi import ssl ssl_ctx ssl.create_default_context(cafilecertifi.where()) async with aiohttp.ClientSession(connectoraiohttp.TCPConnector(sslssl_ctx)) as session: ...import httpx client httpx.Client(verifycertifi.where())3.4 设置环境变量解决 OpenSSL 证书路径问题OpenSSL 类的程序会读取SSL_CERT_FILE和SSL_CERT_DIR环境变量。当发现 OpenSSL 读的证书跟系统不同步时可以直接把变量指到系统证书目录export SSL_CERT_FILE/etc/ssl/certs/ca-certificates.crt export SSL_CERT_DIR/etc/ssl/certs也可以指到 certifi 的证书文件export SSL_CERT_FILE$(python -m certifi)这种方式对很多用 libcurl 编写、或者使用系统 OpenSSL 的组件有效。把它写进项目的启动脚本或者部署配置里不用改代码就能全局生效。CURL_CA_BUNDLE环境变量可以影响 curl 的证书加载不过没有SSL_CERT_FILE的范围广两处最好保持一致。3.5 Node.js 导入额外 CANode.js 项目如果遇到系统 CA 不匹配临时方式是指定NODE_EXTRA_CA_CERTS环境变量指向一个包含额外 CA 证书的文件export NODE_EXTRA_CA_CERTS/path/to/extra-ca.pem node app.js这个环境变量会把指定的 CA 追加到 Node 默认证书集合里。它适合处理私有 CA、企业内网 CA 的场景。如果是全局信任的问题可以把根证书放到/etc/ssl/certs/并执行update-ca-certificatesNode 在多数 Linux 发行版上会读取系统信任链。不过要注意不同版本的 Node 对系统证书库的加载方式略有差异某些版本基于内置的根证书列表某些版本会直接走系统 OpenSSL。所以最稳妥的方式是环境变量显式追加。npm 如果连 registry 都拉不动出现证书验证失败可以优先看下 npm 的配置npm config list检查cafile和strict-ssl配置。正常情况下strict-ssl应该保持true不要为了省事把它关掉。如果内网 npm 源使用私有证书用cafile指向对应证书文件即可。4. 自签名证书与私有 CA 的工程化处理4.1 导出证书内容与抓取证书链处理自签名证书最常用的命令是通过openssl s_client拿到证书链并导出openssl s_client -connect inner.example.com:443 -showcerts -servername inner.example.com /dev/null /tmp/chain.pem文件里会有多个证书块。找到根证书一般是最后一个证书块保存为my-ca.crt。如果连的是内网 HTTPS 服务且先前能通过浏览器访问也可以在浏览器里点击地址栏的锁图标选择“查看证书”导出根证书。导出格式选 Base64 编码的 PEM 格式就可以。4.2 信任自签名证书或私有 CA拿到根证书之后在系统层面配置信任。Debian 系发行版的做法是把证书放到/usr/local/share/ca-certificates/目录下文件后缀必须是.crtsudo cp my-ca.crt /usr/local/share/ca-certificates/my-ca.crt sudo chmod 644 /usr/local/share/ca-certificates/my-ca.crt sudo update-ca-certificates这样系统级信任就建立起来了curl、一部分通过系统 OpenSSL 入网的程序都会生效。如果不想动系统目录只影响单个 Python 项目就把根证书文件放到项目里并在 requests 请求时指定requests.get(https://inner.example.com, verify./certs/my-ca.crt)Node.js 侧继续用NODE_EXTRA_CA_CERTS环境变量处理。4.3 容器环境里的证书更新Docker 镜像是证书验证失败的另一个常见场景。镜像往往是在几个月甚至一年前构建的内部没有运行包管理器的升级流程。运行镜像后连接互联网 HTTPS 服务报错提示找不到签发者证书。推荐的做法是修改 Dockerfile在构建阶段刷新证书库RUN apt-get update \ apt-get install -y ca-certificates \ rm -rf /var/lib/apt/lists/*如果镜像运行时需要访问内网服务且内网服务使用私有 CA可以把 CA 证书 COPY 进镜像然后在构建时执行COPY my-ca.crt /usr/local/share/ca-certificates/my-ca.crt RUN chmod 644 /usr/local/share/ca-certificates/my-ca.crt update-ca-certificates在 Kubernetes 或容器平台里也可以把 CA 以 ConfigMap 挂载到指定位置然后让应用启动脚本在执行时调用update-ca-certificates。不过挂载目录的动态更新不会自动刷新系统证书索引所以更可靠的方案是在启动命令里加一步调用。4.4 代码里临时信任一张证书的注意点调试阶段如果你只是临时请求某个内网端口测试可以加载证书对象import ssl import socket hostname inner.example.com port 443 context ssl.create_default_context(cafile./my-ca.crt) with socket.create_connection((hostname, port)) as sock: with context.wrap_socket(sock, server_hostnamehostname) as tls_sock: print(tls_sock.version())这个方式没有全局修改任何系统状态适合快速验证一个证书是否有效。但我得特别提醒尽量不要在真实代码中使用verifyFalse来掩盖错误。那是把安全防线直接拆掉。这个写法只能用于彻底隔离的调试环境而且换环境前必须改回。真到了生产环境无论如何都要维护正确的 CA 链。4.5 自己签发证书的正确姿势如果你每天都在自签证书建议不要直接签出叶子证书而是先创建一套私有 CA然后由这套 CA 签发各个服务的证书。这样只需要在客户端信任这一个 CA 根证书以后签新证书不用再逐台机器导入。创建私有 CA 的最小流程是# 生成 CA 私钥 openssl genrsa -out ca-key.pem 2048 # 生成 CA 自签名证书 openssl req -new -x509 -days 3650 -key ca-key.pem -out ca-cert.pem \ -subj /CNInternal Demo CA之后每个服务生成自己的私钥和证书签署请求openssl req -newkey rsa:2048 -nodes -keyout service-key.pem \ -out service.csr -subj /CNinner.example.com openssl x509 -req -days 825 -in service.csr \ -CA ca-cert.pem -CAkey ca-key.pem -CAcreateserial \ -out service-cert.pem -extfile ext.confext.conf里配置subjectAltNameDNS:inner.example.com这一步不能省。现代客户端校验证书时基本都会检查 SAN忽略它的话即使 CA 已信任也无法避免主机名不匹配的问题。5. 不同场景下的修复差异与常见问题速查5.1 报错信息对照与处理方法报错关键字可能原因优先处理方式unable to get local issuer certificate证书链不完整或根证书缺失更新系统证书库或显式指定 CA 文件certificate has expired证书过期或系统时间偏差检查服务端证书同时校对本机时间self-signed certificate对方使用自签证书导入自签根证书或私有 CAhostname mismatch域名与证书 CN/SAN 不匹配使用正确的服务域名访问或重新签发匹配域名的证书wrong version number该地址其实不是 HTTPS 或端口不对检查协议与端口配置tlsv1 alert protocol version本地 TLS 版本过低或服务器不支持该版本升级 OpenSSL 与运行语言版本5.2 Python 的 Mac 开发环境特殊案例在 macOS 上装完 Python有时会出现“明明浏览器访问都没问题但 Python 请求就报证书验证失败”。这通常是因为 Python 在安装时没有自动读取系统钥匙串里的根证书。处理办法是安装 certifi 并配置默认证书pip install certifi然后可以直接把 certifi 的证书路径设置为 Python 环境变量export SSL_CERT_FILE$(python3 -m certifi)把这一行写进~/.zshrc或~/.bashrc。经过这个调整Python 的 URLLIB 和 requests 就能正常访问大多数 HTTPS 服务了。如果代理工具也在用确认代理根证书同时加入了钥匙串与 certifi 文件。5.3 Node.js 请求外部服务时报 verify 错误Node.js 的fetch或http模块走的是内置 TLS。遇到证书错误时先检查是不是有NODE_EXTRA_CA_CERTS这个变量被设置成了不存在的文件路径。有时候全局配置里残留了早期调试的 export导致 Node 加载异常。用下面的命令确认node -p process.env.NODE_EXTRA_CA_CERTS如果为空或已失效直接重设后再启动应用。还想再提供一个小命令查看 Node 实际使用的 CA 数量node -e console.log(require(crypto).X509Certificate.prototype.toString.length)这个不太常用大多数时候直接看环境变量和系统证书库就够了。5.4 调试代理场景下的证书修复本地开着抓包代理时出现这个报错我的处理顺序是先导出代理根证书。把这个根证书导入到系统信任区。Windows 证书管理器、macOS 钥匙串、Linux 的/usr/local/share/ca-certificates/都可以。对 Python如果 requests 显式指定了verifycertifi.where()还需要把代理根证书追加到 certifi 的证书文件里。对 Node.js可以通过NODE_EXTRA_CA_CERTS指定包含代理根证书的文件。验证时间与代理自身的有效性。debug 完成关闭代理以后如果不再需要把信任的根证书移除避免以后对正式环境的请求误信任代理 CA。5.5 检查证书库是否生效更新完证书之后要验证是否真正生效。Python 里可以这样查看当前信任的证书路径import ssl print(ssl.get_default_verify_paths())输出里cafile和capath就是当前默认配置会去寻找的证书位置。如果和预期不符就知道问题出在哪一层。还可以用 Python 直接确认某个证书文件能否被 OpenSSL 正确读取python -c import ssl; ssl.create_default_context(cafile/etc/ssl/certs/ca-certificates.crt); print(ok)如果打印 ok说明证书文件格式和路径都没问题。5.6 生产环境里要不要关验证听我一句生产环境里不要通过关闭验证来修复问题。verifyFalse是一时爽后续是灾难。一旦 TLS 校验失效中间人攻击就变成了实际风险而且出现问题后很难排查。生产环境正确的做法是把 CA 纳入版本管理随代码一起部署并在部署脚本里执行证书刷新。把 CA 集中在一个受控仓库里每次有证书更新就走变更流程才是一套可持续的方案。6. 我踩过的一些坑和最终建议最后分享几条在实际处理中总结出的经验。第一碰到这个报错先修系统时间再做后续排查。时间的坑太隐蔽了往往会消耗很久。我以前有一次排查接口报错检查了证书链、环境变量、代理配置最后才发现是测试服务器的时间与标准时间差了将近三小时。当时的感觉真是哭笑不得。第二Python 跟系统证书不要混在一起想。系统 CA 更新了不代表 Python 就能立刻读到。很多人在服务器上执行完update-ca-certificates以为 Python 会自动好起来实际上 Python 的 OpenSSL 不一定读取这个路径。显式传verifycertifi.where()或者设置SSL_CERT_FILE是最稳的。第三调试代理留下的根证书要记得清理。曾经一个项目在代码里加入了抓包工具的根证书用于本地调试结果部署到预发布环境后忘了解除预发布环境的所有 HTTPS 请求都经过了代理 CA 信任链幸好监控发现得早否则生产环境也会带病上线。如果你有类似调试工具一定要按环境去隔离信任配置不要一份配置通吃全部环境。第四容器镜像的证书更新要写进构建流程。不要依赖某个基础镜像自带的证书因为镜像构建日期早、证书过期是很容易被忽略的定时炸弹。加一行apt-get install ca-certificates并清理缓存成本极低收益却很直接。这几招用下来绝大多数CERTIFICATE_VERIFY_FAILED问题都能在几分钟内定位。以后再看到“握手失败”就不至于手足无措了。