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 鑰匙圈,但 CLI 工具與容器經常使用各自的 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 繞過:當你管理該網路或已獲授權在 Mac 上為特定主機啟用繞過時,可在 SWG bar 中啟用繞過 SWG(或執行
swgbar bypass enable <domain>)並重新啟動該 CLI 程序。
變更系統預設值前的交叉對照
如需逐步排解 CERTIFICATE_VERIFY_FAILED 問題,請閱讀修復 Mac 終端機 CLI 與 AI 工具中的 SWG TLS/SSL 憑證錯誤。若想比較本機路由規則與閘道器政策排除項目,請參閱 SWG 繞過與 TLS 解密例外對比。