用過 npm 的朋友應該都有這種經(jīng)歷新裝了一臺電腦裝完 Node.js 也沒多想直接 npm install 一把梭。結果幾個月下來C 盤莫名其妙就滿了D 盤卻空空如也。打開用戶目錄一看AppData\Roaming\npm里堆著幾十個全局包AppData\Local\npm-cache更是占了幾個 G——這里邊全是歷史下載的壓縮包你以為刪了省心結果下次跑一遍 install又把它們?nèi)貋砹?。這就是 npm 默認路徑設計的坑它對普通用戶很友好但對你這種裝了十幾個項目、動不動全局裝工具、經(jīng)常要換電腦同步環(huán)境的人來說默認路徑就是災難。好在 npm 從設計之初就把cache本地緩存、prefix全局安裝路徑、registry倉庫源這三個核心路徑拆開了而且全部支持自定義。這篇文章就把這三個東西一條條捋清楚給你一套可以直接抄的配置方案順便把熱詞里那些npm.ps1 無法加載、npm 不是內(nèi)部或外部命令、鏡像源怎么換一并解決掉。1. 先把概念捋清楚npm 的“三條路”分別管什么1.1 全局安裝路徑prefix——包被裝到哪里全局安裝路徑是 npm 最直觀的一個配置項對應npm prefix命令它決定你執(zhí)行npm install -g時包被解壓到哪個目錄。默認情況下Windows 上它是C:\Users\用戶名\AppData\Roaming\npmLinux/macOS 上是/usr/local用 nvm 裝的話會在 nvm 目錄下。全局包裝進去之后npm 會在同一個目錄下生成對應的可執(zhí)行文件——Windows 上是.cmd和.ps1兩個文件Linux/macOS 上是軟鏈接。這個細節(jié)跟后面的環(huán)境變量配置直接相關。很多人遇到的“全局裝了個工具命令行卻說找不到命令”十有八九就是 prefix 目錄沒加進 PATH。我把全局路徑單獨拎出來放在第一位講是因為它影響到的不只是磁盤空間還有多版本 Node 的共存問題。如果你用過nvm-windows、fnm、volta這些版本管理器會發(fā)現(xiàn)它們本質上就是在切換 Node 版本時動態(tài)修改 prefix 指向的目錄讓不同版本的 Node 各自擁有一套獨立的全局包。如果手動把 prefix 寫死在一個目錄再切換 Node 版本就會出現(xiàn) A 版本裝的包在 B 版本里完全不可見的情況——這不是 bug是路徑隔離的正常效果。1.2 本地緩存cache——下載的壓縮包存到哪如果說 prefix 是“安裝目錄”那 cache 就是“臨時倉庫”。npm 會把每次從 registry 下載的.tgz壓縮包按內(nèi)容尋址的規(guī)則緩存到本地路徑默認是C:\Users\用戶名\AppData\Local\npm-cacheWindows或~/.npmLinux/macOS。為什么要有緩存你想想一個項目里如果有幾百個依賴每個依賴又有各自的依賴跑一次npm install可能要下載上百個包。如果沒有緩存每次安裝都得全量走網(wǎng)絡。有了緩存之后相同版本的包直接從本地cacache目錄讀取速度快得飛起。但緩存也有個雞肋的地方它只增不減。你把 node_modules 刪了重新裝緩存還在你換了項目相同版本的包還能命中緩存。可一旦你項目升級換了一批依賴舊的緩存就永遠躺在那里。我見過最夸張的一個案例負責人的電腦上有 17GB 的 npm 緩存全部是近三年各種歷史版本的廢棄包。所以自定義 cache 路徑的核心價值有兩個一是把它挪出 C 盤二是方便你定期清理甚至整體遷移。有人習慣把 cache 放在固態(tài)硬盤上以追求速度這是合理的取舍后面我會給出方案。1.3 倉庫源registry——包從哪拉下來registry 對應的就是“倉庫路徑”。npm 默認的官方源是https://registry.npmjs.org/但國內(nèi)訪問這個源的體驗只有用過的人才知道——時好時壞抽風是常態(tài)尤其是那些體積大、依賴鏈深的包npm install能卡到你懷疑人生。于是就有了各種鏡像源淘寶npmmirror、騰訊、華為本質上都是官方倉庫的定期同步副本。換源之后 npm install 會去鏡像源拉取元數(shù)據(jù)和 tarball速度一般能從幾分鐘降到幾十秒體感提升非常明顯。這里要說個稍微冷門的知識點registry 不只影響下載還影響你執(zhí)行npm publish時的上傳目標。如果你把 registry 改成了鏡像源又同時維護著自己要發(fā)布的包那發(fā)布時要么臨時用--registryhttps://registry.npmjs.org/指一下要么單獨給發(fā)布命令寫個腳本否則容易把包發(fā)到鏡像源上然后一臉懵地發(fā)現(xiàn)“我發(fā)布的包去哪了”。1.4 為什么默認配置不適合生產(chǎn)環(huán)境把三個路徑串在一起看默認配置的問題就非常清晰了C 盤空間壓力大系統(tǒng)、軟件、頁面文件本來就占 C 盤npm 的全局包和緩存又持續(xù)往 C 盤塞東西。尤其在這個年代很多筆記本標配 512G 固態(tài)但只分了一個 C 區(qū)這種情況更致命。重裝系統(tǒng)等于丟全部只要系統(tǒng)一重裝AppData 目錄直接清空全局包要重新裝緩存要重新下相當于所有歷史優(yōu)化全部歸零。多項目隔離能力弱所有項目共用一套緩存版本沖突時緩存文件雖然不會互相覆蓋內(nèi)容尋址存儲是安全的不變的但會讓你在 node_modules 排查問題時多一層干擾。權限問題Linux/macOS 上默認 prefix 指向/usr/local普通用戶沒寫權限每次全局安裝都要加sudo。一旦需要sudonpm 的 postinstall 腳本就可能因為權限錯亂報出各種莫名其妙的EACCES。所以把 npm 的緩存、全局安裝路徑、倉庫源都顯式配置成你自己的目錄不只是“潔癖”更是一種環(huán)境治理手段。特別是在團隊協(xié)作、公司統(tǒng)一開發(fā)機、CI 鏡像預裝依賴這類場景下定制路徑的價值會進一步放大。2. 配置之前.npmrc 優(yōu)先級和配置文件位置2.1 .npmrc 的加載順序npm 的所有配置項都可以寫在.npmrc文件里。.npmrc在不同層級的優(yōu)先級不一樣理解這個順序是排查“為什么改了不生效”的關鍵。從高到低依次是命令行參數(shù)比如npm install --cache /tmp/cache優(yōu)先級最高項目級.npmrc即項目根目錄下的.npmrc只對這個項目生效用戶級.npmrc默認在~/.npmrcWindows 是C:\Users\用戶名\.npmrc全局級.npmrc在$PREFIX/etc/npmrcnpm 內(nèi)置的默認配置。這個優(yōu)先級跟 CSS 的層疊規(guī)則很像——越貼近項目、越具體的配置越能覆蓋全局。實際工作中最常見的問題是你在用戶級設置了prefixD:\nodejs\npm-global但項目里某個同事提交的.npmrc寫了自己的prefix結果你一跑命令發(fā)現(xiàn)路徑還是不對。所以配置完多路徑之后一旦發(fā)現(xiàn)行為不符合預期第一反應應該是用npm config list查看當前生效值來驗證。還有個小細節(jié).npmrc是支持注釋的用#或;開頭都行。在團隊項目里提交項目級.npmrc時寫上中文注釋說明這個配置的用途能省掉后來者大量排查時間。2.2 查看當前所有配置動手改之前建議先看一眼當前的配置全景。在項目目錄下執(zhí)行npm config list這個命令會打印出所有配置項包括哪些來自哪個配置文件。如果你用 nvm 或 fnm 這類工具最好這里就確認一下當前的 prefix 在哪避免改錯文件。npm config ls -l加-l參數(shù)會打印出 npm 的全部默認配置適合你探索各個配置項的默認值。比如你可以查一下cache、prefix、registry三個關鍵配置當前的取值做到心里有數(shù)。2.3 備份與遷移舊配置如果你已經(jīng)有了一段使用歷史建議在動刀之前先做個備份。~/.npmrc文件本身很小直接復制一份就行cp ~/.npmrc ~/.npmrc.bakWindows 上用copy C:\Users\用戶名\.npmrc C:\Users\用戶名\.npmrc.bak。如果你還想把現(xiàn)有的緩存和全局包也一起搬走那就不要只改配置還得把文件本身挪過去。先記住這兩個路徑npm config get cache npm config get prefix然后停止 Node 相關進程把兩個目錄整體拷貝到目標位置Windows 上推薦用robocopy因為文件夾層級深、文件數(shù)量多普通復制容易中斷robocopy C:\Users\你的用戶名\AppData\Local\npm-cache D:\npm\cache /E /MOVE/MOVE參數(shù)會在復制完成后刪除源目錄相當于剪切。Linux 下直接mv或rsync -av都行。搬完再改配置這樣連歷史緩存都能用上不用重新下載一遍。3. 手把手實操三個路徑一次配到位3.1 方案 A命令行臨時配置如果你想先快速試一下效果或者只針對某一次安裝指定路徑完全不用改任何配置文件。直接給命令加參數(shù)npm install --cache D:\npm\cache --registry https://registry.npmmirror.com也可以把參數(shù)寫到環(huán)境變量里比如先設npm_config_cachenpm 會讀取這個環(huán)境變量作為配置值。這種方式適合臨時用但說實話只適合應急因為你不可能每次都敲這么一長串參數(shù)。更合理的做法是用下面的方案 B 一次性配置好。非要給這種臨時方案找個合理使用場景的話我會用它在 CI 流水線里動態(tài)指定緩存路徑比如 Jenkins 的某個 job 想單獨用一個獨立緩存目錄避免和別的 job 互相污染。這種一次性覆蓋的思路是干凈有效的。3.2 方案 B修改用戶級 .npmrc這是最推薦的做法。執(zhí)行下面三條命令npm config set cache D:\npm\cache npm config set prefix D:\npm\global npm config set registry https://registry.npmmirror.com原理上npm config set默認就是寫用戶級.npmrc等價于手動編輯~/.npmrc。如果你想保留官方源只改前兩個那就不要執(zhí)行第三條。這里有個取舍想多說一句我把 prefix 放在D:\npm\global而不是 Node 安裝目錄下主要考慮的是以后升級 Node 或切換版本時不會殃及全局包。如果你用 nvm那可以把 prefix 交給 nvm 自己管理不要手動寫死如果你只裝了一個 Node就可以放心用自定義路徑。配置完之后立刻驗證npm config get cache npm config get prefix npm config get registry三條命令輸出應該是你剛填的三個值。這一步非常建議執(zhí)行因為肉眼確認過的配置才能讓你在后續(xù)排錯時心安理得地懷疑別的環(huán)節(jié)。3.3 方案 C項目級配置有些場景下你需要為某個項目單獨指定源或緩存。比如公司內(nèi)網(wǎng)有一個私有 npm 倉庫只對特定項目開放或者某個項目因為歷史原因鎖定了某個特定的鏡像源。這種情況就在項目根目錄下新建.npmrcregistryhttps://npm.company.com/ cacheD:/npm/project-cache只寫需要的項沒寫的項會從用戶級或默認配置繼承。這個機制非常靈活配合npm config list可以看到當前項目的完整生效配置。但這里有個值得注意的點項目級.npmrc一旦提交到 Git就可能給別人帶來困擾。如果公司內(nèi)網(wǎng)地址沒法從外部訪問同事拉下代碼后執(zhí)行 npm install 會直接失敗。所以如果只是為了本地調試記得把項目級.npmrc加入.gitignore如果是團隊統(tǒng)一使用的配置就要在 README 里寫清楚背景。3.4 Windows/Linux/macOS 的路徑差異雖然命令差不多但不同系統(tǒng)的路徑寫法有講究。Windows路徑建議用正斜杠D:/npm/cache反斜杠在某些 npm 版本里會被當成轉義符。放在.npmrc里尤其要注意。Linux普通用戶建議把全局包放在~/.npm-global避免碰/usr/local的權限問題。npm 文檔里也推薦這個目錄。macOS跟 Linux 類似但如果你用homebrew安裝的 Nodeprefix 默認在/opt/homebrew或/usr/local這時改 prefix 要格外小心最好保持不動只改 cache。另外如果你改了 prefix記得把新目錄加進系統(tǒng) PATH。這一步不做后面全局安裝的工具全都會“失效”。Windows 上按Win S搜索“環(huán)境變量”編輯用戶變量的Path追加D:\npm\global保存后重開終端。Linux/macOS 則在~/.bashrc或~/.zshrc里加export PATH~/.npm-global/bin:$PATH然后source ~/.bashrc或source ~/.zshrc生效。3.5 配置完成后如何驗證配置完不等于萬事大吉建議按下面幾步做個完整驗證npm install -g nodemon nodemon -v如果能正常輸出版本號說明全局安裝路徑和 PATH 都沒問題。接著隨便找個項目裝個依賴npm install lodash --prefer-offline第一次跑比較慢因為緩存還是空的跑完之后你再看緩存目錄D:\npm\cache里應該已經(jīng)出現(xiàn)了_cacache文件夾。以后重復安裝時只要緩存命中速度會有肉眼可見的提升。還有個隱藏的驗證方式npm cache verify它會掃描緩存目錄統(tǒng)計有效緩存和垃圾文件的體積同時輸出緩存目錄路徑。順手跑一遍確認它指向的是你新配置的目錄說明整個鏈路已經(jīng)通了。3.6 環(huán)境變量 PATH 和 npm.ps1 執(zhí)行策略熱詞里反復出現(xiàn)的npm : 無法加載文件 C:\Program Files\nodejs\npm.ps1因為在此系統(tǒng)上禁止運行腳本本質上是 PowerShell 執(zhí)行策略的問題。默認情況下PowerShell 不允許執(zhí)行 npm 的腳本文件報錯信息會披著“路徑不對”的外衣騙你半天。解決方式不復雜管理員身份打開 PowerShell 執(zhí)行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserRemoteSigned的意思是本地腳本可以運行從網(wǎng)上下載的腳本必須有受信任的簽名。這個策略在安全性和便利性之間取了個平衡也是 Node 官方文檔推薦的處理方式。而npm 不是內(nèi)部或外部命令這類報錯則要分兩類排查。第一類是npm本身找不到查 Node 安裝目錄有沒有加入 PATH第二類是全局包的 bin 找不到查你改的 prefix 目錄有沒有加入 PATH。兩個 PATH 各自獨立經(jīng)常搞混。4. 進階玩法緩存遷移與離線安裝4.1 拷貝已有緩存目錄如果你已經(jīng)用了很久的 npm緩存里可能躺著幾百個包的壓縮包。與其重新走一遍網(wǎng)絡不如直接把舊緩存目錄整體搬過去。操作流程上面提過這里再補充一個細節(jié)npm 緩存目錄結構里的_cacache文件夾是核心里面是內(nèi)容尋址的數(shù)據(jù)文件理論上是不可直接讀的但可以整體復制不影響復用。有個常見的疑問我能不能把緩存目錄只讀掛載到共享盤讓多臺機器共用技術上可行但我不推薦。緩存讀寫頻率高網(wǎng)絡磁盤的 IO 延遲會拖慢 install 速度而且 npm 緩存有并發(fā)寫入共享目錄容易出現(xiàn)鎖沖突或內(nèi)容損壞。同一臺機器上遷移到本地固態(tài)盤是最優(yōu)解多機共享更適合用私有 registry 或離線鏡像來解決。4.2 利用離線緩存裝包npm 的緩存策略可以從“被動命中”升級為“主動離線”。關鍵參數(shù)有兩個--prefer-offline優(yōu)先用緩存緩存沒有再去網(wǎng)絡拉取。--offline完全離線只用緩存。我的習慣是在網(wǎng)絡條件不穩(wěn)定的場景下加--prefer-offline比如出差時連酒店 Wi-Fi跑新項目的第一次 install 明顯比不帶參數(shù)穩(wěn)。如果你確定某個項目的依賴之前全部裝過可以直接npm install --offline速度甚至能達到秒級。另外一個被低估的功能是npm pack它會把某個包打包成.tgz文件保存到本地你可以拿到這個文件后手動指定安裝npm install ./some-package-1.0.0.tgz這比離線緩存更“原始”因為它不查緩存直接裝你指定的文件。適合在公司內(nèi)網(wǎng)分發(fā)內(nèi)部工具包或者把某個私有包傳給別的同事。4.3 緩存清理與維護策略緩存不是越大越好。體積膨脹到一定程度清理反而能提升 npm 的掃描效率。這里給一套適合大多數(shù)人的清理節(jié)奏npm cache verify npm cache clean --forceverify只清理垃圾文件比如下載一半的碎片clean --force會把整個緩存清空需要重新下載。建議日常只跑verify兩到三個月跑一次clean。如果你把緩存放在專門的數(shù)據(jù)盤配合這些命令磁盤占用完全可控。不過要特別提醒一句不要把clean --force當成“釋放空間”的第一反應。我之前就干過一次清理完才發(fā)現(xiàn)有個項目要重新裝依賴而當時網(wǎng)絡正在抽風結果原本 5 秒能裝完的項目硬是跑了 20 分鐘。緩存存在的意義就是對抗網(wǎng)絡的不確定性清它之前先掂量掂量。4.4 CPU 架構與平臺差異導致緩存失效還有一個隱蔽問題cache 內(nèi)容是按包名、版本和平臺、架構一起參與尋址的。你在 Windows x64 上下載的緩存切到 macOS arm64 上并不能直接復用因為 tarball 的平臺版本不同。多設備之間的緩存遷移不是完全通用的這個是很多人第一次同步緩存目錄時最迷惑的地方。形象點說npm 緩存像是“圖書分館”每本書壓縮包都按分類號平臺 架構 版本存放。你把整個分館搬到新城市大部分書能直接用但有一部分書比如帶原生編譯的node-sass、sharp會因為目標機器架構不同而必須重新借閱。理解了這層關系你就能明白為何跨平臺遷移后緩存命中率不如預期了。5. 常見問題與排查技巧實錄5.1 配置了路徑但 npm install 不受影響改了npm config set cache之后跑 install 卻感覺文件還在老的緩存目錄。這種情況九成是因為命令的執(zhí)行環(huán)境和你改配置的環(huán)境不是同一個。比如你改了用戶級.npmrc但當前項目里存在項目級.npmrc覆蓋了配置或者你開了多個終端舊的終端還保留著之前的 npm 路徑。排查方式一句話npm config list看當前實際生效值。如果顯示的還是老路徑順著層級一路查下去是項目級覆蓋還是環(huán)境變量覆蓋一眼就能看出來。比較隱蔽的是某些 IDE 集成的終端會自動加載.env文件把npm_config_cache環(huán)境變量寫進了進程里這種情況在終端里手動敲一句echo $env:npm_config_cachePowerShell就能現(xiàn)形。5.2 換源之后出現(xiàn)證書報錯或包不完整用了鏡像源之后偶爾會遇到SELF_SIGNED_CERT_IN_CHAIN或某些包安裝后執(zhí)行不對。這通常是鏡像源同步的不完整或緩存里有舊的元數(shù)據(jù)。先別急著換源先清一下這個源的緩存npm cache clean --force還不行就臨時切回官方源對比試試如果官方源正常就是鏡像同步問題只能換一個鏡像或等待同步。值得留意的是不同鏡像源的同步頻率不一樣冷門包可能出現(xiàn)版本滯后。所以我的建議是日常開發(fā)用鏡像源沒問題但發(fā)布包、安裝最新版本的前沿工具時臨時切回官方源更穩(wěn)妥。5.3 npm 不是內(nèi)部或外部命令這個報錯分兩種情況。一是 Node 沒裝好或沒有加入 PATH你可以在命令行試node -v如果這個也報錯就去檢查 Node 安裝目錄如果node -v正常但npm不行那就是 npm 的系統(tǒng)路徑被誤改或損壞。二是你剛全局裝完一個包直接輸入包名發(fā)現(xiàn)找不到命令——這就是前面說的 prefix 沒進 PATH或者 PATH 里是舊路徑。一個不太常見的坑是 Windows 下 PATH 中路徑有空格比如C:\Program Files\nodejs\。如果你自定義的 prefix 目錄名也帶空格某些腳本工具可能解析失敗。所以自定義路徑時盡量用無空格的目錄名比如D:\node-global而不是D:\My Common Tools\node-global。這類問題沒有報錯信息純粹就是“命令找不到”排查起來特別費勁不如一開始就繞開。5.4 ERR! EACCES 權限不足Linux/macOS 上比較常見本質是寫不了 prefix 或 cache 目錄。如果包已經(jīng)裝到了系統(tǒng)目錄而你用的是普通用戶就需要sudo但這往往是飲鴆止渴——sudo 之后生成的目錄歸 root 所有后面不寫 sudo 還是裝不了。根治方案就一個把 prefix 設到用戶目錄下然后再把新目錄加進 PATH。命令不要加 sudo直接npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH正常情況下再也不會遇到 EACCES。Windows 上如果遇到 EPERM多半是緩存或全局目錄被某個進程鎖住比如正在運行的 Node 或 IDE 的索引進程關掉再試。5.5 緩存損壞導致 install 報錯雖然 npm 的內(nèi)容尋址存儲足夠健壯但偶爾也會碰上緩存文件損壞。癥狀通常是某個包反復失敗或者npm ci報錯但npm install正常。解決辦法就是讓 npm 自己修復先npm cache verify再單獨針對那個包重裝。這個方法比直接 clean 整個緩存溫和得多。如果 verify 也救不回來再 clean。我個人的經(jīng)驗是先清單個包再局部 verify最后才考慮全量 clean這樣能最大限度保留有效緩存。5.6 快查速記表癥狀可能原因解決方式無法加載 npm.ps1PowerShell 執(zhí)行策略限制Set-ExecutionPolicy RemoteSigned -Scope CurrentUsernpm 不是內(nèi)部或外部命令Node 或 prefix 沒進 PATH檢查node -v修復對應 PATH 項改了 cache 不生效項目級 .npmrc 覆蓋npm config list逐層查全局包裝完找不到命令prefix 目錄沒進 PATH把npm prefix -g結果加入 PATH頻繁 EACCES 權限錯誤prefix 指向系統(tǒng)目錄改用~/.npm-global換源之后包不穩(wěn)定鏡像同步滯后清緩存重裝或切回官方源緩存目錄巨大長年累積歷史包定期npm cache verify必要時 clean跨平臺緩存不通用平臺/架構參與尋址接受緩存部分失效重裝即可6. 花點時間配置省下幾個月的心煩這套配置我用了幾年從最早把 cache 和 prefix 挪到 D 盤到后來換機器時直接用備份的.npmrc和緩存目錄一鍵恢復再也沒被“C 盤滿了”或者“重裝系統(tǒng)后所有全局包要重來”的事情折騰過。說到底npm 這三個路徑的定制并不復雜就幾條命令的事情。但很多人在遇到問題時只想著“臨時裝一下能用就行”結果路徑越來越亂到最后根本分不清是緩存問題、權限問題還是網(wǎng)絡問題?；?10 分鐘把環(huán)境理順后續(xù)所有的 install、publish、調試都會順暢很多。最后再分享一個小習慣每次新配完環(huán)境我都會跑一遍npm config list并把輸出截圖存到自己的環(huán)境文檔里。換電腦、教同事、排查環(huán)境問題時這張截圖就是最可靠的參照。配置再清晰都不如留一個“標準化基線”來得省事。