📖 介绍 📖

公司内网用 Claude Code 接企业网关（或 Bedrock 专线）的读者，这几天升级到 2.1.304 之后大概率撞上同一堵墙：前一版本还好好的，升级完每次请求直接报

API Error: Unable to connect to API: SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT)

证书明明装进了系统根存储、网关也把完整证书链发过来了，甚至--debug里都能看到「custom CA 已加载」——但验证就是不过。官方仓库 10 月 20 日起陆续聚集了网关直连 Bedrock、HTTP MCP 服务器、Claude Desktop 内嵌 Code 等多条同类报错，至今未修。

这篇文章把「中招人群长什么样、三步判定你属于哪种、每种的处置怎么做、升级前怎么止损」一次讲清。先说结论：这是 2.1.304 引入的证书校验回归，官方仓库有持续讨论且未修复；最稳的止损是回退 2.1.303 并关掉自动更新，等你环境里实测新版修了再升。

🖥️ 演示环境 🖥️

• 📰 依据来源：官方仓库公开 issue 全文与评论（2026-10-20 至 10-22）
• ⏱️ 影响版本：2.1.304 起报错；2.1.295/296/302/303 同配置正常；2.1.306/2.1.307 仍未修复
• 🌐 复现环境（报告者）：Windows 11 原生安装版 + 私有 CA 签名的 HTTPS 网关
• 🙅 本文边界：作者无企业网关环境，未实跑复现；以下判定步骤全部锚定官方公开讨论，你的环境结论请以--debug实际输出为准

📢注意：本文内容为个人学习笔记，仅供参考。附：读者须知

🧩 症状对照：你是不是这一类

满足下面全部三条，基本就是本次回归：

1. 版本：2.1.304 及以上（2.1.306、2.1.307 仍复现）；
2. 拓扑：请求经过私有 CA 签名的 HTTPS 网关（Bedrock 专线、企业 TLS 网关），或连接HTTP 型 MCP 服务器时报UNABLE_TO_GET_ISSUER_CERT_LOCALLY；
3. 配置未变：同样的CLAUDE_CODE_CERT_STORE=bundled,system（或NODE_EXTRA_CA_CERTS）配置，2.1.303 及之前全部正常。

不满足的——比如报的是self signed certificate、certificate has expired，或者根本没走任何私有 CA——是另一类证书问题，处理路径不同，别硬套本文。

🔍 二、三步判定：证书到底在哪一环断的

🎯 先分清：报的是「颁发者找不到」，不是「证书不可信」

UNABLE_TO_GET_ISSUER_CERT的字面意思是：验证方找不到给你网关证书签名的上一级 CA。这跟「证书被拒」不同——不是你的根证书不被信任，而是证书链没拼全或拼了没用上。两者的修法完全不同，先认准报错串。

🧾 再跑--debug：读 CA 加载清单

claude--debug

关注输出里这几行（2.1.304 的真实样例）：

CA certs: stores=bundled,system, extraCertsPath=C:/.../gateway-ca.pem CA certs: Loaded 117 bundled root certificates (2.1.296: 121) CA certs: Dropped 51 expired certificate(s) from system store CA certs: Loaded 123 system CA certificates CA certs: Dropped blocked certificate d7a7a0fb... from system (new in 2.1.304) CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS [ERROR] Bedrock ListInferenceProfiles failed: unable to get issuer certificate

逐行解读：

• stores=bundled,system+Appended extra certificates：你的 CA 三条路（内置包、系统存储、NODE_EXTRA_CA_CERTS附加文件）全都加载了——加载没问题；
• Dropped blocked certificate ... (new in 2.1.304)：2.1.304 新增了「按指纹拉黑特定根证书」的行为。如果你网关的 CA 链上有证书恰好被列入拉黑名单（或因上游证书撤销被连带），它会被静默丢弃——这正是一些环境「配置没动却突然全挂」的可疑点；
• Dropped N expired certificate(s)：过期证书清理也是 2.1.304 新行为，过期中间证书被清掉同样会造成链断。

🔀 最后区分：「链没发全」和「链发了被弃用」

这是本次回归最绕的地方，官方仓库报告者给了一个非常有诊断价值的观察：debug 日志显示 CA 列表构建正确（系统存储已加载、extra PEM 已附加），但验证依然失败——说明构建好的自定义 CA 列表没有被真正用于网关连接的验证。换句话说：

• 旧版行为：构建 CA 列表 → 用它验证 → 通过；
• 2.1.304 行为：构建 CA 列表 → 日志显示构建成功 → 验证时没用上→ 报颁发者找不到。

判定方法：如果--debug里 CA 加载行全部正常、配置与 2.1.303 完全一致、仅版本不同导致失败——命中回归，直接跳到第三节的处置；如果--debug显示你的 CA根本没被加载（extraCertsPath路径错、系统存储里没有你的根），那是配置问题，先修配置（把网关根证书追加进NODE_EXTRA_CA_CERTS指向的 PEM 文件），别急着回滚版本。

🛠️ 三、处置分级：从止损到等待修复

✅ 处置一（推荐，立刻可用）：回退 2.1.303 并锁版本

社区验证过的止损组合：

claudeinstall2.1.303

然后在 settings 里关掉自动更新，防止被拉回新版：

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

改完用claude doctor自检，应显示自动更新为「已按环境变量禁用」。两点注意：

• 别只回滚不锁版本——自动更新会把 2.1.304 拉回来，故障复现；
• 回退前记录你当前的CLAUDE_CODE_CERT_STORE/NODE_EXTRA_CA_CERTS配置，回滚后原样保留，2.1.303 用同一套配置即可恢复。

🔧 处置二（并行尝试）：换证书信任路径

如果业务不允许降版本，可同时试两条路（不同环境命中率不同，均来自官方公开讨论，非保证修复）：

• 把网关完整证书链（根 + 中间）合并成一个 PEM，通过NODE_EXTRA_CA_CERTS指向它；
• 确认网关发送了完整中间链——部分网关只发叶子证书，让客户端自己找中间证书，在 2.1.304 的新校验路径下更容易断链。这一条要网管配合查网关配置。

⏳ 处置三：跟进官方修复

该问题在官方仓库处于 open 状态、持续有人跟帖确认 2.1.306/2.1.307 未修，Claude Desktop 的 Code 标签页也被报告同样受影响。修复落地后记得先删掉DISABLE_AUTOUPDATER再升级，并在你自己的网关环境实测一轮再放开全员。

💡 四、升级止损的两个习惯，比这次故障更值钱

第一，锁定关键环境的自动更新。编排类 CLI 工具默认自动更新意味着「某个清晨所有人同时换版本」——企业网关、CI 流水线这类依赖私有 CA 的环境，永远应该晚几个版本再跟。DISABLE_AUTOUPDATER一个环境变量，换的是变更主动权。

第二，把--debug的 CA 加载清单纳入排错第一现场。这次故障里最有诊断价值的信息全在CA certs:那几行：加载了几张、丢弃了哪张、为什么丢。以后遇到任何「连不上 API」类报错，先抓这段输出，能省掉大半盲目试错。

⚠️说明：本文基于 2026-10-20 至 10-22 官方仓库公开讨论整理，版本行为、修复进度都可能随新版本变化；请以官方文档与仓库最新状态为准自行核实。本文只做故障判定与处置方法整理，不涉及任何代理服务或工具的推荐；文中所有环境操作（回滚版本、修改信任存储、调整网关配置）请在企业变更流程内，先与网管确认变更流程再进行。

⚓️ 相关链接 ⚓️

• XiaoqiangClub
• Claude Code 官方文档：设置与环境变量
• Claude Code 官方文档：企业托管策略
• 官方仓库 issue：2.1.304 私有 CA 网关证书验证回归（含 debug 日志样例与社区处置）