如何在 Mac 安全清除 npm 快取

npm 快取不是 node_modules，也不是專案狀態

npm 的共用下載快取採用內容定址儲存，在 macOS 上預設位於 ~/.npm，但設定可能把它改到別處；node_modules 是個別專案已安裝的依賴樹，package.json 與 package-lock.json 則是重建依賴的依據，都不屬於快取。舊的 npm-shrinkwrap.json 同樣是專案檔案，但 npm v12 已不再讀取，必須重新命名為 package-lock.json，目前的 npm 才能用它重新安裝。

先找出實際路徑，再執行驗證

不要因為 ~/.npm 存在，就假設它仍是作用中的快取；npmrc、環境變數或工具設定都可能改變位置。先記下 npm --version，以 npm config get cache 的輸出為準，用 du -sh 加上該確切路徑測量；接著停止所有會讀寫快取的 npm 處理程序，再執行 npm cache verify。verify 會檢查索引與內容的完整性，並回收不再需要的資料，不需要加 --force；完成後重新測量，例行維護通常做到這裡就夠了。

1. 執行 npm --version 與 npm config get cache，複製輸出的路徑，並確認它是快取，而不是專案目錄。
2. 在 du -sh 後面接上剛才的確切路徑，測量目前大小與 macOS 的可用空間；路徑含空格時要加上引號。
3. 停止正在執行的 npm install、npm ci、npm exec 或 npm publish 等作業，再執行 npm cache verify，並保留摘要與錯誤訊息。
4. 重新測量；只有快取仍大到值得清、之後也能連網時，才在確認 package.json、package-lock.json 與私有套件庫設定都沒變之後，執行 npm cache clean --force。
5. 視需要再執行一次 npm cache verify，重新測量同一路徑，並以原本的依賴關係圖測試具代表性的專案。

不要把未經驗證的路徑貼進 rm -rf，也不要同時刪除 lockfile。一次同時改變快取與依賴解析，就失去了診斷原始問題所需的對照。

接受重新下載的代價，才完整清除

npm cache clean --force 適合已經量到快取很大、現在確實需要空間，或 verify 處理不了的快取專屬故障；--force 只加在這個指令上，不要設成永久的 npm 設定。清除會丟掉可重複使用的下載內容，之後安裝會變慢，而且需要套件庫、私有套件主機、Git、代理伺服器與網路都能使用；離線時，或已從上游消失的套件，可能再也取不回來。它不會解除安裝 node_modules，也不會改寫 lockfile，更修不好 ERESOLVE、憑證、Node 引擎版本、原生模組建置或生命週期指令碼的問題。

重新測量，並驗證實際專案

清除後再執行一次 npm config get cache，測量同一路徑與 macOS 的可用空間；如果想重建快取結構，可以再執行 npm cache verify。保留原本的 package.json 與 lockfile，用一個具代表性的專案跑正常的安裝、建置或測試流程，驗證連線、離線作業與私有套件庫的需求；同樣的錯誤再次出現時，就別再重複清快取。AskClean 目前只辨識預設的 ~/.npm，並把它當成單一的共用快取項目，確認後會整個永久刪除；自訂的快取路徑仍要透過 npm 確認與處理。

清理決策與風險對照

清除 npm 快取前，先用 npm config get cache 找出實際路徑並測量，再執行 npm cache verify；確有需要才用 npm cache clean --force。它不會刪除 node_modules、package.json 或 lockfile。

常見問題