【BUG已解决】git SSL certificate problem: unable to get local issuer certificate 解决方案1. 问题描述在执行git clone、git pull或git push时终端报错$ git clone https://github.com/example/repo.git Cloning into repo... fatal: unable to access https://github.com/example/repo.git/: SSL certificate problem: unable to get local issuer certificate有时候会看到略微不同的措辞fatal: unable to access https://gitlab.company.com/xxx.git/: SSL certificate problem: self signed certificate in certificate chain这个错误在以下场景特别常见企业内网使用自签名证书的私有 GitLab/Gitea公司代理/防火墙对 HTTPS 流量做了 SSL 中间人检测MITMWindows 上刚安装 GitGit 自带的证书库版本过旧使用了公司 VPN 客户端其证书未添加到系统信任链2. 原因分析Git 通过 HTTPS 协议访问远程仓库时底层依赖 libcurl 做 SSL/TLS 校验。校验失败的核心原因是Git或系统找不到用于验证目标服务器证书的根证书Root CA。客户端发起 HTTPS 请求 ↓ 服务器返回证书链 ↓ Git/curl 尝试沿着证书链找到一个受信任的根证书 ↓ ① 找到了 → 验证通过正常通信 ② 没找到证书链不完整/根证书缺失/自签名证书未加入信任库→ 报错触发场景具体原因私有 GitLab/Gitea使用自签名证书未被系统信任企业代理/防火墙中间人检测插入了自己的证书客户端未信任该证书Windows Git for Windows自带的 CA 证书包版本过旧或路径配置错误Linux 服务器ca-certificates包过旧或未安装VPN软件VPN注入的证书未加入系统信任链3. 解决方案方案一不推荐长期使用临时关闭 SSL 验证# 【BUG已解决】全局关闭有安全风险仅用于紧急场景 git config --global http.sslVerify false # 只对某个特定仓库关闭 cd my-repo git config http.sslVerify false风险提示关闭 SSL 验证意味着 Git 不再校验服务器身份存在被中间人攻击篡改代码的风险生产环境和长期使用强烈不建议。方案二更新 CA 证书库推荐首选Linux (Debian/Ubuntu)sudo apt update sudo apt install --reinstall ca-certificates sudo update-ca-certificatesLinux (CentOS/RHEL)sudo yum reinstall ca-certificates sudo update-ca-trust extractWindows# 更新Git for Windows到最新版本自带证书包会同步更新 winget upgrade --id Git.Git # 或者直接指定使用系统证书库而不是Git自带的证书包 git config --global http.sslBackend schannelmacOS# 更新证书通常随系统更新自动完成也可以用Homebrew强制刷新 brew install ca-certificates brew link --overwrite ca-certificates方案三手动指定 CA 证书文件路径如果确定是某个企业自签名证书导致的问题可以将证书导出并显式指定# 从浏览器或系统证书库导出目标服务器的证书为 .pem 格式 # 假设导出到了 ~/certs/company-ca.pem git config --global http.sslCAInfo ~/certs/company-ca.pem获取证书内容的方法Linux/macOSecho | openssl s_client -connect gitlab.company.com:443 -showcerts 2/dev/null | \ openssl x509 -outform PEM ~/certs/company-ca.pem方案四将企业自签名证书加入系统信任库最规范的方案Linux# 复制证书到系统证书目录 sudo cp company-ca.crt /usr/local/share/ca-certificates/ sudo update-ca-certificates # 验证是否已被系统信任 curl https://gitlab.company.commacOSsudo security add-trusted-cert -d -r trustRoot \ -k /Library/Keychains/System.keychain company-ca.crtWindows# 双击 .crt 文件 → 安装证书 → 选择受信任的根证书颁发机构 # 或用 certutil 命令行导入 certutil -addstore -f ROOT company-ca.crt导入系统信任库后Git 使用 schannel 后端Windows 默认可配置会自动信任git config --global http.sslBackend schannel方案五切换到 SSH 协议彻底绕开 HTTPS 证书问题如果目标仓库同时支持 SSH 访问直接换协议是最省心的方案# 生成SSH密钥如果还没有 ssh-keygen -t ed25519 -C your_emailexample.com # 将公钥添加到GitLab/GitHub账号设置中 cat ~/.ssh/id_ed25519.pub # 把仓库远程地址从https换成ssh git remote set-url origin gitgithub.com:example/repo.git # 验证SSH连接 ssh -T gitgithub.com4. 各方案对比总结方案安全性适用场景推荐指数关闭SSL验证❌ 危险紧急临时排障⭐更新CA证书库✅ 安全大部分场景首选⭐⭐⭐⭐⭐指定sslCAInfo✅ 安全明确知道自签名证书来源⭐⭐⭐⭐加入系统信任库✅ 安全企业内网长期使用⭐⭐⭐⭐⭐切换SSH协议✅ 安全支持SSH的仓库⭐⭐⭐⭐⭐5. 常见问题 FAQ5.1 更新证书后仍然报错如何进一步诊断# 用curl单独测试排除是否是Git本身的问题 curl -v https://gitlab.company.com 21 | grep -i SSL\|certificate # 如果curl也报同样的错说明是系统层面证书链问题不是Git专属问题5.2 GIT_SSL_NO_VERIFY 环境变量与 config 配置的区别# 环境变量方式仅当前终端会话生效适合CI临时使用 export GIT_SSL_NO_VERIFYtrue git clone https://gitlab.company.com/repo.git # git config方式持久化配置影响后续所有git操作 git config --global http.sslVerify falseCI/CD 场景推荐用环境变量方式且用完后记得清除避免影响其他任务。5.3 公司代理软件如Fiddler/Charles导致的证书问题# 这类代理会给HTTPS流量做拦截插入自己的证书 # 需要将代理软件生成的根证书加入系统信任库 # 以Fiddler为例通常在其安装目录能找到FiddlerRoot.cer # 导入系统证书库后还需要让Git信任它 git config --global http.sslCAInfo /path/to/FiddlerRoot.pem5.4 npm/pip 等其他工具是否也有类似问题是的几乎所有基于 HTTPS 的命令行工具都可能遇到相同的根本原因本地缺少可信CA证书。解决思路完全一致# npm 类似配置 npm config set cafile ~/certs/company-ca.pem # pip 类似配置 pip config set global.cert ~/certs/company-ca.pem从根本上把证书加入系统信任库可以一次性解决所有工具的证书问题而不需要给每个工具单独配置。5.5 Docker 容器内 Git 报同样的错误容器内的证书库通常是独立的需要单独处理FROM ubuntu:22.04 # 将企业证书复制进镜像 COPY company-ca.crt /usr/local/share/ca-certificates/ RUN apt-get update \ apt-get install -y ca-certificates git \ update-ca-certificates5.6 团队协作时如何统一解决避免每个人都单独配置将证书文件和配置脚本纳入项目仓库写一个初始化脚本#!/bin/bash # setup_git_certs.sh - 团队统一执行的证书配置脚本 CERT_PATH$(pwd)/certs/company-ca.pem git config --global http.sslCAInfo $CERT_PATH echo ✅ Git SSL证书配置完成5.7 使用 GUI 客户端如 GitHub Desktop、SourceTree时的证书问题排查GUI 工具通常内置自己的 Git 实现或调用系统 Git遇到证书问题时排查思路一致但配置入口不同GitHub Desktop: Preferences → Advanced → 通常直接沿用系统Git配置无需单独设置 SourceTree: Tools → Options → Git → 确认使用的Git版本和证书路径如果 GUI 工具报错但命令行git本身能正常工作说明是该工具自带的Git实现版本较旧建议在设置中切换为使用系统安装的Git。5.8 GitHub Actions / GitLab CI 流水线中遇到证书问题CI 环境通常是全新的容器实例如果需要访问企业内网私有仓库# GitLab CI 示例在流水线开始前统一处理证书信任 before_script: - cp $COMPANY_CA_CERT /usr/local/share/ca-certificates/company-ca.crt - update-ca-certificates - git config --global http.sslCAInfo /etc/ssl/certs/ca-certificates.crt将证书文件通过 CI/CD 平台的受保护变量或Secrets机制注入而不是直接硬编码在流水线脚本中是更安全的做法。5.9 排查是否是本地时间不同步导致的证书验证失败一个容易被忽略的原因——如果本机系统时间严重偏差比如虚拟机/容器时间没有同步会导致SSL证书的有效期校验失败报错信息也可能类似证书问题# 检查系统时间是否准确 date # Linux下同步系统时间 sudo timedatectl set-ntp true sudo systemctl restart systemd-timesyncd # 确认时间同步生效后重新测试git操作 git clone https://github.com/example/repo.git5.10 排查是否是Git版本过旧导致的证书链算法不支持非常老旧的 Git 版本2.x 早期可能不支持较新的 TLS 1.3 或某些现代加密套件git --version # 版本过旧时Ubuntu/Debian可以通过PPA获取更新的Git sudo add-apt-repository ppa:git-core/ppa sudo apt update sudo apt install git5.11 排查完全找不到原因时的最后手段如果排查了所有可能性依然无法解决可以尝试完全重装Git并清空所有历史配置# 备份现有配置 cp ~/.gitconfig ~/.gitconfig.bak # macOS重装 brew uninstall git brew install git # 恢复必要的用户配置但不恢复可能有问题的sslCAInfo等设置 git config --global user.name Your Name git config --global user.email youexample.com5.11.1 补充跳板机/Jump Server场景下的证书链传递问题通过跳板机中转访问内网Git仓库时如果跳板机本身也存在证书信任问题会导致排查更加复杂——需要在跳板机和最终客户端两处都确认证书配置# 在跳板机上先单独验证网络和证书是否正常 ssh jumpserver curl -v https://gitlab.internal.com # 确认跳板机测试通过后再排查本机到跳板机之间的转发配置5.11.2 补充使用 credential.helper 配合 HTTPS 减少重复认证的干扰因素有时候证书问题与认证信息缓存问题同时出现容易混淆排查方向。建议先单独确认证书层面完全通过后再排查认证凭证问题# 清理可能错误缓存的认证信息避免与证书问题混淆排查 git credential-manager erase git config --global credential.helper store6. 排查清单速查表□ 1. curl -v https://目标地址 单独测试是否同样报错 □ 2. 确认是否是企业内网/代理/VPN环境 □ 3. 更新系统CA证书库apt/yum/brew □ 4. 明确证书来源后用 http.sslCAInfo 指定证书文件 □ 5. 长期使用建议把证书加入系统信任库而非单独配置Git □ 6. 支持SSH的仓库优先切换到SSH协议彻底避开问题 □ 7. 绝不在生产/长期环境使用 sslVerifyfalse7. 总结SSL certificate problem: unable to get local issuer certificate的核心是本地缺少验证服务器证书所需的根证书。解决优先级先确认是否是系统级证书库过旧→ 更新 ca-certificates企业内网自签名证书场景→ 获取证书并加入系统信任库而不是单独配置Git支持SSH的仓库→ 直接切换协议从根本上避开HTTPS证书问题绝对不要长期使用sslVerifyfalse绕过验证这会让你的代码传输暴露在中间人攻击风险下企业内网环境建议由 IT 部门统一制作证书安装包通过 MDM 或脚本批量部署到所有开发者机器避免每个人各自摸索踩坑。