unable to get local issuer certificate — 第一次就失敗、而且永遠不重試的那個報錯

客戶端和端點之間出的岔子，絕大多數都會被自動重試掉——伺服器錯誤、過載、請求超時、斷連、臨時限流，都會指數退避重試最多 10 次，然後才可能讓你看見。TLS 證書驗證失敗是極少數一次都不重試的，它在第一次嘗試就把錯誤丟擲來。這件事把判斷方向整個反過來了：一個瞬間就出現、而且每次都出現的報錯，不是「這家服務不穩」的證據，恰恰是「問題在本地、可復現、歸你修」的證據。

你看到的報錯

Error: unable to get local issuer certificate

Error: self-signed certificate in certificate chain

{ code: 'SELF_SIGNED_CERT_IN_CHAIN' }
{ code: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE' }

SSL certificate verification failed
SSL certificate error (...)

這四段說的是同一件事，只是站在不同高度描述。你的執行時拿到伺服器出示的證書，想沿著證書鏈一路走到一個它本來就信任的根，走不通。報錯資訊告訴你的是在哪一步斷的。

這些都不代表伺服器掛了。真掛了的伺服器，根本走不到「出示證書」這一步。

讓這個報錯顯得比實際嚴重的，是重試的不對稱

把這張表當成一個篩子來讀：有重試預算的故障，必須連續失敗 10 次、而且每次間隔越來越長，才輪得到你看見。沒有預算的，第一次就到你眼前。所以出現得越快的報錯，越系統性地偏向「沒人給它重試」的那一類。這意味著很大一部分被人描述成「這服務時好時壞」的故障，性質其實是反的：一個穩定的、本地的、可復現的配置問題，只是它和終端之間恰好沒有任何緩衝。

落到實用一句話：30 秒才蹦出來的報錯，和瞬間蹦出來的報錯，不是同一類問題，哪怕文案長得像。出錯的快慢本身就是診斷資訊。在動手改任何東西之前先用它。

兩條必須說清楚的限定。證書失敗並不是一直都免於重試的——早期版本會讓它先走完整個重試預算，所以在舊版本上，證書問題看起來也是又慢又飄的。另外，「TLS 報錯」不等於「不重試」：握手超時是瞬時故障，照樣重試。把出錯快慢當訊號用之前，先在你自己正在跑的那個客戶端版本上確認一次實際行為。

到底是哪一層壞了

多數同類文章上來就是「把證書加上」。這對第二、第三行有用，對第一、第四、第五行完全沒用。下面這一節的順序，是為了讓你在動手改之前先知道自己在哪一行。

按這個順序排查

HOST=api.9coding.com
openssl s_client -connect "$HOST:443" -showcerts </dev/null 2>/dev/null \
  | openssl x509 -noout -issuer -subject -dates

node -p "process.version"
node -p "typeof require('tls').getCACertificates"   # "function" 表示讀得到系統信任庫

security find-certificate -a -p /Library/Keychains/System.keychain > ~/corp-ca.pem
security find-certificate -a -p /System/Library/Keychains/SystemRootCertificates.keychain >> ~/corp-ca.pem

Get-ChildItem Cert:\LocalMachine\Root, Cert:\LocalMachine\CA |
  ForEach-Object {
    "-----BEGIN CERTIFICATE-----"
    [Convert]::ToBase64String($_.RawData, 'InsertLineBreaks')
    "-----END CERTIFICATE-----"
  } | Set-Content -Encoding ascii $HOME\corp-ca.pem

sudo cp corp-root.crt /usr/local/share/ca-certificates/corp-root.crt   # Debian/Ubuntu
sudo update-ca-certificates
# RHEL/Fedora：放 /etc/pki/ca-trust/source/anchors/ 然後 `sudo update-ca-trust`

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt   # Debian/Ubuntu
# macOS/Windows：用你剛寫出來的那個檔案

openssl s_client -connect "$HOST:443" -CAfile "$NODE_EXTRA_CA_CERTS" </dev/null 2>&1 \
  | grep -i 'verify return code'
# 要的是：Verify return code: 0 (ok)

claude --debug
# 然後讀 ~/.claude/debug/ 下最新的那個檔案

# <模型 id>：從 https://api.9coding.com/v1/models 裡複製一個
curl -sS -w '\n%{http_code}\n' https://api.9coding.com/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"<模型 id>","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

node -e 'require("https").get("https://api.9coding.com/", r => console.log(r.statusCode))
  .on("error", e => console.error(e.code, "-", e.message))'

那個你一定會想設、但不該設的變數

每一個討論這個報錯的帖子，最後都會冒出 NODE_TLS_REJECT_UNAUTHORIZED=0。它確實能讓報錯消失。它實際做的事是這樣的。

它關掉的是整個程序的 TLS 證書校驗——不是某一個主機，也不是某一次請求。這個程序往外發的每一條 HTTPS 連線，包括你根本沒想到的那些，從此會接受任何能坐在你和目的地之間的人遞過來的任何證書。而在一臺流量本來就正在被攔截的機器上，這恰好是你原本用來察覺這件事的那個性質。

你手上原本是一個配置問題，第 3 步兩分鐘就能解決。這一下把它換成了一個安全問題：它是無聲的，在有人發現之前會一直在，而且會跟著你複製過去的任何指令碼和映象一起擴散。如果你確實為了五分鐘的實驗設過一次，就在同一個會話裡把它取消掉。

不存在「只是在內網端點上測一下所以沒關係」的版本。信任一個指定的 CA 是同樣的工作量，而且它讓其他所有連線的校驗都保持開著。

什麼時候這不是你的問題

以下情況說明你看到的是運營方的證書，不是你的配置：

• 第 1 步顯示簽發者確實是公共 CA，而 notAfter 已經過去，
• 或者第 1 步顯示只有葉證書、沒有中間證書，且 curl 報一樣的錯，
• 並且換一臺機器、換一個網路也能復現——手機熱點就夠了，
• 而且它是在你這邊沒有任何改動的情況下開始的。

證書過期是一件有人漏掉的排期事件，所以它通常以小時計恢復，不是以分鐘計。在你花一下午重建信任庫之前，先去看運營方的狀態頁——我們的在狀態頁。

提問題時請帶上 request id——9Coding 的報錯響應裡都有一個，形如 (request id: 2026...)。這個 id 加上時間戳、模型名和完整報錯文字，就能把那一次呼叫查出來。只說「用不了」的反饋沒法排查。

證書錯誤和連線錯誤不是同一個問題

證書錯誤意味著連線建立成功了，然後校驗沒過——你已經走到了「被遞了一張證書」這一步。ECONNREFUSED、ETIMEDOUT、fetch failed 則表示你根本沒走到那裡，配多少 CA 都不會有任何變化。它們還會被重試，這正是它們感覺慢、而這一個感覺瞬間的原因。請看連線錯誤。

相關報錯

• 連線錯誤 — 分辨網路、代理與端點
• 401 Unauthorized — 兩層認證，一樣的報錯資訊
• 429 Too Many Requests — 為什麼你看見它的時候，重試已經用完了
• 全部報錯速查 — 排查手冊總表