SSL 证书校验失败：CERTIFICATE_VERIFY_FAILED unable to get local issuer certificate

(MaxRetryError("HTTPSConnectionPool(host='huggingface.co', port=443): Max retries exceeded with url: /api/models/hr16/yolox-onnx/revision/main (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1007)')))")

现象与触发场景

常见触发场景：

• Windows 便携版内置 Python 没有使用最新的 CA 根证书包
• 公司/学校网络做了 HTTPS 中间人解密，装了自签根证书但 Python 不认识
• 代理软件（Clash 等）的 MITM 证书没有被 Python 信任
• 系统时间/日期不正确导致证书被判为未生效或已过期

根因

• Python 的证书链校验使用 certifi 提供的 CA bundle，而 Windows 便携版的内置 Python 默认没有把 certifi 的 cacert.pem 指给 SSL 模块，于是所有 HTTPS 请求都找不到签发者（unable to get local issuer certificate）。
• 企业代理把 TLS 连接解密后用自己的根证书重签，该根证书只装进了 Windows 证书store，没有进 Python 的 CA bundle。
• aiohttp / requests 各自维护连接池，报错会分别表现为 requests.exceptions.SSLError、ClientConnectorCertificateError 或包在 MaxRetryError 里。

解决步骤

已按「最可能有效」排序。请从上往下做，每做完一步用「验证」确认，不要一次改五处。

1. 把 SSL_CERT_FILE 指向内置 Python 自带的 certifi 证书包（Windows 便携版首选）
   便携版 Python 已经自带 certifi 与一份较新的 cacert.pem，只是没被使用。把 SSL_CERT_FILE 环境变量指向它，强制 Python 使用这份证书链；用 setx 永久写入后必须完全重启 ComfyUI（含终端窗口）。路径要按自己的实际安装位置替换。
   setx SSL_CERT_FILE "D:\ComfyUI_windows_portable\python_embeded\Lib\site-packages\certifi\cacert.pem"
   # 临时验证（当前命令行窗口内有效）
   set SSL_CERT_FILE=D:\ComfyUI_windows_portable\python_embeded\Lib\site-packages\certifi\cacert.pem
2. 公司代理/自签证书场景：把企业根证书加入 Python 信任链
   如果出口做了 TLS 解密，正确做法是把企业根证书（.crt/.pem）内容追加到 certifi 的 cacert.pem 后面，或单独保存一个合并后的 pem 再通过 SSL_CERT_FILE 指过去。不要靠关闭校验绕过，否则等于放弃中间人攻击防护。
   # Linux/macOS：把企业根证书追加到 certifi 的 CA 包（示例路径请按实际替换）
   cat corp-root-ca.crt >> $(python -c "import certifi;print(certifi.where())")
3. 确认系统时间正确，并排除代理软件 MITM 干扰
   先检查系统日期时间是否准确（误差过大会直接导致证书无效）。若使用 Clash 等带 MITM 的代理，关闭对相关域名的解密，或把该代理的根证书按上一步导入 Python 信任链。
4. 确认是无头环境/容器：检查 ca-certificates 是否安装
   精简 Docker 镜像常常没装根证书包，表现为所有 HTTPS 都失败。装上系统 CA 包后重试，而不是在代码里关校验。
   apt-get update && apt-get install -y ca-certificates

验证是否修好

补充说明

ComfyUI-Manager 官方文档另给了一个 config.ini 里的 bypass_ssl = True 开关（关闭 SSL 校验）。该做法能立刻让流程跑通，但会放弃证书校验，只建议在临时排查或内网可信环境下使用，排查完应改回并把证书链修好。

来源

1. [163] （官方 issue）　MimicMotionGetPoses · Issue #5613 · Comfy-Org/ComfyUI　https://github.com/Comfy-Org/ComfyUI/issues/5613
2. [164] （官方 issue）　WD14Tagger|pysssss Cannot connect to host cdn-lfs.hf.co:443 ssl:True [　https://github.com/Comfy-Org/ComfyUI/issues/5096
3. [162] （官方文档）　ComfyUI Manager 故障排除（SSL 证书验证失败 / bypass_ssl） - ComfyUI　https://docs.comfy.org/zh/manager/troubleshooting
4. [165] （节点仓库 issue）　[Bug] SSL: CERTIFICATE_VERIFY_FAILED when installing nodes in ComfyUI 　https://github.com/Comfy-Org/ComfyUI-Manager/issues/2076

这条报错要用到的东西

按本条报错所属的类别（网络、下载与访问（含国内网络环境））列出站内相关的下载包与板块入口。 它们不是「必须下载才能修好」，而是这一类问题里最常要动到的东西；具体怎么做，以上面的解决步骤为准。

同一类别的其他条目

返回报错库