Source: https://swgbar.com/zh-TW/guides/homebrew-docker-python-node-ca-trust-swg-macos/
Language: zh-TW

# Mac 在 SWG 下的 Homebrew、Docker、Python 與 Node.js CA 信任設定

瞭解為何 Homebrew、Docker Desktop、Node.js、Python、git 與 curl 在 macOS 上會拒絕 SWG 簽署的 TLS 憑證，以及如何權衡 CA 憑證套件設定與 SWG 繞過。

SWG bar · 更新日期 2026年11月18日

在實施 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 繞過](<https://swgbar.com/zh-TW/guides/multi-domain-sso-api-cdn-swg-bypass/>)。

## 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 憑證錯誤](<https://swgbar.com/zh-TW/guides/swg-tls-certificate-errors-macos/>)。若想比較本機路由規則與閘道器政策排除項目，請參閱 [SWG 繞過與 TLS 解密例外對比](<https://swgbar.com/zh-TW/guides/swg-bypass-vs-tls-exception/>)。

## 延伸閱讀

*   [如何在 Mac 上繞過 SWG（單網域一鍵繞過與 CLI 指令）](<https://swgbar.com/zh-TW/guides/how-to-bypass-swg/>)
*   [如何在 Mac 上繞過 SSL 檢查（企業 SWG 單網域直連方案）](<https://swgbar.com/zh-TW/guides/bypass-ssl-inspection-mac/>)
*   [如何在 macOS 上繞過 HTTPS 與 TLS 檢查（Break-and-Inspect 指南）](<https://swgbar.com/zh-TW/guides/bypass-https-tls-inspection-mac/>)
*   [如何在 Mac 上繞過企業代理伺服器與 SWG SSL 檢查](<https://swgbar.com/zh-TW/guides/bypass-corporate-proxy-ssl-inspection-mac/>)
*   [如何判斷 Mac 是否被 SWG 劫持（偵測 HTTPS 與 SSL 檢查）](<https://swgbar.com/zh-TW/guides/detect-https-inspection/>)
*   [如何檢查公司或工作用 Mac 是否正在攔截 HTTPS（SSL 檢查）](<https://swgbar.com/zh-TW/guides/check-if-work-mac-intercepting-https/>)
*   [Mac 專用 SSL 檢查偵測工具：在選單列即時發現 HTTPS 攔截](<https://swgbar.com/zh-TW/guides/ssl-inspection-checker-mac/>)
*   [Mac 上的 Zscaler SSL 檢查：如何偵測並按網域繞過](<https://swgbar.com/zh-TW/guides/zscaler-ssl-inspection-bypass-mac/>)
*   [Mac 上的 Netskope SSL 檢查：偵測解密與單網域繞過指南](<https://swgbar.com/zh-TW/guides/netskope-ssl-inspection-bypass-mac/>)
*   [Mac 上的 Cloudflare WARP 與 Zero Trust TLS 檢查：偵測與繞過](<https://swgbar.com/zh-TW/guides/cloudflare-warp-tls-inspection-mac/>)
*   [SWG bar 中的「已確認」與「疑似」HTTPS 檢查狀態解析](<https://swgbar.com/zh-TW/guides/confirmed-vs-suspected-https-inspection/>)
*   [在 SWG bar 中檢查中間人根憑證與核發機構](<https://swgbar.com/zh-TW/guides/inspect-mitm-root-certificates-macos/>)
*   [Mac 上的企業 SWG 與 MDM HTTPS 解密檢查解析](<https://swgbar.com/zh-TW/guides/enterprise-swg-https-inspection-macos/>)
*   [SWG 繞過與 TLS 解密例外（Break-and-Inspect）對比](<https://swgbar.com/zh-TW/guides/swg-bypass-vs-tls-exception/>)
*   [在 Mac 上為多網域 Web 應用、SSO、CDN 與 API 設定 SWG 繞過](<https://swgbar.com/zh-TW/guides/multi-domain-sso-api-cdn-swg-bypass/>)
*   [排解 Mac 上 SWG 繞過的「恢復中」「已暫停」與連線錯誤](<https://swgbar.com/zh-TW/guides/troubleshoot-swg-bypass-recovering-paused-macos/>)
*   [macOS VPN 虛擬介面與 SWG HTTPS 檢查比較](<https://swgbar.com/zh-TW/guides/macos-vpn-virtual-interface-vs-swg-inspection/>)
*   [為什麼憑證固定（Pinning）應用與 mTLS 在 SWG 檢查下會中斷](<https://swgbar.com/zh-TW/guides/certificate-pinning-mtls-swg-inspection-macos/>)
*   [修復 Mac 終端機 CLI 與 AI 工具中的 SWG TLS/SSL 憑證錯誤](<https://swgbar.com/zh-TW/guides/swg-tls-certificate-errors-macos/>)
*   [修復 Mac 上 Claude Code 與 Cursor 的 'unable to get local issuer certificate' 錯誤（SWG 與 MCP）](<https://swgbar.com/zh-TW/guides/ai-coding-agents-claude-code-cursor-swg-macos/>)
*   [在 Mac 上使用 openssl 與 security verify-cert 驗證 TLS 憑證](<https://swgbar.com/zh-TW/guides/verify-tls-certificates-openssl-security-verify-cert-macos/>)
*   [SWG bar 權限、本機隱私與 TLS 探測上限說明](<https://swgbar.com/zh-TW/guides/macos-network-extension-privacy-probe-limits/>)
*   [SWG bar 如何檢查 HTTPS 解密](<https://swgbar.com/zh-TW/how-it-works/>)
*   [下載並安裝 Mac 版 SWG bar（macOS 14+）](<https://swgbar.com/zh-TW/install/>)
*   [偵測 SSL 與 HTTPS 檢查的 Chrome 擴充功能（SWG bar 配套外掛）](<https://swgbar.com/zh-TW/chrome-extension/>)
*   [SWG bar CLI 使用指南](<https://swgbar.com/zh-TW/cli/>)
*   [SWG bar MCP 使用指南](<https://swgbar.com/zh-TW/mcp/>)
*   [SWG bar 版本資訊](<https://swgbar.com/zh-TW/releases/>)
*   [關於 SWG bar](<https://swgbar.com/zh-TW/about/>)
