Mac 在 SWG 下的 Homebrew、Docker、Python 与 Node.js CA 信任配置
解析为何 Homebrew、Docker Desktop、Node.js、Python、git 和 curl 在 macOS 上会拒绝 SWG 签发的 TLS 证书,以及如何权衡 CA 证书包配置与 SWG 绕过。
SWG bar · 更新日期
在启用 HTTPS Break-and-Inspect 解密检查的公司 Mac 上,各类开发运行时验证 TLS 证书的方式各不相同。Safari 和 Chrome 会查询 macOS 钥匙串,而命令行工具和容器却经常依赖各自独立的 CA 证书包——从而导致包管理器与 SDK 频繁报错中断。
为什么不同 Mac 开发工具会选择性失败
| 工具 / 运行时 | macOS 上的默认信任库 | 常见环境变量或配置项 |
|---|---|---|
| Node.js / npm / yarn / pnpm | 编译内置的 Mozilla CA 证书包 | NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pem |
| Python / pip / uv / requests | certifi 证书包或 OpenSSL CA 路径 |
SSL_CERT_FILE / REQUESTS_CA_BUNDLE |
| git | 视构建方式而定,使用 OpenSSL 或 Secure Transport | git config --global http.sslCAInfo /path/to/corp-ca.pem |
curl / Homebrew (brew) |
macOS Secure Transport 或 OpenSSL CA 证书包 | HOMEBREW_CURLRC / CURL_CA_BUNDLE(可执行 curl --version 核查) |
| Docker Desktop / 容器 | Linux 虚拟机与镜像内的 /etc/ssl/certs(而非 macOS 钥匙串) |
将企业 CA 添加到 Docker 虚拟机或镜像信任库 |
1. 先定位具体是哪个仓库或 API 主机名遭到拦截
在修改 Shell 配置文件或容器构建脚本之前,请先确认究竟是哪些外部主机名正在接受 SSL 检查,而非因 DNS 或防火墙阻断导致失败:
swgbar domains list --status confirmed
swgbar probe registry.npmjs.org
swgbar probe pypi.org
swgbar probe ghcr.io
请注意,包管理器在下载过程中经常会跳转到多个不同的主机(例如 formulae.brew.sh → ghcr.io,或 github.com → objects.githubusercontent.com)。请参阅为多域名 Web 应用、SSO、CDN 与 API 配置 SWG 绕过。
2. 在 CA 证书包配置、TLS 例外与 SWG 绕过之间做出选择
- 附加企业根 CA PEM:当企业策略要求所有流量必须经由 SWG 解密审计时,从 SWG bar → 证书中确认对应的根证书,并按照 IT 安全指引导出 PEM 文件,配置
NODE_EXTRA_CA_CERTS、SSL_CERT_FILE、REQUESTS_CA_BUNDLE或http.sslCAInfo。切勿直接关闭 TLS 校验(如设置NODE_TLS_REJECT_UNAUTHORIZED=0或sslVerify=false)。 - 申请 IT TLS 解密例外:对于公共软件源、Docker 基础镜像或强制启用证书固定的工具,在 CI 与本地设备间长期维护自定义 CA 证书包往往十分脆弱,建议由管理员在网关配置不解密例外。
- 在获授权网络中使用单域名 SWG 绕过:如果你自行管理该网络或已获准对特定主机开启绕过,可在 SWG bar 中开启绕过 SWG(或运行
swgbar bypass enable <domain>),随后重启对应 CLI 进程。
修改系统默认设置前的对照排查
如需逐步排查 CERTIFICATE_VERIFY_FAILED 报错,请阅读修复 Mac 终端 CLI 与 AI 工具中的 SWG TLS/SSL 证书错误。如需对比本地路由规则与网关策略排除方案,请参阅SWG 绕过与 TLS 解密例外对比。