【Claude Code】SSL certificate verification 证书验证失败排查与自定义 CA 配置指南
文章目录
- 一、问题描述
- 1.1 环境信息
- 1.2 报错现象
- 二、根因分析
- 2.1 错误链路追踪
- 2.2 可能原因列举
- 三、解决方案
- 方案一：配置 NODE_EXTRA_CA_CERTS 加载自定义 CA（推荐）
- 方案二：联合使用 NODE_EXTRA_CA_CERTS 与代理配置
- 四、重要：禁止的做法
- 不要设置 NODE_TLS_REJECT_UNAUTHORIZED=0
- 五、验证与回归测试
- 六、总结与预防
- 6.1 核心要点
- 6.2 最佳实践建议
- 七、参考资料
一、问题描述
1.1 环境信息
| 项目 | 说明 |
|---|---|
| 工具名称 | Claude Code |
| 错误类别 | TLS/SSL 证书验证错误 |
| 涉及证书 | 企业代理或安全设备自签名证书 |
| 影响范围 | 所有 HTTPS 请求（API 调用） |
| 网络环境特征 | 存在透明代理、SSL 解密设备、企业 CA 的环境 |
| 适用平台 | Windows / macOS / Linux |
1.2 报错现象
Claude Code 启动后，首次调用 Anthropic API 时终端输出以下错误之一并中止运行：
Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certifi