一、先判斷 npm 逾時:不一定是 Node.js 或套件本身出錯
當你執行 npm install 時,若畫面長時間停在 idealTree、fetch、reify,最後出現 ETIMEDOUT、ECONNRESET、EAI_AGAIN 或 network request failed,先不要急著刪除 node_modules、重裝 Node.js,甚至重新建立整個專案。這類訊息通常只表示 npm 在某個網路階段沒有等到預期回應,真正原因可能是套件註冊表無法連線、依賴套件的下載網域沒有走代理、DNS 回應不穩,或 Clash 處於與終端機不一致的代理模式。
要先分清楚「套件不存在」與「請求根本沒有完成」:如果 npm 回傳 404 Not Found、No matching version found,多半是套件名稱、版本或註冊表設定問題;如果錯誤停在數十秒後才出現,且換一個節點、換網路或開啟 Clash 後結果不同,才比較像是代理路徑或連線品質問題。另外,專案若使用私有註冊表、Git 依賴、GitHub Release 或企業內部套件庫,npm 實際連線的主機可能不只一個,不能只測試單一網址就下結論。
二、先確認 npm 的註冊表與實際下載目標
npm 預設會從 registry.npmjs.org 取得套件 metadata,但安裝過程可能還會依照套件資訊前往其他主機下載壓縮檔或二進位檔。例如某些套件會使用 GitHub、GitHub Releases、外部 CDN,原生模組也可能在安裝腳本裡下載對應平台的預編譯檔。因此,瀏覽器能開啟 npm 官網,不代表終端機執行安裝時的每一個連線都已經被 Clash 正確處理。
先在終端機檢查 npm 目前使用的註冊表,不要只看專案文件或其他人的截圖。可使用以下指令:
npm config get registry
npm config get proxy
npm config get https-proxy
npm config list
正常情況下,公開套件可使用 https://registry.npmjs.org/;若公司或團隊指定了內部鏡像,則應保留管理員提供的網址,不要任意改回公開註冊表。特別要注意全域設定與專案目錄中的 .npmrc 可能同時存在,後者會覆蓋部分前者。Windows 使用者也應檢查使用者目錄下的 .npmrc,macOS 與 Linux 則可檢查家目錄中的同名檔案。
如果你曾經設定過失效的舊代理,npm 可能仍然嘗試連往已關閉的本機埠。此時可以先查看設定來源,再決定是否清除:
npm config delete proxy
npm config delete https-proxy
這兩個指令只會移除 npm 自己保存的代理欄位,不會關閉 Clash,也不會改變作業系統代理。若你準備改由 Clash 的系統代理、環境變數或 TUN 接管流量,清除過時的 npm 代理通常能避免「代理套代理」造成的重複轉發。若公司要求 npm 必須使用指定 HTTP Proxy,則不要直接刪除設定,應先向管理員確認正確的主機、埠號與驗證方式。
三、在 Clash 裡確認節點、模式與規則命中
確認 npm 設定沒有明顯錯誤後,再回到 Clash 查看連線紀錄。最有價值的不是盲目切換十幾個節點,而是執行一次最小化測試,同時觀察 registry.npmjs.org、套件下載網址以及可能出現的 GitHub 主機是否有新連線。若紀錄中完全沒有這些請求,問題可能是終端機沒有使用系統代理、npm 使用了另一個代理設定,或目前啟用的模式沒有接管該行程。
在規則模式下,先確認請求實際命中的策略群組。若你使用的是「規則」模式,npm 相關流量可能被某條更前面的 GEOIP、MATCH 或自訂規則送往 DIRECT。不要只把 npmjs.org 加入代理就結束,還要看紀錄中的完整主機名稱。若專案依賴來自 GitHub,可能需要另外檢查 github.com、api.github.com、objects.githubusercontent.com 或實際顯示的 CDN 網域。
可以用較窄的規則先做驗證,群組名稱請替換成你設定檔中真實存在的名稱:
# Example rules snippet — replace NPM_PROXY with your real policy group
rules:
- DOMAIN,registry.npmjs.org,NPM_PROXY
- DOMAIN-SUFFIX,npmjs.org,NPM_PROXY
- DOMAIN-SUFFIX,github.com,NPM_PROXY
- DOMAIN,api.github.com,NPM_PROXY
# Add download hosts observed in Clash logs.
- MATCH,DIRECT
這段只是排錯示意,不建議未經核對就直接套用到生產設定。DOMAIN-SUFFIX,github.com 的涵蓋範圍比單一主機廣,若公司希望 GitHub 內部資源直連,應拆成更精確的規則。規則順序也很重要:同一個網域若先被其他規則匹配,後面新增的代理規則不會生效。測試期間可在 Clash 介面中切換一個延遲較低且穩定的節點,再重新執行安裝,並記錄「節點、模式、命中策略、錯誤訊息」四項結果,之後才容易比較。
四、動手測試:讓終端機與 Clash 使用同一條路徑
這一節建議先用最小測試,不要立刻跑完整專案安裝。假設 Clash 的混合埠是本機的 7890,可以先明確指定代理,測試 DNS 解析與 HTTPS 請求是否有回應:
curl -I --proxy http://127.0.0.1:7890 https://registry.npmjs.org/
npm view lodash version --registry=https://registry.npmjs.org/
如果第一個指令能收到 HTTP 回應,但第二個 npm 指令仍逾時,代表 npm 可能受到自己的代理欄位、憑證設定或專案註冊表影響;如果兩個都失敗,請回到 Clash 紀錄檢查本機監聽埠、節點狀態與規則命中。Windows PowerShell、macOS 與 Linux 的環境變數寫法略有不同,但概念都是讓啟動 npm 的那個終端機知道代理位置:
# macOS / Linux
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
npm view lodash version
# Windows PowerShell
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
npm view lodash version
這些環境變數只影響目前的終端機工作階段,關閉視窗後通常就會失效。若測試成功,表示 npm 能透過明確的 HTTP 代理工作,但你平常啟動的 shell、IDE 內建終端機或背景腳本沒有繼承同樣的設定。此時應檢查 IDE 是從哪個環境啟動、專案腳本是否清除了代理變數,以及是否同時存在不同版本的 Node.js 與 npm。
若工具鏈不接受 HTTP 代理而只支援 SOCKS,請確認 Clash 的 SOCKS 埠與協定格式;不要把 SOCKS 埠誤填成 HTTP 混合埠。某些 npm 相依套件的安裝腳本還會自行呼叫 curl、git 或作業系統下載器,這些程式不一定讀取 npm 的所有設定,因此應分別測試 git ls-remote、curl 與 npm,而不是只測一個命令。
五、DNS、TUN 與快取:為什麼「看得到網域」仍可能連不上
npm 逾時不全是節點問題。當 DNS 解析結果不穩、解析請求走了與 HTTPS 不同的出口,或本機網路攔截了某些回應時,終端機可能先花很久等待解析,最後才顯示模糊的網路錯誤。你可以先使用 nslookup 或 dig 查詢註冊表主機,並在 Clash 的 DNS 設定與連線紀錄中觀察請求是否符合預期:
nslookup registry.npmjs.org
dig registry.npmjs.org
npm cache verify
若瀏覽器與 npm 的解析結果差異很大,可暫時在 Clash 中使用較穩定的 DNS 策略,並清除已確認損壞的本機 DNS 快取後重試。不要因為一次解析失敗,就把所有 DNS 請求永久導向同一個遠端服務;企業內網、私有註冊表與本機開發域名可能需要保留直連或內部 DNS。設定修改後應以實際紀錄驗證,不要只看介面上的「DNS 已啟用」。
如果 npm、Git、IDE 外掛與其他不讀系統代理的程式都需要遵守同一套規則,TUN 往往比逐一設定環境變數更完整。它會把較多系統流量交給 Clash 核心處理,但同時可能與公司 VPN、零信任軟體、虛擬機網路或其他網路過濾器衝突。啟用 TUN 前,請先記下目前的路由與代理設定,準備好關閉 TUN、恢復原生網路的步驟;如果只想修復 npm,優先使用明確的 HTTP 代理或環境變數,通常比較容易控制影響範圍。
六、安裝重試與快取處理:最後才清理,不要一開始就破壞現場
當代理路徑已確認可用,仍然偶發下載中斷時,才檢查 npm 的重試、逾時與快取設定。適度提高網路逾時可以改善節點延遲較高的環境,但它不能修復錯誤的規則或無法連線的代理;把逾時調得過大,反而會讓每次失敗都等待更久。可先查看目前設定:
npm config get fetch-timeout
npm config get fetch-retries
npm cache verify
確認網路正常後,再以小範圍方式重試,例如先安裝單一套件、使用鎖定檔重新執行,並保留完整輸出。若只有某個套件失敗,查看該套件的安裝腳本與下載來源;若所有套件都失敗,回到註冊表、代理與 DNS,而不是反覆清理快取。只有在 npm cache verify 顯示快取確實損壞,或錯誤明確指向本機快取內容時,才考慮清理,並先確認團隊是否需要保留離線安裝資料。
相比只在瀏覽器中切換代理的工具,Clash 能把註冊表、Git 依賴、CDN 與其他終端機流量放到同一個可觀察的規則框架;相較於單純把所有流量塞進全域代理,Clash 又能透過規則、DNS 與 TUN 取捨來縮小影響範圍。當你能從「錯誤類型 → npm 設定 → Clash 紀錄 → 代理模式 → DNS」逐層排除,npm 安裝逾時就不必靠重裝 Node.js 或盲目換節點解決;如果你正在尋找一個能同時管理開發工具與一般應用連線的方式,先從實際日誌建立自己的規則,會比套用一份來源不明的全域設定更穩定。