Mac 上公司代理证书导致“终端”工具出错

症状

• npm 或 Node 显示“self-signed certificate in certificate chain”或“unable to get local issuer certificate”。
• Git 对 HTTPS 远程仓库显示“SSL certificate problem”。
• Safari 浏览器能打开网站，但 curl 或 Python 不能。
• 错误只在公司网络或 VPN 上出现。

可能的原因

• TLS 检查。代理会把网站的证书替换为由公司根证书签名的证书。
• 各自独立的信任存储。Safari 浏览器使用 macOS 钥匙串，而许多命令行工具使用自己的受信任证书列表。
• 缺少代理设置。“终端”中的工具并不总是使用系统代理，它们需要代理环境变量或自己的设置。

如何检查

1. 显示服务器发送的证书链，查看最顶层证书的颁发者。

   openssl s_client -connect registry.npmjs.org:443 -servername registry.npmjs.org -showcerts </dev/null

2. 用 curl 显示 TLS 握手过程。

   curl -v https://registry.npmjs.org/ -o /dev/null

3. 在“钥匙串访问”中找到公司根证书：在“系统”钥匙串中搜索公司名称。

4. 显示 shell 中的代理环境变量。

   env | grep -i proxy

如何修复

1. 向 IT 团队索取 PEM 格式的公司根证书文件。不要信任来源不明的证书。

2. 对于 Node.js 工具，用 NODE_EXTRA_CA_CERTS 指定该文件。设置后重新启动工具。

   export NODE_EXTRA_CA_CERTS=~/certs/company-root.pem

3. 在 Node.js 22.19、24.6 或更高版本中，可以直接使用钥匙串信任的证书。

   export NODE_USE_SYSTEM_CA=1

4. 为 npm 设置证书文件。

   npm config set cafile ~/certs/company-root.pem

5. 为 Git 设置证书文件。

   git config --global http.sslCAInfo ~/certs/company-root.pem

6. 对于 curl，用 --cacert 指定该文件。

   curl --cacert ~/certs/company-root.pem https://example.com

7. 如果 IT 团队使用公司代理，请为“终端”工具设置该代理。

   export https_proxy=http://proxy.example.com:8080

8. 不要关闭证书检查，例如 strict-ssl 或 http.sslVerify。这会让连接变得不安全。

使用 Kilobat

常见问题

参考资料

• Node.js：Command-line API、NODE_EXTRA_CA_CERTS 和 --use-system-ca
• npm Docs：config（cafile、proxy、https-proxy、strict-ssl）
• git-config(1)、http.sslCAInfo 和 http.proxy，macOS 27.2 自带的 man 手册页（Git 2.56）
• Apple 支持：在“钥匙串访问”中更改证书的信任设置
• curl(1)，macOS 27.2 自带的 man 手册页

参考资料核查于 2026年10月29日。man 手册页为 macOS 自带版本；在“终端”中用 man <name> 打开。

相关指南