Windows 上讓 npm 與 pnpm 走 Clash：環境變數與分流規則完整步驟（2026）

1. 典型症狀與搜尋意圖：為什麼瀏覽器正常、終端機卻失敗

許多開發者在 Windows 上已安裝圖形版 Clash 客戶端，也習慣用「系統代理」或 TUN 讓瀏覽器順利開啟海外網站。然而 Node 生態的套件管理器 往往仍透過 終端機行程 直接發起 HTTPS 連線到 registry.npmjs.org、github.com 或 tarball CDN，這些行程不一定會自動繼承你在 Clash 介面裡勾選的「系統代理」行為，尤其當你混用 PowerShell 7、Windows Terminal、Git Bash 等不同 Shell 時，環境變數是否繼承、是否被 CI 腳本覆寫，都會造成「同一台電腦、同一條網路，卻只有 npm 失敗」的錯覺。

另一個高頻情境是：你把 registry 指到 淘寶／npmmirror 鏡像以加速下載，但 lockfile 或某些依賴仍會去抓 官方 tarball URL；若此時 Clash 規則 把鏡像與官方源拆成不同出口，或其中一條路徑沒有穩定代理，就會出現 部分套件成功、部分卡在 fetch 的現象。使用者真正想解的是：單一、可重現的出口策略——國內可快取的走直連，海外 registry 與 Git 走代理，並且npm 與 pnpm 兩邊行為一致。

2. npm／pnpm 實際讀取的設定層：環境變數與 npm config

npm 會綜合讀取 使用者與專案層級 的 .npmrc、全域設定，以及執行當下的 環境變數。其中與代理最相關的包含 HTTP_PROXY、HTTPS_PROXY（以及部分工具會看的 ALL_PROXY），還有透過 npm config set proxy 寫入的 proxy／https-proxy 鍵值。若這兩層互相矛盾，常見結果是：同一指令在 A 終端成功、在 B 終端失敗，因為其中一個 Shell 多帶了舊的 HTTP_PROXY。

pnpm 同樣尊重 Node 生態慣例，並會讀取自身與 npm 相容的設定檔；團隊若同時使用 pnpm-workspace.yaml 與根目錄 .npmrc，還要注意 registry 與 shamefully-hoist 等選項 是否讓依賴解析路徑與 npm 時期不同。實務上建議先用 npm config list 與 pnpm config list 做一次棚卸，確認目前生效的 registry、proxy 相關鍵 與 strict-ssl，再調整 Clash 規則；否則會變成在代理與直連之間來回打轉。

3. Shell 端：HTTP_PROXY、HTTPS_PROXY 與大小寫變體

在 Windows 上，最單刀直入的方式是在你每日使用的 Shell 裡，把代理指到本機 Clash 的 mixed-port（常見為 7890，實際請以你的設定為準）。格式通常為 http://127.0.0.1:PORT：Clash 會在該埠提供 HTTP CONNECT，讓 HTTPS 請求也能被轉發。若你只設 HTTP_PROXY 而沒設 HTTPS_PROXY，部分工具仍會嘗試直連 443，導致症狀像「HTTP 小測試成功、npm 仍失敗」。

有些文件會同時提到小寫的 http_proxy；在跨平台腳本裡，最穩健的習慣是兩組都寫，或在團隊文件中明定「以 PowerShell 為唯一標準 Shell」，避免新人從網路複製了 bash 語法卻貼在 cmd 裡。若你使用 企業內網 PAC 或公司根憑證，還要另外處理 TLS 驗證 與 Clash 的 MITM／Sniffer 邊界，本篇假設為一般開發者本機情境，以 標準憑證鏈 為主。

# Session-only proxy env for current PowerShell window
$env:HTTP_PROXY  = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:NO_PROXY    = "localhost,127.0.0.1,::1,registry.npmmirror.com,*.npmmirror.com"
pnpm install

若你希望「開啟某個終端機設定檔就自動帶入」，可把上述寫進 PowerShell Profile，但要留意：長期全域啟用代理，可能讓內網 API、本機 Docker、公司 VPN 子網也誤入 Clash。此時就更依賴下一節的 NO_PROXY 設計與 Clash 規則中的 DIRECT 條目。

4. NO_PROXY：讓國內 registry 與內網服務不要繞代理

NO_PROXY（或 no_proxy）的設計目的，是列出「應該略過 HTTP 代理、直接連線」的主機名、網域後綴或 IP。對於已將 registry 設為 https://registry.npmmirror.com 這類境內鏡像的使用者，把該主機與相關 CDN 後綴放進 NO_PROXY，可避免流量先繞進 Clash 再出去，減少延遲與不必要的策略組切換。相對地，registry.npmjs.org、npm.pkg.github.com 等海外節點通常應不要出現在 NO_PROXY，才會走你為海外流量準備的代理策略。

實務上常見錯誤是 NO_PROXY 寫了過寬的萬用字元，或漏掉公司內部 Verdaccio／JFrog 的主機名，導致內部套件庫反而被送去公開節點。建議與團隊共用一份「允許直連清單」，並在 README 註明：哪些網域必須直連、哪些必須代理，與 Clash 規則中的 DOMAIN／DOMAIN-SUFFIX 條目彼此對照，避免「環境變數說直連、Clash 卻把封包轉去節點」的打架情形。

5. registry 與 lockfile：避免鏡像與官方源混用

即使你在 .npmrc 把 registry 指到鏡像，舊的 lockfile 或某些 scoped package 仍可能指向官方 tarball。若此時 Clash 對鏡像網域設了 DIRECT、對 registry.npmjs.org 設了 REJECT 或走不穩定的自動選線，整體安裝仍會失敗。較穩健的流程是：先決定團隊唯一的 registry 政策，再讓代理與規則服務該政策，而不是反過來用代理「硬修」一個混亂的 registry 組合。

對 pnpm 使用者，若採用全域 store 與硬連結策略，也要確認不同專案之間是否曾用不同 registry 解析同一套件名稱；切換 registry 後，建議在問題專案執行清理快取與重新解析的指令（依團隊規範），並用 Clash 連線日誌確認實際連到的主機是否與預期一致。

6. Clash 分流規則順序與範例（直連鏡像、代理 npmjs）

Clash（含 mihomo 系核心）在匹配規則時，通常依由上而下的第一個命中決定策略。若要「境內鏡像直連、海外 registry 走代理」，請把更精確、更應優先例外化的條目放在前面。常見寫法包含 DOMAIN-SUFFIX 針對 npmmirror.com、針對公司內網後綴的 DIRECT，後面再放 registry.npmjs.org 與 github.com 等走你為開發者準備的 策略組。

下列片段僅為結構示意，實際鍵名、縮排與策略組名稱請依你的訂閱與 GUI 匯出的格式調整；重點是順序與意圖，而不是複製後不加修改就套用。

# Example only — adjust policy group names to match your profile
rules:
  - DOMAIN-SUFFIX,npmmirror.com,DIRECT
  - DOMAIN-SUFFIX,company.internal,DIRECT
  - DOMAIN-SUFFIX,registry.npmjs.org,🔰 Dev-Proxy
  - DOMAIN-SUFFIX,npm.pkg.github.com,🔰 Dev-Proxy
  - DOMAIN-SUFFIX,github.com,🔰 Dev-Proxy

若你同時使用 Fake-IP 或 Sniffer，請記得：規則匹配的是還原後的網域名稱或 IP，與你在瀏覽器網址列看到的不一定同一層資訊。遇到「規則寫了但日誌顯示仍走 MATCH」時，先用連線日誌確認實際 SNI 與目標 IP，再回頭調整 DOMAIN-KEYWORD 或更精準的 DOMAIN-SUFFIX，避免過寬關鍵字把不相關流量全吸進開發者策略組。

若你的 Clash 設定與訂閱尚未匯入完成，可先參考站內 訂閱匯入教學，把基礎策略組與 DNS 模式穩定後，再回來微調 npm 相關網域。

7. 系統代理、TUN 與純環境變數的邊界

開啟 系統代理後，部分應用程式會自動讀取 Windows 的系統代理設定，但 Node 官方發行的 Windows 二進位在歷史上對「是否繼承系統代理」的行為，曾隨版本與編譯選項而變動；因此不要假設「只要 Clash 開了系統代理，npm 就一定會跟著走」。最可預測的做法仍是：在你要跑 pnpm install 的同一個終端機，明確設定 HTTPS_PROXY，或在 .npmrc 寫入對應 proxy 鍵值並確保沒有舊值殘留。

TUN 模式理論上能在較低層次攔截更多流量，但在開發者機器上常與 公司 VPN、虛擬機、Android 模擬器 互相影響；若你已啟用 TUN，仍建議保留清楚的 NO_PROXY 與 Clash 規則中的 PROCESS／LAN 例外，以免本機回環測試或內網 API 被誤導。與 IDE 內建終端機 相關的網域與 QUIC 行為，可再對照 Cursor 開發者網域分流 一文，把「編輯器更新」與「純 CLI 的 npm」分開思考。

8. 驗證與除錯清單

建議依序確認：① Clash 本機 mixed-port 是否可連、日誌是否出現 CONNECT；② 目前 Shell 的 HTTP_PROXY／HTTPS_PROXY 是否與預期一致（可用 Get-ChildItem Env:HTTP_PROXY 等指令）；③ npm config list 與 pnpm config list 是否出現幽靈 proxy；④ NO_PROXY 是否誤包含了 registry.npmjs.org；⑤ Clash 規則順序是否讓鏡像真的命中 DIRECT。

常見錯誤訊息包含：ECONNRESET、ETIMEDOUT、UNABLE_TO_GET_ISSUER_CERT_LOCALLY（多與公司 SSL 檢查或自簽憑證有關，而非單純代理）。每遇到一類錯誤，先判斷是DNS、TCP 連線、TLS 還是HTTP 層拒絕，再決定要改環境變數、registry，還是調整 Clash 規則與策略組。若你也在 Docker 內跑 npm，請改參考 容器走宿主機 Clash 的路徑，因為 bridge 網路下 127.0.0.1 指向的是容器自己，而不是 Windows 主機。