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 解密例外對比。