Source: https://swgbar.com/zh-TW/guides/swg-tls-certificate-errors-macos/
Language: zh-TW

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

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

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

當公司 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](<https://swgbar.com/zh-TW/install/>)。
2.  執行一次失敗的指令，接著檢查 **SWG bar → 網域**，或直接使用內建的 [CLI](<https://swgbar.com/zh-TW/cli/>) 從終端機探測該端點：

```
/Applications/SWGBar.app/Contents/MacOS/swgbar probe registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar domains detail registry.npmjs.org
```

3.  檢查該網域的分類與根憑證（Root CA）。請留意，Web 前端、身分驗證伺服器、套件註冊中心與大型語言模型 API 端點經常使用不同的主機名稱——某個子網域可能直接放行，而另一個子網域則正在被解密。

如果你使用相容 MCP 的 AI 助理，也可以連線 [SWG bar 內建的 MCP 伺服器](<https://swgbar.com/zh-TW/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 解密例外對比](<https://swgbar.com/zh-TW/guides/swg-bypass-vs-tls-exception/>)。

## 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](<https://swgbar.com/zh-TW/guides/how-to-bypass-swg/>)。

## 留意平台與網路邊界

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

## 延伸閱讀

*   [如何在 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 在 SWG 下的 Homebrew、Docker、Python 與 Node.js CA 信任設定](<https://swgbar.com/zh-TW/guides/homebrew-docker-python-node-ca-trust-swg-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/>)
