npm 安裝一直逾時怎麼辦？檢查 Clash 代理與套件庫設定

前言：npm 逾時不一定是套件庫故障

使用 Clash 時執行 npm install，如果進度長時間停在 idealTree、fetch 或套件下載階段，最後出現 ETIMEDOUT，很容易以為 npm registry 當機。實際上，逾時可能發生在不同環節：終端機沒有使用 Clash 代理、規則把套件庫流量送到不合適的路徑、npm 仍保留舊代理設定，或 DNS 解析與目前網路環境不一致。

Clash 的系統代理不一定會自動套用到所有命令列程式。瀏覽器能正常開啟網頁，只能證明瀏覽器目前的流量可用，不能直接證明 Node.js、npm 或終端機程序也經過相同的代理。處理時先確認是哪一段連線失敗，再逐項修改，會比同時更換 registry、清除快取和調整超時參數更容易找出真正原因。

1檢查 Clash 模式與 npm 流量分流

先確認 Clash 客戶端已啟動，配置正在運行，而且選取的代理策略組中確實有可用節點。若使用規則模式，npm registry 的連線會依照配置中的規則分流；即使 Clash 顯示已連線，套件庫仍可能被規則送往 DIRECT，或套用到一個目前無法連通的代理策略。

確認代理模式與策略組

在 Clash Verge、Clash Verge Rev 或其他桌面客戶端中，先查看目前使用的是規則模式、全域模式還是直連模式。全域模式適合短時間用來判斷「是否為分流規則問題」，但不建議長期取代規則模式。測試時，也可以在客戶端的連線記錄中搜尋 registry.npmjs.org，查看命中的規則和實際使用的策略組。介面名稱會因客戶端版本而不同，請以目前使用版本的規則與連線頁面為準。

如果全域模式下安裝成功、規則模式下逾時，問題多半與規則順序、規則指向的策略組或規則集更新有關。若兩種模式都失敗，就繼續檢查代理埠、節點連線和終端機設定，而不要先假設只要增加一條規則就能解決。

確認 registry 規則

若你的配置允許自行編輯規則，可在其他可能攔截 npm 網域的規則之前加入套件庫規則。以下的 Proxy 是示意策略組名稱，必須改成自己配置中實際存在的名稱；不同訂閱的策略組可能叫「代理」、「Proxy」或其他名稱。若不能直接編輯訂閱配置，請使用客戶端提供的覆寫或規則管理功能，避免直接改動後又被訂閱更新覆蓋。

規則清單通常由上往下判斷，前面若已有涵蓋這些網域的規則，後面的新增規則就可能不會生效。修改後重新載入配置，再查看連線記錄確認實際命中的策略。若 registry 設為公司內部鏡像，還要將該鏡像使用的主機網域納入檢查，而不是只追蹤 npmjs.org。

2檢查 npm registry 與代理設定

npm 的 registry 和代理伺服器是兩項不同設定。registry 決定套件資訊從哪個服務取得；代理設定則決定 npm 如何連線到該服務。若 registry 指向失效的鏡像，即使 Clash 節點正常也可能無法安裝；反過來，registry 正確但 npm 的代理仍指向已關閉的埠，同樣會逾時。

先在終端機執行以下命令，查看目前設定與 Node.js、npm 版本。這些資訊不包含密碼時通常適合用於初步排查；若要分享日誌，仍應檢查是否含有私人 registry 位址或認證資訊。

一般公開套件庫可使用 https://registry.npmjs.org/。若目前 registry 是不熟悉或已停止服務的鏡像，先切回官方位址做一次測試；如果工作環境規定必須使用公司 registry，則不要擅自改成公開 registry，應確認公司鏡像是否可達及其代理要求。

上面的代理設定只是常見示例，並非所有 Clash 配置都使用 7890。若本機代理埠不同，請替換成客戶端實際設定；若代理本身沒有啟用，也不要填入這個位址。部分環境只需要清除 npm 的舊代理，並依靠系統代理或 TUN 模式處理流量；這時保留錯誤的 npm 代理反而會讓連線失敗。測試後可用 npm config get proxy 和 npm config get https-proxy 確認目前值。

3動手測試終端機代理是否可用

這一步的重點是把「Clash 節點是否可連線」和「npm 是否讀到正確代理」分開測試。先在 Clash 中確認代理已啟動，記下 HTTP 或 mixed-port，再開啟一個新的終端機視窗。若剛修改過 npm 設定，使用新視窗可以避免仍沿用舊的環境變數或 shell 狀態。

npm ping 或 npm view 成功，表示 registry 的基本請求能完成，但不保證所有套件的下載網址都能正常存取。某些套件會從其他網域取得 tarball，因此遇到「套件資訊取得成功、下載檔案仍逾時」時，請查看 npm 的詳細輸出，並在 Clash 連線記錄中確認實際失敗的主機，再針對該網域檢查規則。

4排查 DNS、連線逾時與快取問題

如果 npm 設定正確，連線仍不穩定，可以再檢查 DNS 和節點狀態。Clash 的 DNS 行為會受配置、客戶端及核心版本影響；當終端機解析出的位址與代理路徑不匹配時，可能出現解析失敗、連線重置或等待過久。先重新載入 Clash 配置，切換一個已知可用的節點，並觀察連線記錄中是否有 DNS 錯誤或被拒絕的請求。不要一次加入多組 DNS 參數，否則很難判斷哪一項改動有效。

也可以比較其他網路環境，或短暫暫停 VPN、其他代理和安全軟體，再測試一次。多個代理程式同時接管流量、公司防火牆限制外部套件庫，或本機安全軟體攔截 Node.js，都可能讓瀏覽器正常但 npm 失敗。測試時只做必要且可還原的調整，不要為了安裝套件長期關閉防護功能。

不要用調高逾時掩蓋連線問題

提高 npm 的重試次數或逾時時間，有時能幫助網路短暫抖動時完成下載，但它不會修正錯誤代理、失效 registry 或分流方向。若每次都卡到逾時上限，應先解決連線原因。若錯誤只在某個套件發生，確認套件名稱與版本、檢查鎖定檔及下載網址，並避免一開始就刪除整個快取或重新產生鎖定檔，避免引入新的版本差異。

如需清理 npm 快取，可先執行 npm cache verify 檢查快取狀態。只有在輸出顯示快取確實異常時，再依照專案需求處理；不要把 npm cache clean --force 當作解決所有逾時的固定步驟。清快取不會修復 Clash 無法連線，也不會讓錯誤的 registry 自動恢復。

5確認修正有效並避免再次逾時

完成調整後，不要只依賴一次安裝成功就結束排查。依序確認 registry 位址符合預期、npm 代理值與 Clash 實際埠號一致、連線記錄命中正確策略，然後重試原本失敗的命令。若只有全域模式成功，回到規則模式後仍失敗，就要繼續修正規則或策略組，而不是永久讓所有流量走同一條路徑。

• 代理直連對照：在 Clash 暫時使用直連或全域模式進行短時間測試，以區分 registry、節點與規則問題，測試後恢復原設定。
• 記錄可重現資訊：保存錯誤代碼、npm 版本、registry 位址、失敗主機及測試時間，方便與網路管理者或套件庫維護者核對。
• 管理專案設定：檢查專案目錄內的 .npmrc 是否覆寫使用者層級設定；在團隊專案中，應遵循團隊指定的 registry 與代理方式。
• 避免盲目更改鎖定檔：修復網路後先用原本命令重試，只有在套件依賴確實需要更新時，才修改 package-lock.json 或其他鎖定檔。

npm 安裝逾時通常不是單一原因造成。最有效的排查順序是：確認 Clash 可用、檢查分流命中、核對 registry、清除或修正 npm 舊代理、檢查終端機環境變數，最後才處理 DNS、快取或逾時參數。每次只改一項並重新測試，才能知道是哪個環節真正解決問題。

前往下載