修復 Mac 終端機 CLI 與 AI 工具中的 SWG TLS/SSL 憑證錯誤

排解並修復 macOS 在企業 SWG 環境下 git、npm、Python、Claude Code 與 Cursor 出現的 CERTIFICATE_VERIFY_FAILED 與本機簽發者憑證錯誤。

SWG bar · 更新日期

當公司 Mac 位於執行 **HTTPS/SSL 解密檢查(Break-and-Inspect)**的安全 Web 閘道(SWG)之後時,Safari 與 Chrome 往往能正常載入網頁而不顯示警告,但終端機工具與 AI 程式設計助理卻會因 TLS 交握失敗而報錯,常見錯誤包括 SSL: CERTIFICATE_VERIFY_FAILED、UNABLE_TO_GET_ISSUER_CERT_LOCALLY 或 SSL certificate problem: unable to get local issuer certificate。

產生這種差異的原因在於:瀏覽器會查詢 macOS 鑰匙圈(Keychain)——企業 MDM 可以在其中安裝組織的檢查根憑證(Root CA);而許多命令列執行環境(git、curl、Node.js/npm、Python/pip)以及 AI 工具(Claude Code、Cursor、MCP 伺服器)預設則是依據各自內建的公開 CA 憑證庫來驗證伺服器憑證。

1. 確認是哪個主機名稱正在接受 HTTPS 檢查

在修改環境變數或網路設定之前,請先確認失敗端點的憑證鏈在你的 Mac 上是否確實被替換:

  1. 在執行 macOS 14 或以上版本(Apple 晶片)的 Mac 上安裝並開啟 SWG bar。
  2. 執行一次失敗的指令,接著檢查 SWG bar → 網域,或直接使用內建的 CLI 從終端機探測該端點:
/Applications/SWGBar.app/Contents/MacOS/swgbar probe registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar domains detail registry.npmjs.org
  1. 檢查該網域的分類與根憑證(Root CA)。請留意,Web 前端、身分驗證伺服器、套件註冊中心與大型語言模型 API 端點經常使用不同的主機名稱——某個子網域可能直接放行,而另一個子網域則正在被解密。

如果你使用相容 MCP 的 AI 助理,也可以連線 SWG bar 內建的 MCP 伺服器,讓你的 AI 用戶端直接查詢已觀測網域與憑證鏈。

2. 選擇適合你環境的修復方式

確認是由檢查根憑證簽署目標主機名稱的憑證後,請依照網路政策與授權範圍,從以下三種方式中擇一處理:

處理方式 運作機制 最適用情境
為工具設定 CA 憑證信任 將執行環境變數(例如 NODE_EXTRA_CA_CERTS、SSL_CERT_FILE 或 REQUESTS_CA_BUNDLE)指向包含企業根憑證的匯出 PEM 憑證檔。 公司政策規定必須走受檢查的 SWG 路由,且你信任該 CA 用於特定工具。
申請管理員設定 TLS 解密例外 由 IT 在閘道器上將該 API 或套件庫主機名稱排除於 HTTPS 解密之外,同時保留閘道器路由。 啟用憑證固定的工具或團隊共用的開發端點在 Break-and-Inspect 下無法運作。
在 SWG bar 啟用單網域 SWG 繞過 透過選單列、CLI 或 MCP 在 macOS 上讓選取的主機名稱不經閘道器 HTTPS 解密連線。 你管理該網路,或已獲授權在 Mac 上針對特定網域測試未受檢查的路由。

如需詳細比較閘道器例外與路由變更的架構差異,請閱讀 SWG 繞過與 TLS 解密例外對比。

3. 在獲授權時於 macOS 上繞過受檢網域

若單網域繞過適合你的網路環境,你可以從選單列(SWG bar → 網域 → 繞過 SWG → 開啟)或在終端機中針對確切的 API 或套件庫主機名稱啟用繞過:

/Applications/SWGBar.app/Contents/MacOS/swgbar bypass enable registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar bypass status

等待狀態顯示為繞過中(CLI 輸出 bypassing)後,重新啟動 CLI 指令、背景常駐程式或 IDE 擴充功能主機程序,讓既有連線關閉並透過新規則重新連線。首次使用時的 macOS 網路擴充功能核准、重新啟動恢復行為,以及完成後如何關閉繞過,請參閱如何在 Mac 上繞過 SWG。

留意平台與網路邊界

  • 以單一主機名稱為範圍:繞過 example.com 不會自動涵蓋 api.example.com 或 auth.example.com。請逐一確認工具連線的每個主機名稱。
  • 平台與網路需求:SWG bar 2.4.12 需要執行 macOS 14+ 的 Apple 晶片 Mac,以及透過實體網路介面建立的可用 IPv4 路徑。若防火牆封鎖直接對外連線,或工具本身強制使用明確代理伺服器,請停用繞過規則,改用管理員 TLS 例外或設定 CA 憑證套件。
  • 以最新證據驗證:每次變更後,請使用 HTTPS 與 SSL 檢查指南重新執行檢查,而不要依賴快取結果。