修復 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/"