Claude Code 报错 "SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT)":解决方法
返回博客
文章claude codetroubleshootingsegurançadev toolsagente de programação

Claude Code 报错 "SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT)":解决方法

Mafra2026年10月24日阅读约 6 分钟

你更新了 Claude Code,打开会话后,每个请求都失败并报 SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT)。公司的 CA 已经配置好,网络没有任何变化,同一台机器昨天还正常。如果你遇到的正是这种情况,问题很可能不在你的配置,而在 2.1.304 版本。

完整的错误信息是什么?

它在第一个请求时就出现,不会重试,因为从 v2.1.199 起 Claude Code 不再重试证书校验失败:

API Error: Unable to connect to API: SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store

错误信息本身建议设置 NODE_EXTRA_CA_CERTS。如果 CA 从未配置过,这样就能解决。但如果 CA 已经配置好、只是新版本不再使用它,就解决不了。官方仓库的 issue #103680 自 2026 年 10 月 20 日起描述的正是这种情况。

是我的配置问题,还是版本问题?

如果在 2.1.303 上正常、更新后才出错,而你什么都没改,那就是版本问题。如果这台机器从来没成功过,那是配置问题。下表区分了几种情况:

症状可能原因处理方法
新机器或从未配置 CA;日志中看不到 CA 被加载配置问题把 NODE_EXTRA_CA_CERTS 指向 CA 证书包
2.1.303 及之前正常;日志显示 CA 已加载,但连接仍然失败2.1.304 的回归问题(issue #103680)回退到 2.1.303 并关闭自动更新
只有某个证书链经过 emSign 的 HTTP MCP 服务器报错,新版本中错误码为 CERT_REJECTED据用户报告,与 2.1.304 新增的证书屏蔽列表有关尚无确认的解决办法;关注该 issue
Claude Code 中 UNABLE_TO_GET_ISSUER_CERT 错误的流程图:用 claude --debug 确认 CA 已加载,用官方安装脚本回退到 2.1.303,并用 DISABLE_AUTOUPDATER=1 锁定版本;如果日志中没有 CA,则配置 NODE_EXTRA_CA_CERTS
从报错到绕过,共 4 步。来源:issue #103680(anthropics/claude-code)、CHANGELOG 与官方文档,核对日期 2026年10月24日。

如何确认 Claude Code 已经加载了我的 CA?

用调试日志启动一次会话,查找以 CA certs: 开头的行。如果你的 CA 出现在日志里,而连接依然失败,那你遇到的就是这个回归问题。

claude --version
claude --debug

日志不会输出到终端,而是写入 ~/.claude/debug/<session-id>.txt(或你用 --debug-file 指定的路径)。在 Linux 或 macOS 上:

grep "CA certs" ~/.claude/debug/*.txt | tail -n 20

下面是 #103680 作者在 2.1.304 上贴出的日志片段:CA 已加载,紧接着连接失败:

CA certs: stores=bundled,system, extraCertsPath=C:/.../gateway-ca.pem
CA certs: Loaded 117 bundled root certificates
CA certs: Loaded 123 system CA certificates
CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS
[ERROR] Bedrock ListInferenceProfiles failed: unable to get issuer certificate

如果没有 Appended extra certificates from NODE_EXTRA_CA_CERTS 这一行,说明 Claude Code 没有读取你的文件。这是配置问题,下面关于版本回退的部分不适用。

日志里没有 CA:如何正确配置?

把变量写进 ~/.claude/settings.json 的 env 块,而不仅仅是在 shell 里导出。官方文档解释了原因:后台代理运行在一个监督进程中,它继承最先启动它的那个终端的环境,只有 settings 能覆盖所有会话。

{
  "env": {
    "NODE_EXTRA_CA_CERTS": "/path/to/ca-bundle.pem",
    "CLAUDE_CODE_CERT_STORE": "bundled,system"
  }
}

bundled,system 本来就是默认值:Claude Code 同时信任内置的 Mozilla 证书集和操作系统证书库。只有在之前被人改过时才需要显式设置。证书包必须是 PEM 格式;如果网关由私有 CA 签发,需要同时包含根证书和中间证书。

如何回退到 2.1.303 并锁定版本?

用官方安装脚本指定版本号,然后关闭自动更新。如果不做第二步,Claude Code 会在下一次检查时自动升级回有问题的版本。

macOS、Linux 和 WSL:

curl -fsSL https://claude.ai/install.sh | bash -s 2.1.303

Windows PowerShell:

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.303

确认版本:

claude --version
# 2.1.303 (Claude Code)

然后在 ~/.claude/settings.json 中关闭自动更新:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

确认已生效:

claude doctor
# Auto-updates: disabled (set by env: DISABLE_AUTOUPDATER)

官方文档明确的三个细节:

  • DISABLE_AUTOUPDATER 只关闭后台检查。手动执行 claude update 和 claude install 仍然有效,所以锁定期间团队里不要有人习惯性地运行 claude update。
  • 通过 Homebrew 或 WinGet 安装的版本不会自动更新。如果你用它们安装且仍在 2.1.303 或更早版本,只要不执行升级即可。
  • 如果希望长期降低风险,可以设置 "autoUpdatesChannel": "stable",它大约落后一周,并跳过有严重回归的版本。但这不能保证避开这个具体问题:切换后请检查版本号。

为什么不直接设置 NODE_TLS_REJECT_UNAUTHORIZED=0?

因为它会对所有主机完全关闭证书校验。Claude Code 官方错误参考文档明确不建议这样做。你是用一个可见的错误,换来一个接受任何证书的连接,包括中间人的证书。回退版本是可逆的;打开的 TLS 漏洞你事后不会察觉。

已经修复了吗?

截至 2026 年 10 月 24 日,还没有。官方 CHANGELOG 已更新到 2.1.310,没有任何关于 Bedrock 或网关连接使用自定义 CA 的条目。在该 issue 中,一位用户确认 2.1.306 仍有此问题,另一位贴出了 2.1.307 的日志,问题相同。

要判断何时解除锁定,请关注 #103680 和 CHANGELOG。修复发布后,删除 DISABLE_AUTOUPDATER 这一行并运行:

claude update
claude --debug

在推广给团队之前,先发一个真实请求测试。停留在 2.1.303 也有代价:例如 2.1.309 包含多项沙箱和 Bash 权限检查的修复。锁定版本是为了渡过这个 bug,而不是长期停留。

如果错误只出现在某个 HTTP MCP 服务器上怎么办?

可能是另一个原因。在同一个 issue 中,一位用户展示了一个 "type": "http" 的 MCP 服务器,其证书链经过 emSign Root CA - G1 根证书,从 2.1.304 起无法连接。2.1.307 的日志中出现了 Dropped blocked certificate 和 CERT_REJECTED 错误码,内置根证书数量也从 121 个(2.1.296)减少到 117 个。

据该报告,同一台机器上的 curl、Node 和 openssl 都接受这条证书链,而把 NODE_EXTRA_CA_CERTS 指向该根证书并没有解决问题。目前没有证据表明回退到 2.1.303 能解决这种情况,Anthropic 也没有就屏蔽列表发表官方说明。如果你只有某个 MCP 服务器报错,且其证书链经过 emSign,请把 --debug 日志补充到该 issue 中:正是这类数据能把两个 bug 区分开。

如果锁定版本会让你的主力代理停用几天,可以同时在终端里保留第二个编程代理:Verboo Code 提供无限 token。

喜欢这篇文章吗?
把知识分享给你的朋友。
// 继续阅读

相关文章