修复 curl、Git、Python 和 Node.js 中的 SSL 证书错误

2026-05-08

curlgitpythonssl-errordevelopment

SSL certificate problem: unable to get local issuer certificate 错误（及其变体）是最常见的开发问题之一。它意味着工具无法验证服务器的证书链——通常是因为系统上的 CA 根证书已过时或缺失。

本指南涵盖正确的修复方法——不只是禁用安全性的 -k / --insecure 变通方案。

根本原因

你的工具根据 CA 证书包——一个包含受信任根证书的文件——来验证 SSL 证书。当这个证书包过时、缺失或服务器的证书链不完整时，验证就会失败。

Your tool → "Is this certificate signed by a CA I trust?"
CA bundle → "I don't have that CA's root certificate"
→ ERROR: unable to get local issuer certificate

curl

错误

curl: (60) SSL certificate problem: unable to get local issuer certificate

修复 1：更新 CA 证书（正确做法）

# Debian/Ubuntu
sudo apt update && sudo apt install ca-certificates
sudo update-ca-certificates

# CentOS/RHEL
sudo yum update ca-certificates

# macOS (Homebrew curl)
brew install ca-certificates

修复 2：指定 CA 证书包路径

curl --cacert /etc/ssl/certs/ca-certificates.crt https://example.com

修复 3：设置环境变量

export CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

不要这样做（除非测试）

curl -k https://example.com  # Disables ALL certificate verification

Git

错误

fatal: unable to access 'https://...': SSL certificate problem: unable to get local issuer certificate

修复 1：更新 CA 证书（与 curl 相同）

sudo apt update && sudo apt install ca-certificates

修复 2：将 Git 指向正确的 CA 证书包

git config --global http.sslCAInfo /etc/ssl/certs/ca-certificates.crt

修复 3：Windows（Git for Windows）

Git for Windows 自带 CA 证书。更新到最新版本的 Git，或者：

git config --global http.sslBackend schannel

这告诉 Git 使用 Windows 内置的证书存储而非自带的。

生产环境不要这样做

git config --global http.sslVerify false  # Disables ALL SSL verification for Git

Python (requests / pip)

错误 (requests)

requests.exceptions.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED]

错误 (pip)

pip install ... Could not fetch URL https://...: connection error: [SSL: CERTIFICATE_VERIFY_FAILED]

修复 1：更新 certifi（Python 的 CA 证书包）

pip install --upgrade certifi

Python 的 requests 库使用 certifi 包获取 CA 证书，而不是系统存储。

修复 2：指向系统 CA 证书包

import requests
response = requests.get('https://example.com', verify='/etc/ssl/certs/ca-certificates.crt')

或设置环境变量：

export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

修复 3：macOS Python（常见问题）

macOS Python 在安装后通常有一个空的证书存储。运行：

# Find your Python install
python3 -c "import ssl; print(ssl.get_default_verify_paths())"

# Install certificates (macOS Python from python.org)
/Applications/Python\ 3.x/Install\ Certificates.command

pip 专用修复

pip install --upgrade pip
pip config set global.cert /etc/ssl/certs/ca-certificates.crt

Node.js

错误

Error: unable to get local issuer certificate
  code: 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY'

修复 1：设置 NODE_EXTRA_CA_CERTS

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt

这会添加额外的 CA 而不替换 Node.js 内置的证书包。

修复 2：开发中的自签名证书

// Only for development — adds a specific CA
const https = require('https');
const fs = require('fs');

const agent = new https.Agent({
  ca: fs.readFileSync('/path/to/custom-ca.pem'),
});

fetch('https://internal-service.local', { agent });

生产环境不要这样做

export NODE_TLS_REJECT_UNAUTHORIZED=0  # Disables ALL SSL verification

企业代理 / 企业环境

许多企业网络使用 TLS 检查代理，用内部 CA 重新签名流量。你的工具不信任这个内部 CA。

修复： 从 IT 部门获取企业 CA 证书并添加它：

# System-wide (Debian/Ubuntu)
sudo cp corporate-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# Python
export REQUESTS_CA_BUNDLE=/path/to/corporate-ca-bundle.pem

# Node.js
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

# Git
git config --global http.sslCAInfo /path/to/corporate-ca-bundle.pem

Docker 容器

Docker 镜像通常有过时的 CA 证书包。修复：

# Debian-based
RUN apt-get update && apt-get install -y ca-certificates && update-ca-certificates

# Alpine
RUN apk add --no-cache ca-certificates

快速诊断

# Test if the SSL connection works with openssl
openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>/dev/null | grep "Verify return code"
# "0 (ok)" = chain is fine, your tool's CA bundle is the problem
# "21 (unable to verify)" = server's chain is incomplete

# Check what CA bundle your system uses
python3 -c "import certifi; print(certifi.where())"
curl-config --ca 2>/dev/null || echo "Check /etc/ssl/certs/"