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