1. nvm是什么为什么要装一个版本管理工具先别急着下载安装如果你连nvm是什么、它和Node.js是什么关系都没搞清楚装完十有八九要翻车。nvm的全称是Node Version Manager直译就是Node版本管理器。一句话说清楚它让同一台电脑上可以同时存在多个Node.js版本并且随时切换。很多刚接触前端的人把“nvm下载安装教程”和“node.js下载安装教程”当成两回事其实完全可以放在一起搞因为装nvm的目的就是为了把Node.js装得明明白白。这篇文章适合几类人刚开始学Node.js、连环境都装不明白的新手电脑上已经装过Node.js但版本管理混乱的老手以及要在不同项目之间来回切换Node版本、被全局包搞得头大的开发同学。我会把Windows、macOS、Linux三条安装路线都讲一遍重点放在Windows上因为nvm在Windows下的坑最多也最容易把人劝退。1.1 没有nvm的时候Node版本切换有多痛先想象一个场景你要维护一个老项目代码依赖的是Node 12而你几个月前为了试新特性顺手装了Node 20。结果旧项目一启动就报错什么语法不兼容、依赖装不上问题五花八门。这时候你有两个选择卸载Node 20、重新装Node 12或者硬着头皮改代码。前者听着简单实际做起来很折腾因为卸载之后你还需要把全局安装的包、环境变量、缓存全部清理干净稍有不慎就留下一堆残留装新版的时候又和旧配置打架。更麻烦的是你手头可能同时有三四个项目每个要求的Node版本都不一样。没有nvm的时候你只能反复卸载、重装一次折腾半小时。有了nvm之后整个过程变成一句话nvm use 20.11.0回车当前终端的Node环境就切过去了。再切回旧版本也是一样。这就是版本管理工具的价值它把“环境管理”这件事从手工劳动变成了一个可重复执行的命令。除了切换方便nvm还有一个容易被忽略的好处它把Node版本之间完全隔离。每个版本都有自己独立的全局模块目录你在Node 18下装的全局包不会污染Node 20下的环境反过来也一样。这一点看起来像“缺点”实际是保护机制等到后面讲到全局包丢失问题你就会理解。1.2 nvm的运作原理改的是PATH不是装多个神仙很多新手以为nvm是魔法装了之后电脑里就有好多个Node。实际它的原理并不复杂nvm本身只是一个“调度器”负责管理安装在某个统一目录下的各个Node版本。当你执行nvm use某个版本时它做的事是修改当前终端会话的环境变量PATH把目标版本的可执行文件目录排到最前面。可以用一个生活化的类比PATH就是外卖配送路线图系统执行node命令时会按路线图一个个去指定目录里找node这个“店铺”。nvm做的事情就是动态调整这张路线图让系统先找到你当前指定的那家“店”。Windows上nvm-windows的实现方式略有不同它还会借助符号链接把某个固定的Node目录指到当前选择的版本但核心思路仍然是“改路径、改指向”不会真的在同一时间让两个版本的node同时成为默认命令。理解了原理你就知道为什么安装nvm之后一定要重开终端因为环境变量只在“终端打开的那一刻”读取一次不重开终端新的PATH根本不会生效。这个问题后面也会经常遇到。2. 安装前必须确认的三种情况很多人安装nvm失败不是因为步骤不对而是因为“起手式”就错了。电脑上已有的Node.js没有处理、权限不够、网络不稳定任何一个都可能导致后面看似完美的安装流程翻车。这里先花几分钟把前置工作做完。2.1 先摸摸底你的系统和终端是什么nvm在Windows、macOS、Linux下的安装方式完全不同甚至Windows下的nvm和Mac/Linux下的nvm都不是同一个东西。Windows下通常使用的是社区维护的nvm-windows它提供的是exe安装程序安装后命令叫nvm原版nvm的很多命令和它略有差异macOS和Linux下使用的是原版nvm以shell脚本安装为主。所以在开始之前先确定你的操作系统和默认终端。为了直观我做了一个对照表供你参考操作系统常用终端推荐安装方式命令入口WindowsPowerShell / cmd官方发布页下载exe安装包nvmmacOSTerminalzsh官方脚本或源码手动安装nvmLinuxbash / zsh官方脚本或源码手动安装nvm另外提醒一点如果你用的Windows自带的旧版cmd建议切换到PowerShell再执行很多权限和路径问题在PowerShell下表现得更清晰。macOS在较新版本上默认shell是zsh安装时配置文件名要写成.zshrc而不是.bash_profile这个细节我见过太多人搞错。2.2 检查电脑上是否已有Node.js卸载干净再动手打开终端分别执行以下两个命令看看输出结果node -v npm -v如果提示“找不到命令”或者“不是内部或外部命令”说明你的电脑是干净的可以跳过这节。如果正常输出了版本号比如v18.17.0那你必须先处理掉现有Node.js否则后面nvm装了也可能抢不到“默认Node”这个位置因为系统原本的Node路径优先级往往更高。卸载Node.js时Windows用户去“设置 - 应用”里找到Node.js项卸载即可。这里有一个重点卸载之后手动检查一下环境变量看PATH里是否还残留Node相关的路径比如C:\Program Files\nodejs。如果有手工删除否则等会儿安装nvm时会一直读到一个不存在的旧路径。macOS用户如果当初是用官方pkg包安装的建议用安装包自带的卸载脚本而不是简单删除目录否则/Library目录下会残留一堆符号链接。Linux用户一般用apt或yum卸载通常比较干净但仍建议卸载后执行which node确认没有遗留。2.3 权限和网络安装前的最后一道保险Windows下运行nvm安装程序必须右键选“以管理员身份运行”。这一点不是可有可无因为安装过程要写环境变量还要在系统盘创建符号链接普通权限很可能中途报错。macOS和Linux下安装原版nvm不需要管理员权限默认安装到当前用户的home目录这反而是更安全的做法。网络方面nvm安装成功后首次安装Node.js时要从远程仓库下载压缩包这一步对网络稳定性比较敏感。如果你的网络访问官方下载源很慢后面第3节会讲到配置镜像源的方法建议安装完nvm第一时间就把镜像配上。这里先记着一句话不要因为下载慢就去折腾所谓的“高速下载器”和第三方安装包那些东西往往是版本被改过或者捆绑了额外程序安全风险完全不值得。3. Windows系统下nvm的下载安装全流程Windows用户是踩坑大户所以这一节我写得最详细。你要记住一个原则nvm-windows不是原版nvm它没有原版那么多命令但日常核心功能足够用了。3.1 去哪下载Windows版nvm打开nvm-windows的官方发布页面找到最新的发行版本。你会发现里面有几个文件日常安装只需要两个nvm-setup.exe和nvm-noinstall.zip。前者是图形安装程序双击就能一步步装后者是免安装压缩包适合不想走安装向导、喜欢手动配置的人。我的建议是第一次装直接用nvm-setup.exe省事、不容易出错。nvm-noinstall.zip留给那些想要完全控制安装位置、或者后面打算再手动折腾环境变量的老手。安装包体积不大下载时如果特别慢可以找网络空闲的时间段重试或者换一个网络条件更好的环境尽量不要使用来路不明的“镜像破解版”或“绿色版”。别问我怎么知道的我见过有人下载了一个山寨安装包装完在系统目录里多了一堆垃圾程序。3.2 安装向导里的每个选项都代表什么双击nvm-setup.exe一路Next的时候有两个路径选择页面要打起精神。第一页是选择nvm本身安装的位置。默认路径一般是C:\Users\你的用户名\AppData\Roaming\nvm这个路径建议保留默认或者改到D盘类似D:\nvm这种纯英文路径。千万不要把路径里带上中文、空格、特殊符号例如“C:\软件安装\nvm”这种后面八成会出现莫名其妙的定位失败问题。第二页是选择Node.js的符号链接目录默认是C:\Program Files\nodejs。这个目录就是将来你在命令行里执行node时实际去的地方。nvm每切换一次版本就把这个目录里的指向换到另一个真实版本目录。保持默认的Program Files路径通常没问题但需要注意它同样要求不能带中文和空格。装完之后先不用急着运行任何命令直接关掉当前终端窗口重新打开一个新的“管理员PowerShell”窗口。为什么要重开前面讲过环境变量只在终端启动时读取一次你不重开旧窗口里根本不知道nvm的存在。3.3 验证nvm是否安装成功在新开的PowerShell窗口执行nvm version如果输出一串版本号比如1.1.12说明安装成功。如果提示“nvm不是内部或外部命令”先别慌检查两件事第一你是不是忘了重开终端第二去安装目录看一眼确认nvm.exe真的存在。如果存在但还是提示命令找不到那就是环境变量PATH有问题具体排查方法在第6节。验证通过之后我们离“装Node.js”只剩一步先把下载源配好。3.4 配置下载镜像源解决下载慢的痛点Windows下nvm的配置信息存放在一个settings.txt文件中它就在你刚才选择的nvm安装目录里。打开这个文件你会发现里面默认写着root: D:\nvm path: C:\Program Files\nodejs arch: 64 proxy: none想解决下载慢的问题只需要在这个文件里追加两行node_mirror: 你选择的Node下载镜像地址 npm_mirror: 你选择的npm下载镜像地址这里我不直接在博文里写死某一个镜像地址因为这类地址更新频繁、不同网络环境下可用性差异很大去年能用今年失效是常态。你只需要在搜索引擎里搜“Node.js 镜像站”或者到可信的社区找当前可用的地址即可。配置完保存文件重新打开终端再执行nvm install的时候你就会发现下载速度明显改善。需要提醒一句镜像源一定要选可信、维护活跃的不要随便拿一串号称“最新”的地址就往配置文件里塞因为一旦地址指向恶意服务器你下载的Node压缩包可能被植入不明内容装出来的环境根本不可信。4. macOS / Linux系统下安装nvmmacOS和Linux推荐使用原版nvm安装方式有两种官方一键脚本以及手动从源码仓库拉取。前者方便后者更适合不放心“直接执行远程脚本”的同学。4.1 使用官方一键脚本安装打开终端执行官方文档提供的一键安装脚本。脚本地址以官方发布的最新版本为准格式一般是这样curl -o- https://你的nvm仓库下载地址/install.sh | bash执行完成后脚本会自动把nvm仓库克隆到当前用户目录下的.nvm文件夹然后修改你的shell配置文件。如果是zsh它会写入.zshrc如果是bash会写入.bashrc或.bash_profile。脚本执行结束后终端会提示你重开窗口或手动执行source ~/.zshrc验证一下nvm --version能输出版本号就成了。这里有一个很多新手会犯的错误执行完source之后明明看到nvm命令能用了结果关掉终端再开又找不到了。原因多半是脚本写入的配置文件不是当前shell实际读取的那一个。比如你的默认shell是zsh配置文件却是.bashrc自然不生效。排查方法很简单先执行echo $SHELL确认自己在用什么shell再去对应的配置文件里检查有没有nvm相关的初始化代码。4.2 不想执行远程脚本手动安装更稳妥如果你对“curl一段脚本直接管道给bash”这件事有顾虑完全合理。其实手动安装也不难本质就是三件事把nvm代码拉到本地、定义一个函数、写几句初始化配置。先找一个目录执行git clone 你的nvm仓库地址 ~/.nvm然后在你的shell配置文件中追加以下几行export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh [ -s $NVM_DIR/bash_completion ] \. $NVM_DIR/bash_completion保存后执行source ~/.zshrc再验证nvm --version同样能正常使用。这种方式的好处是你全程知道每一步做了什么出了问题也容易排查。如果你电脑上连git都没有装那就先装gitnvm仓库本身不大拉取很快。4.3 一个常见建议macOS上尽量别用brew装nvmmacOS用户常常习惯性用Homebrew安装一切但装nvm我建议你打消这个念头。不是不能装而是通过brew安装的nvm在你使用nvm install node的时候比较容易遇到目录权限问题最终Node会被装进brew管理的目录里和nvm的设计初衷产生冲突。你可能会发现自己明明执行了nvm usenode却还是指向系统默认路径排查起来非常头疼。既然有更干净的脚本安装方式建议就别给自己找麻烦。macOS下安装完成后还要留意系统升级导致的shell切换。macOS每次大版本升级之后有时候默认shell会被重置如果发现nvm命令突然“消失”多半就是shell配置没有生效重新检查一遍.zshrc即可。5. 装好nvm之后Node.js怎么装、怎么切很多人把nvm安装完成当作终点实际上这才是起点。nvm本身不包含Node.js它只是一个“安装器调度器”接下来你要用它把Node.js真正装进系统里。5.1 日常使用最频繁的nvm命令先给一张命令速查表建议收藏命令作用示例nvm list available列出远程所有可安装版本Windowsnvm list availablenvm ls-remote列出远程所有可安装版本macOS/Linuxnvm ls-remotenvm install 版本号安装指定Node版本nvm install 20.11.0nvm use 版本号切换当前终端使用的版本nvm use 20.11.0nvm ls列出本地已安装版本nvm lsnvm current显示当前使用的版本nvm currentnvm alias default 版本号设置默认Node版本nvm alias default 20.11.0nvm uninstall 版本号卸载指定版本nvm uninstall 18.17.0这里注意一下macOS/Linux原版nvm查远程版本用nvm ls-remoteWindows版用nvm list available两者命令不一致。我见过有人在Windows上敲ls-remote然后报错其实就是版本分支不同导致的。5.2 第一次装Node.jsLTS还是Current选哪个打开终端执行nvm list available或nvm ls-remote你可能会被一串版本号吓到。Node.js的版本号看着多但其实只需要关心两类LTS长期支持版和Current当前发布版。LTS版本经过了长时间稳定性验证生产环境首选Current版本更新更快新特性多但稳定性相对弱适合自己折腾和学习。建议你第一次安装直接选一个偶数版本的LTS比如20.x系列不要纠结非要装最新。新手最忌讳的是“非最新不装”最新的Node往往意味着周边依赖还没有完全适配装完项目一跑就报错。完整流程演示一下假设我要安装Node 20.11.0nvm install 20.11.0 nvm use 20.11.0 node -v npm -v执行完nvm install之后安装程序会自动创建对应版本目录。执行nvm use之后通路才算打通。最后分别验证node和npm两个命令能正常输出版本号说明Node.js环境正式可用。为了让以后每次打开终端自动使用这个版本再执行一条命令nvm alias default 20.11.0这条命令设置“默认版本”以后新开终端就自动切换到Node 20不需要再手动use一次。如果你有多个版本并存别忘了这一步否则下次打开终端会找不到node命令。5.3 用.nvmrc锁定项目版本团队协作不再解释当你的项目需要在特定Node版本下运行时在项目根目录创建一个文件文件名是.nvmrc里面只写一行版本号例如20.11.0之后团队成员进入项目目录执行nvm usenvm会优先读取当前目录下的.nvmrc并自动切换到对应版本。如果本地还没装这个版本它会提示你先执行nvm install。这个小文件应该提交到版本仓库因为它起到了“项目环境约定”的作用比在文档里写一段“请在Node 20.11.0下运行”靠谱得多。6. 常见问题与排查技巧实录环境工具这种东西十个人安装至少有两个人会在某个环节卡住。这些报错大多不是因为你操作错得离谱而是出在那些教程里“默认你会”的细节上。我把平时见到最多的几个问题一次性整理出来。6.1 提示“nvm不是内部或外部命令”或“command not found”这个报错占安装问题的一半以上。Windows下最直接的原因是没有重开终端或者nvm安装目录没有进入PATH。先重开终端试试不行就手动去安装目录确认nvm.exe存在再检查系统环境变量里是否包含这个目录。如果你的PATH里确实有但还是找不到命令可以重启一次电脑环境变量的刷新有时候就是慢半拍。macOS/Linux下遇到bash: nvm: command not found优先检查shell配置文件里是否真的添加了nvm初始化代码。比如用zsh却改.bashrc很可能就不生效。另外执行命令行source ~/.zshrc时要在home目录别站在别的目录就执行那等于什么都没改。6.2 nvm install下载慢、老是失败nvm本身装好了但执行nvm install 20.11.0时进度条半天不动或者直接提示连接超时。这是镜像源问题。Windows用户记得检查settings.txt里的node_mirror和npm_mirror配置macOS/Linux用户可以通过设置环境变量NVM_NODEJS_ORG_MIRROR指定镜像。配置好之后下载速度通常能提升到可以接受的范围。如果镜像也换过了还是失败就要检查是不是安全软件拦截了下载进程或者磁盘空间不足。关闭多余的安全拦截、清理一下临时文件再重试。仍然不行就手动访问镜像站下载对应版本的node压缩包再按nvm的目录规则放置。这种“手工装版本”的方式虽然麻烦但确实是最终兜底方案。6.3 切换Node版本之后全局安装的工具全都没了这是最多人误解的一个点。你用nvm use切到另一个Node版本然后执行某个全局命令结果提示找不到。这不是nvm把你的工具删了而是在nvm的世界里每个Node版本拥有独立的全局包目录。你在Node 18下装的全局工具切到Node 20之后当然不可见。解决方式有两种第一种切回原来版本继续用第二种在当前版本重新执行npm install -g把工具装回来。Windows版nvm提供了一个迁移命令nvm reinstall-packages执行它会尝试把上一个版本的全局包重新装到当前版本够省事。但这命令不能保证所有包都一次成功遇到个别包报错就单独重装。6.4 明明nvm安装成功node执行的还是旧版本如果你在安装nvm之前没有把系统里原有的Node.js清干净这种怪现象很常见。你可以执行where nodeWindows或which nodemacOS/Linux查看node命令实际来自哪个路径。如果输出的路径不是你nvm管理的那个目录说明系统PATH中原来Node路径排在了nvm前面。解决办法就是把旧的Node相关路径从PATH里彻底删掉。Windows用户在系统环境变量里检查是否残留nodejs目录macOS/Linux用户用which node找出旧路径后清理对应的符号链接或手动删除旧Node安装残留。这一步做完一定要重启终端。7. 一份可以直接套用的避坑清单最后这部分不打算给你总结什么“大道理”就是把我在实际安装过程中踩过、也看着别人踩过的坑列出来你以后遇到可以直接按着查。所有涉及Node、nvm的目录路径一律不用中文、空格、特殊符号不要因为默认路径看着顺眼就乱改。安装或配置完成后立刻重开终端。环境变量的生效机制决定了“新开窗口”永远是第一步排查动作。Windows下安装nvm-setup.exe必须管理员权限但日常使用nvm命令不需要管理员别混为一谈。只要下载速度不对第一反应是检查镜像源而不是反复点击重试。重试一百次也改变不了网络路径不好的现实。每个Node版本都有独立的全局包目录切换版本导致全局工具“消失”是设计如此不是你操作失误。别装来路不明的“加固版”“一键版”nvm安装包环境工具有任何异常都会被后续项目无限放大。关于镜像配置再多说一句个人体会。网络上流传的镜像地址经常变化与其收藏某一串地址不如掌握“配置格式”这件事。格式其实就两个键node_mirror负责Node二进制包的下载地址npm_mirror负责npm官方包的下载地址剩下的就是把活跃可用的地址填进去。你只要理解了这句话以后任何镜像变化都难不住你。我个人在实际操作中的体会是环境工具的安装90%的问题都出在“旧环境没有清干净”和“新环境没有刷新PATH”这两件事上。许多人陷入反复卸载重装的循环真正的原因其实特别简单。所以如果你今天装完还是有问题不要急着把nvm卸载冷静下来按第6节的三个方向慢慢排查大概率能在一个小时内解决。
