Node.js 的安装和卸载听起来是入门第一课但我处理过的开发机多了之后才发现恰恰是这个“最基础”的环节翻车率最高。版本选错、装到一半报错、npm 全局包删不干净、卸载完发现系统里全是残留目录每一件都足够让人折腾到怀疑人生。这篇内容我把自己这些年装 Node.js、卸 Node.js 的经验全部捋一遍覆盖 Windows 和 Ubuntu 两套主流环境把 npm 全局包卸载、残留清理、版本不存在的报错这类高频问题一次说透。不管你是刚入门前端的小白还是要给服务器配置运行环境的运维同学都能从中找到可以直接照做的方案。1. 动手之前先把版本选择这件事搞懂1.1 版本号不只是数字LTS 和 Current 的区别Node.js 的版本号是有隐藏信息的主版本号是奇数还是偶数决定了这个版本的生命周期定位。偶数主版本比如 18、20、22会进入长期维护阶段也就是大家常说的 LTS奇数主版本比如 19、21、23更多是实验性更新只维护几个月就会被放弃。所以生产环境、公司项目、重要的工具链一律选 LTS别用奇数版本去赌稳定性。Node.js 官方同时会维护多个 LTS 版本。以我写作时的情况来说20 已经是相当成熟的 LTS22 也进入了 LTS 序列而 24 这类较新版本还在快速迭代阶段。日常个人开发或者给小型项目搭建环境直接用 20 或 22 都是很稳的选择只有当你确实需要某个新特性才去考虑 Current 版本。热词里出现了一条典型的错误信息error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava...这类报错十有八九就是版本号搞错了。Node.js 的版本发布节奏是固定的不是所有次要版本号都会出现。比如你可能想装 24.x 的最新版但官方只发到了 19.0你手一抖填了 24.21.0nvm 自然找不到这个版本。后面我会专门讲这个问题的排查思路。1.2 三条安装路线选哪条最合适我见过很多人一上来就问“怎么装 Node.js”但这个问题背后其实是三种完全不同的需求。我用一张表把常见路线整理清楚安装方式适用场景版本新鲜度卸载干净程度适合谁官方二进制包 / MSI服务器部署、临时使用高可指定版本一般需手动清理追求简单直接的人nvm / fnm 版本管理日常开发、多项目并行高切版本非常方便高一条命令即可卸载前端、后端开发人员apt / 系统包管理器Ubuntu/Debian 快速装低源里的版本偏旧好但版本太旧不太在意版本的懒人如果你是纯后端服务部署对多版本切换没需求那官方二进制包解压就能用非常干净。但你是在自己电脑上长期写代码我强烈建议用版本管理器因为项目之间依赖的 Node 版本经常不一样老项目要 14新项目要 20用 nvm 只在当前 shell 里切换一下就完成了不用反复卸载重装。第三条 apt 路线要提醒一句Ubuntu 默认源里的 nodejs 包通常非常旧这是很多人都踩过的大坑。我见过不少人在 Ubuntu 上敲了sudo apt install nodejs装完发现版本还是 12.x然后一脸懵地来问为什么装不了新特性。用系统源装之前先查一下源里的版本能不能满足需求再做决定。2. Ubuntu 上安装 Node.js 20推荐两条路线2.1 方法一官方二进制包手动但很干净这一招适合服务器或者临时环境全程用 wget 加 tar 就能完成。首先去 Node.js 官网的下载页面找到 linux-x64 的 .tar.xz 包把链接复制下来然后执行cd /tmp wget https://nodejs.org/dist/v20.16.0/node-v20.16.0-linux-x64.tar.xz sudo tar -xJf node-v20.16.0-linux-x64.tar.xz -C /usr/local/lib/解压之后目录结构是这样的/usr/local/lib/node-v20.16.0-linux-x64/bin/node。接下来要做两件事一是把可执行目录加入 PATH二是把 include 和 lib 路径告诉系统避免以后编译 native 模块时找不到头文件。sudo vim ~/.bashrc在文件底部加上export NODE_HOME/usr/local/lib/node-v20.16.0-linux-x64 export PATH$NODE_HOME/bin:$PATH保存后执行source ~/.bashrc然后验证node -v npm -v这里有两个细节要提醒。第一如果你已经有系统自带的 node在/usr/bin/node而你的 PATH 里/usr/local/lib/node-v20.16.0-linux-x64/bin在前面那么node -v会优先显示新版本但其它工具链可能还会去扫/usr/bin/node容易出现混乱。最好把旧版先卸载或者用 update-alternatives 统一管理。第二后面你通过 npm 安装全局包时会面临权限问题建议不要把全局前缀设在/usr/local以外的系统目录而且不要用 sudo npm否则权限错乱会让你怀疑人生。因为使用官方二进制方式时 npm 会写全局包到/usr/local/lib/node_modules普通用户没有写权限所以很多教程会让你加 sudo我个人的习惯是在服务器上把 npm 全局目录切到用户目录下比如npm config set prefix ~/.npm-global再把~/.npm-global/bin加入 PATH这样就不用碰 sudo 了。2.2 方法二nvm 多版本管理强烈推荐如果你在 Ubuntu 上是做开发的直接上 nvm。安装命令很简单curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash这里的版本号会变装之前建议看一下当前 release 是多少。执行完成之后nvm 会往你的~/.bashrc里写入一段初始化脚本重新打开终端或者手动 source 一下source ~/.bashrc验证是否装好command -v nvm然后安装 Node.js 20nvm install 20 nvm use 20 nvm alias default 20nvm install 20会自动解析当前 20.x 的最新版本号装完后立刻可用。nvm alias default 20的意思是以后每次打开新终端都默认使用 20这一步很多人会漏掉结果下次重开终端发现 node 又不见了。nvm 有一个好处是卸载也极度爽快nvm uninstall 20一键清理干净不会在系统目录里留一堆文件。缺点是新 shell 里第一次跑 node 会稍微慢一点因为 nvm 要切换路径但这一点延时几乎可以忽略。如果机器上还没有编译工具链后面用 npm 装一些需要编译原生模块的包时会报 python/gcc/make 缺失的错误建议提前装好sudo apt update sudo apt install -y build-essential python32.3 方法三NodeSource 仓库apt 也能装新版本有时候就是不想折腾只想apt install nodejs一把梭。但前面说了Ubuntu 官方源里的版本通常很旧所以这时候可以用 NodeSource 提供的仓库它会把 NodeSource 的源加入系统然后你会通过 apt 装到较新版本。官方推荐脚本curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs这个脚本执行过程中会添加 NodeSource 的 apt 源并更新系统源列表然后 apt install 就能装到 20.x。相比手动解压用 apt 装的另一个好处是卸载简单sudo apt remove nodejs再清理 apt 源列表即可。要注意 setup_20.x 里的 20 也可以改成 18、22按需选择。不过 NodeSource 仓库的包更新速度和官方会有几周延时追求极致最新版本的话还是用 nvm。3. Windows 下的安装流程看着简单但藏着几个坑3.1 MSI 安装全流程Windows 装机最简单的方式是去 Node.js 官网下载 LTS 版本的 MSI 安装包。下载后双击一路 Next唯一要留意的是默认界面里的 “Add to PATH” 选项默认是勾选的务必保持勾选。安装完成后打开一个新的 cmd 或 PowerShell 窗口一定要重开旧窗口读不到新环境变量执行node -v npm -v如果能正常输出版本号说明装好了。这里有一个很多新手搞不懂的逻辑为什么安装时明明勾选了 Add to PATH但有时候命令行还是提示找不到 node这是因为 PATH 环境变量的修改只在新的进程里生效。你已经开着的旧终端窗口还是用旧的环境变量列表只有重新打开终端才会读到新的配置。所以但凡遇到装完软件后命令找不到第一件事就是重开终端别急着怀疑装坏了。3.2 装完就踩坑的三个细节第一个坑是中文用户名或者带空格路径。Windows 下如果你当前系统的用户目录是C:\Users\张三npm 安装全局包时会在这个路径下面创建目录某些原生模块的编译脚本对非 ASCII 路径支持很差就会报莫名其妙的长串错误。遇到这个问题最省事的办法是新建一个英文名用户或者在装 Node 时把安装路径改到纯英文目录比如D:\Nodejs。第二个坑是 MSI 安装也分用户级和系统级。如果你是在公司电脑上装没有管理员权限MSI 可能会选择用户级安装结果全局包都装在%APPDATA%\npm下之后换用户或者提升权限时会发现全局包“消失”了。这不是什么 bug是安装级别不同导致的。第三个坑是多版本管理。Windows 上没有真正的 nvm-sh但有 nvm-windows 和 fnm。如果你需要同时维护多个版本的 Node我建议用 fnm它速度更快用法和 nvm 类似fnm install 20 fnm use 20这里提醒一句市面上称为“nvm”的工具其实有两个完全不同的项目一个是给 Unix 系统用的 nvm-sh另一个是给 Windows 用的 nvm-windows两者不通用别混着看文档会越看越晕。3.3 Windows 卸载时的残留重灾区Windows 卸载 Node.js 的麻烦程度比 Linux 高得多因为软件卸载工具只会删掉安装目录里的主文件而 npm 在你用户目录里塞的一大堆东西它根本不管。卸载 Node.js 的正确基本动作是在控制面板卸载程序但卸载完并不算完。接下来需要手动清理以下几处C:\Program Files\nodejs如果卸载后还残留就手动删%APPDATA%\npm全局包的主要存放位置%APPDATA%\npm-cachenpm 缓存目录%USERPROFILE%\.npmrcnpm 配置文件%USERPROFILE%\.node-gyp编译原生模块时使用的缓存和头文件然后在系统环境变量的 PATH 里把 Node.js 程序目录和npm相关的条目删掉。这里操作时要注意别一顺手把别的东西也删了PATH 里可能有上百条路径我只建议删掉那些明确包含 nodejs、npm 字样的条目其他的尽量别动。注册表不建议新手手动碰容易把系统搞出问题。对比一下就会明白Windows 上卸载工具类软件时大家遇到的“残留”问题思路其实是一模一样的除了卸载程序本身还要清理它写进你用户目录和环境变量里的东西。4. npm 全局包装得下也最好卸得干净4.1 先学会查看全局包很多初学者只把 Node.js 当成一个运行环境装了之后就开始用 npm 一顿狂装全局包比如npm install -g typescript、npm install -g pnpm结果过了几个月自己都忘了电脑上装了哪些全局命令想卸载也不知道从哪下手。先把查看全局包的命令先记住npm list -g --depth0这条命令会列出你当前全局安装的顶层包不显示依赖树。想看这些包实际存放在哪里可以执行npm root -g以 Windows 为例常见路径是C:\Users\你的用户名\AppData\Roaming\npm\node_modulesUbuntu 上用 nvm 的话路径则是~/.nvm/versions/node/v20.x.x/lib/node_modules。4.2 卸载全局包的正确姿势卸载全局包的正确命令是npm uninstall -g 包名比如我之前装了 typescript那卸载就是npm uninstall -g typescript这里有个问题被反复问到“我能不能直接把node_modules里的那个包目录删掉”我的建议是如果你不想给自己找麻烦就不要这么做。npm 维护的全局目录里不止有包文件还有各种 bin 链接、目录结构记录。直接删目录会让 npm 的后续操作判断出错其它依赖这个包的全局工具可能瞬间变成不可用状态你再跑npm list -g也会发现记录里还挂着残缺的包名整体状态非常脏。另外提醒一个我已经踩过的坑以前为了省 C 盘空间我把 npm 的全局目录挪到了别的盘npm config set prefix D:\somewhere结果所有全局命令全部失效tsc、pnpm之类的都找不到。原因很简单shell 里的 PATH 还指向旧的%APPDATA%\npm而真实的 bin 已经被我挪走了。改 prefix 不是不行但必须把新的目录重新加进 PATH并且旧目录里的残留要清理两个坑叠在一起新手很容易在中间状态里陷进去。4.3 卸载 npm 缓存与残留除了全局包文件npm 缓存也值得提一句。一般情况下你不用手动清缓存但如果卸载时想把 Node.js 相关的数据清干净可以执行npm cache clean --force或者更温和一点先看缓存有效性npm cache verify缓存目录在 Windows 是%APPDATA%\npm-cacheUbuntu 是~/.npm。如果系统里已经没有 Node.js直接把这两个目录删掉也完全没问题它们就是纯粹的缓存数据保存的是一些已经下载过的 tarball 包删了下次需要时会重新下载。5. 卸载 Node.js把残留问题一次解决5.1 Windows 卸载完整流程卸载 Node.js核心不是把程序删掉而是把所有相关的目录和环境变量一并清理。我在 3.3 节只列了路径这节把动作串成完整流程。第一步控制面板里卸载 Node.js。第二步手动删除以下目录C:\Program Files\nodejs%APPDATA%\npm%APPDATA%\npm-cache%LOCALAPPDATA%\Temp\npm-*临时文件可能有一堆以 npm 开头的缓存目录第三步删除用户目录下的配置文件%USERPROFILE%\.npmrc%USERPROFILE%\.node-gyp第四步编辑环境变量。打开系统设置里的“编辑系统环境变量”在“用户变量”和“系统变量”的 PATH 中删掉包含 nodejs、npm、%APPDATA%\npm的条目。注意看清楚路径再动手别把C:\Windows\System32这类系统路径误删了。5.2 Linux 卸载完整流程Linux 下卸载 Node.js 取决于安装方式。如果你用的是官方二进制包解压方式卸载就是把目录删掉同时清理 PATH 里的条目。找到你当初解压到的目录比如/usr/local/lib/node-v20.16.0-linux-x64然后sudo rm -rf /usr/local/lib/node-v20.16.0-linux-x64再编辑~/.bashrc把里面 NODE_HOME 相关的几行删掉。这时再执行node -v如果还在输出版本号说明系统里还有其它地方的 node用which node查一下真实位置。如果你当初做过软链接那还要清理/usr/bin/node里的软链。如果你用的是 nvm 安装卸载会更干净nvm uninstall 20这一条命令会把对应版本的 Node.js 连同它的全局包一起删除。如果你连 nvm 本身都不想要了卸载所有 Node 版本后再删掉~/.nvm目录并从.bashrc里移除 nvm 初始化脚本。如果是 apt 装的sudo apt remove nodejs npm sudo apt autoremove如果你当初用了 NodeSource 仓库还要清理对应的源列表sudo rm /etc/apt/sources.list.d/nodesource.list sudo apt update5.3 验证卸载是否彻底卸载完不要直接关机先用命令验证一下node -v npm -v系统提示command not found说明当前 shell 里已经找不到 node 和 npm 了。但如果命令还能输出版本号尝试重新打开一个终端再测一次因为当前 shell 里的 PATH 可能还残存旧的环境变量。还有一种隐蔽情况你已经删除了 nodejs 程序但node命令来自另一个程序比如某些 IDE 自带了一个 Node runtime 并把它的路径写进了 PATH这时候which node能帮你定位到具体路径。6. 真实报错排查版本不存在、PATH 混乱和权限冲突6.1 “v24.21.0 is not yet released”这类版本错误这条报错描述的其实是“想装一个官方还没发布的版本”。通常发生在 nvm 或某些脚本尝试安装具体版本号时。如果你手动填了一个官方版本列表里不存在的版本工具就会提示该版本尚未发布。对策也很简单不要凭感觉写版本号先查官方到底发布到了哪个版本。在 Linux 上用 nvm 的话可以这样列出所有可安装的远程版本nvm ls-remote屏幕上会列出很长一串版本找到需要的大版本下最新的那个即可。想要直接装某个大版本的最新版也只需要nvm install 20nvm 会自动解析。也可以直接去 Node.js 官网查看官方发布节奏以官网发布的版本列表为准。这类问题的根源就是“版本号是动态的不能靠猜”。6.2 PATH 混乱装了新版但 node -v 还是旧版这种问题在 Linux 上最常见。你用官方二进制包装了 Node 20也改了~/.bashrc但执行node -v时还是显示老的版本。先用这条命令定位which node它会告诉你 shell 实际调用的 node 程序路径。如果输出的是/usr/bin/node说明新旧版的路径都在 PATH 里但旧版路径排在前面。解决思路有几种把新版本路径往前放直接卸载旧版或者干脆用 nvm让 nvm 管理 PATH从根上避免这种混乱。Windows 上也有类似情况装了新版本但 PowerShell 里还是旧版。检查一下用户变量和系统变量里是否同时存在两个 nodejs 目录把旧版从 PATH 里删掉重开终端。6.3 权限报错npm install -g 总在报 EACCESEACCES: permission denied是 Linux 和 macOS 上非常常见的 npm 报错。原因是 npm 想朝/usr/lib/node_modules之类系统目录写入但当前用户没有写权限。很多人第一反应是sudo npm install -g xxx这个操作短期内能用但全局包被 root 写入后普通用户下次想卸载或者更新时又会被权限卡住形成恶性循环。我的建议很简单不要用 sudo 去运行 npm而是用 nvm 管理 Node.js。nvm 安装的 Node 都在用户目录下npm 全局目录也在用户目录下根本不存在系统目录写入权限问题一劳永逸。6.4 常见问题速查表现象原因解决方案node -v找不到命令Node.js 未安装或 PATH 未生效重开终端若刚装完检查安装时是否勾选 Add to PATHnode -v显示旧版本新旧版本路径都在 PATH 里用which node/where node定位调整 PATH 顺序npm 全局包无法执行目录被搬家但 PATH 没更新删除旧 PATH 条目把新 npm 全局目录加入 PATHnpm install -g 报 EACCES全局目录在系统目录当前用户无写权限安装 nvm 后重装 Node避免 sudo npmnvm 提示版本不存在版本号写错或未发布先用nvm ls-remote查可用版本再安装卸载后 node 还能执行卸载不彻底或其它软件自带 Node执行which node/where node定位并清理我在实际处理各种开发机时最深的体会是安装和卸载 Node.js 最难的地方不在于“执行命令”而在于“用一致的方式管理环境”。不要今天用 apt 装一个明天用二进制包覆盖后天又冒出来一个残留的旧版本最后 PATH 里乱成一锅粥。其实无论 Windows 还是 Ubuntu选一个版本管理器固定下来以后安装、切换、卸载都是一条命令的事这也算是我在做完整环境清理之后越来越认可的一条经验。还有就是遇到问题先看npm list -g、which node、node -v这三条命令的输出再动手改所有安装卸载问题基本都能顺藤摸瓜解决。