2026/9/9 11:48:11
FEATURED · 精选文章 
你是不是也遇到过这种场景项目本地跑得好好的突然就报了一行Node.js not found你决定把 Node.js 卸载重装结果控制面板里点了卸载重装完一敲node -v依然提示“找不到命令”。问题几乎不在安装步骤而在卸载没卸干净。Node.js 和普通软件不一样它会在系统里留下安装目录、全局包、缓存、环境变量等多个“分身”任何一个没清掉重装后的环境都是半残状态。这篇把 Node.js 的卸载和安装掰开揉碎地讲清楚不同安装方式分别怎么卸、哪些残留必须手动清、环境变量怎么修、装完该怎么验证、遇到not found这类报错怎么排查。不管你是刚入门的小白还是被 Mac/Linux/Windows 环境折腾过无数次的老手都能在这里找到对应的操作。我的目标很朴素让你能干净卸载并装上一个长期稳定、不折腾的新环境。1. 卸载之前先搞清楚Node.js到底在你机器上装了什么1.1 Node.js、npm、全局包和缓存四件套很多人以为 Node.js 就是一个node.exe卸载就是把那个文件夹删了。实际上一套完整的 Node.js 环境至少包含四类东西Node.js 运行时本体Windows 下默认在C:\Program Files\nodejsmacOS/Linux 下可能是/usr/local/bin/node、/usr/bin/node或者某个版本管理器的专属目录。npm 及 npx、corepack 等命令行工具通常跟随 Node 一起装进系统目录负责管理依赖、执行脚本。全局 npm 包你用npm install -g装过的工具比如yarn、nodemon、typescript、nest都放在全局目录Windows 下一般是C:\Users\你的用户名\AppData\Roaming\npmmacOS/Linux 下一般是/usr/local/lib/node_modules或 nvm 管理的对应目录。缓存和配置文件npm 缓存目录在 Windows 下是C:\Users\你的用户名\AppData\Local\npm-cache在 macOS/Linux 下是~/.npm另外还有.npmrc、.node_repl_history、.node-gyp这类配置文件分散在用户主目录里。这四部分分布在完全不同的位置只删一个地方根本卸不干净。尤其全局包和缓存它们才是重装后各种“奇怪报错”的源头。比如全局包还在但全局目录里的node解释器被卸载了你敲nodemon就会提示脚本无法运行缓存里存了旧依赖快照新装的 npm 可能会继续读取导致npm install依然报过期错误。1.2 为什么要“彻底”卸载而不是直接删文件夹直接删安装目录的后果我见过很多次主要有三个环境变量里的旧路径不会自动消失。新装的 Node.js 装到新路径后系统路径里可能还残留旧路径导致执行node -v时调用的还是旧版或者干脆找不到。全局命令和旧的 node.exe 分离。比如你以前把全局包装在%APPDATA%\npm卸载后这个目录还在里面的.cmd脚本会尝试调用一个已经不在的 node等于留下了一堆坏掉的快捷方式。缓存、配置里的旧状态会干扰新环境。比如.npmrc里残留了老的 registry 地址或 prefix 配置新装的 npm 读到的还是旧配置你怎么改都没用。所以我把“彻底”两个字当成整个流程的底线。动手卸载之前先别急不要想着“赶紧卸完赶紧重装”耐心按下面的分类一步一步来。2. Windows下的完整卸载链路程序卸载、残留清理、环境变量修复2.1 从“卸载程序”和安装器入手Windows 上最不推荐的方式是直接删C:\Program Files\nodejs文件夹。Node.js 的安装包通常是 MSI 格式Windows Installer 在系统里登记了大量信息如果你直接暴力删除注册表里会留下残缺记录之后重装时可能出现“另一个安装程序正在运行”或者“已安装同版本”的提示。正确的第一步是从“设置 - 应用 - 安装的应用”里找到 Node.js点击卸载或者打开旧版“控制面板 - 程序和功能”卸载。卸载过程中如果提示文件被占用先关掉所有终端、VSCode、WebStorm再打开任务管理器把所有node.exe进程结束掉然后重新卸载。如果你当初不是用官方安装包而是用以下方式装的卸载入口也不一样安装方式卸载命令/入口官方 MSI 安装包设置 - 应用 - Node.js - 卸载Chocolateychoco uninstall nodejswingetwinget uninstall OpenJS.NodeJSnvm-windowsnvm uninstall 版本号再卸载 nvm 本身绿色版/zip 手动解压没有卸载程序只能手动删除目录再清理环境变量其中 nvm-windows 的情况比较特殊。如果你用nvm install装过多个版本每个版本其实是放在 nvm 的安装目录下的比如D:\nvm\v20.11.0。卸载时先nvm uninstall 版本号确认版本列表空了以后再从“设置 - 应用”里卸载 nvm 工具本身。但即使这样nvm 的缓存和临时文件仍然可能残留在%APPDATA%\nvm或%LOCALAPPDATA%\nvm需要手动删除。2.2 清理npm缓存、全局安装目录和用户目录残留很多人在程序列表里把 Node.js 卸掉就觉得自己已经卸载完了。其实卸载程序只删除它安装时写入的文件你后来通过 npm 安装的全局模块、缓存它一概不管。这一步必须手动处理。建议打开文件资源管理器把地址栏路径粘贴进去逐一确认C:\Program Files\nodejs如果卸载后还存在直接删除。C:\Users\你的用户名\AppData\Roaming\npm全局模块目录。如果你确认以后不再需要这些全局工具整个删。C:\Users\你的用户名\AppData\Roaming\npm-cache老版本 npm 的缓存目录删。C:\Users\你的用户名\AppData\Local\npm-cache新版 npm 的缓存目录删。C:\Users\你的用户名\.npmrcnpm 配置文件不需要就删。C:\Users\你的用户名\.node_repl_historyNode REPL 历史记录可删。C:\Users\你的用户名\.node-gyp原生模块编译缓存删。删除的时候如果提示文件被占用多半是某些全局命令还在后台运行比如yarn、nodemon、tsc。打开任务管理器搜索名字全部结束进程再来一次。这里我建议你在卸载前先用npm ls -g --depth0把全局包列表导出一份避免后面重装时忘了自己装过什么。2.3 注册表与“已安装同版本”的坑怎么处理卸载步骤走完后还有一个很多人容易忽略的地方注册表残留。某些 MSI 安装的软件卸载后注册表项不一定都清干净。你重装时如果遇到“Node.js is already installed”或者“Another version is already installed”十有八九是注册表里还有旧版本信息。在Win R里输入regedit打开注册表编辑器重点查看HKEY_CURRENT_USER\Software\Node.jsHKEY_LOCAL_MACHINE\SOFTWARE\Node.jsHKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Node.js如果存在先右键导出备份再删除。不要只删一个就跑三个位置都检查一遍。不过手动编辑注册表对新手不友好推荐先装一个 Geek Uninstaller 或者 Revo Uninstaller 这类工具他们能在卸载主程序后扫描文件系统和注册表残留把和 Node.js 相关的项列出来你勾选确认后删除比手动regedit安全得多。说到底这个思路和清理一些“你以为卸载干净、其实后台还在运行”的软件是一样的。很多工具类的软件卸载后还会留下服务、计划任务、配置文件Node.js 虽然没有服务但注册表和环境变量残留一样会闹脾气。2.4 清理系统环境变量别让旧路径残留最后一个重点环境变量。打开“系统属性 - 高级 - 环境变量”检查上下两个Path列表。系统 Path 里常见残留项C:\Program Files\nodejs\。用户 Path 里常见残留项C:\Users\你的用户名\AppData\Roaming\npm。这两个都删掉。另外还要检查有没有NODE_PATH这个系统变量或用户变量如果存在也删掉。很多人重装之后出现“npm 不是内部或外部命令”就是因为只删了旧的C:\Program Files\nodejs忘了用户 Path 里还留着一个旧全局目录新装的 npm 和旧路径对不上。改完环境变量一定要把已经打开的终端窗口、IDE 全部关掉再重新打开。Windows 的环境变量是在进程启动时读取的你不重开终端等于没改。如果重启后还是有问题再检查一下系统变量和用户变量的 Path 顺序不要出现两个 node 路径同时存在的情况。3. macOS和Linux平台的卸载各家有各家的坑3.1 macOS从pkg安装包卸载的官方姿势如果你是从官方下载的.pkg安装包装的 Node.js那它默认写在/usr/local目录下。问题是macOS 的 pkg 安装程序一般不会生成“应用程序”图标所以你在“应用程序”文件夹里找不到卸载入口。只能手动删文件。先确认一下 node 的位置which node ls -l /usr/local/bin/node如果/usr/local/bin/node是真实文件不是符号链接可以执行sudo rm -rf /usr/local/bin/node sudo rm -rf /usr/local/bin/npm sudo rm -rf /usr/local/bin/npx sudo rm -rf /usr/local/lib/node_modules sudo rm -rf /usr/local/include/node sudo rm -rf /usr/local/share/doc/node sudo rm -rf /usr/local/share/man/man1/node.1如果ls -l显示这是一个符号链接指向~/.nvm/versions/node/...那千万不要执行上面的删除命令说明你实际是用 nvm 装的要去 3.4 节看 nvm 的卸载方式。删完系统目录后再清理用户主目录里的缓存和配置rm -rf ~/.npm rm -rf ~/.node-gyp rm -rf ~/.npmrc rm -rf ~/.node_repl_history rm -rf ~/Library/Caches/node还有一点旧版 pkg 安装包可能在/Library/Receipts里写安装记录。如果你希望系统完全忘记旧版本可以在/Library/Receipts里搜索node相关的.pkg文件如果有一并删掉。这个步骤不是必须但会影响后续 pkg 安装时是否提示已安装。3.2 使用Homebrew安装的Node.js如何干净卸载Homebrew 装的 Node.js卸载很简单brew uninstall --ignore-dependencies node brew cleanup注意--ignore-dependencies不要省略。Homebrew 在安装 node 时可能顺带装了icu4c等依赖如果直接brew uninstall nodeHomebrew 会把这种“不再被依赖”的库也删掉万一其他工具也在用就麻烦了。所以先只删 node之后确认系统里没有其他工具需要那些依赖再执行brew autoremove。Homebrew 卸载后/usr/local/Cellar/node和/usr/local/opt/node一般会自动清理但~/.npm和~/.node-gyp仍然要手动删。另外如果你用 Homebrew 安装过nvm建议把它也卸掉换成官方脚本安装方式。Homebrew 版 nvm 在升级和维护上经常出问题很多“nvm 命令找不到”的情况都是 Homebrew 版引起的。3.3 Linux发行版的卸载apt、dnf、源码安装三路并讲Debian/Ubuntu 系用 apt 安装的 Node.jssudo apt-get remove nodejsremove会保留配置文件如果想把配置也删掉sudo apt-get purge nodejs sudo apt-get autoremove如果你之前是通过 NodeSource 的源安装的卸载后建议把/etc/apt/sources.list.d/nodesource.list也删掉否则每次apt update都会访问一个已经没有使用的源。同时可以检查一下/etc/apt/keyrings/nodesource.gpg是否残留一并删除。RedHat/CentOS/Fedora 系sudo dnf remove nodejs老版本用sudo yum remove nodejs。如果你是从源码编译安装的卸载方式是在解压源码的目录里执行sudo make uninstall前提是你还留着当时下载的源码目录并且版本和已安装的版本一致。如果源码目录已经不在了只能手动删除常见路径sudo rm -rf /usr/local/bin/node /usr/local/bin/npm /usr/local/bin/npx sudo rm -rf /usr/local/lib/node_modules sudo rm -rf /usr/local/include/node无论用哪种包管理器安装最后都别忘了清理用户目录rm -rf ~/.npm ~/.node-gyp ~/.npmrc ~/.node_repl_history3.4 nvm或fnm这类版本管理工具管理的Node.js怎么卸如果你用了 nvm 或 fnm 这类版本管理器卸载逻辑就完全不一样了。不要让系统的包管理器去卸载 Node否则 nvm 的符号链接会指向一个不存在的路径天天报错。macOS/Linux 的 nvm卸某个 Node 版本nvm uninstall 18.19.0如果要把 nvm 本身也删掉顺序很重要先nvm deactivate解除当前版本然后删除~/.nvm目录再打开~/.bashrc或~/.zshrc把里面和 nvm 相关的加载语句删干净export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh最后重开终端执行command -v nvm没有输出就说明清理干净了。fnm 也是类似先fnm uninstall 版本号然后删除 shell 配置里的eval $(fnm env)再删除~/.local/share/fnm数据目录。如果你用了n这个轻量版本管理工具卸载方式则是sudo n rm 版本号或手动删除/usr/local/n目录。总而言之先搞清自己是用什么装的再决定动手路线这是卸载阶段最重要的一句话。4. 从零开始安装Node.js官方包、版本管理器和包管理器的选择4.1 官方安装包和LTS/Current到底选哪个全新安装时选对版本比安装本身更重要。官方下载页会给你两个选择LTS长期支持版和Current最新特性版。我的建议非常明确日常开发选 LTS。LTS 版本是 Node.js 官方承诺长期维护的版本稳定性和兼容性都经过大量项目验证。Current版本一般只适合尝鲜或者某个工具明确要求新特性时才用。你在生产环境里、公司项目里、写教程里都优先选 LTS能少踩 90% 的坑。Windows 下载.msimacOS 下载.pkgLinux 可以选择二进制压缩包或者直接用发行版自带的包管理器安装。安装时 Windows 的 MSI 向导会问你是否“自动安装必要的工具”如果你没有装过 Python 和 Visual Studio Build Tools建议勾选。很多原生模块在npm install时需要通过 node-gyp 编译没有本地构建工具链会直接报错。如果你已经装了 VS Code、Git、Python那可以不勾但要注意后续若出现python not found或者MSBuild相关的报错还是要回来补装。4.2 使用nvm-windows实现多版本切换如果你经常同时维护多个项目一个用 Node 14一个用 Node 20那不建议用官方安装包直接用 nvm-windows 管理。下载nvm-setup.exe安装到D:\nvm这种纯英文无空格的目录。装完后打开终端先看可用版本nvm list available然后安装、切换nvm install 20.11.0 nvm install 18.19.0 nvm use 20.11.0nvm list可以看当前已安装的版本带*的是当前使用的版本。如果nvm use之后切换不生效检查一下是不是没有执行nvm onnvm-windows 有nvm on/off两个状态只有on时才接管 Node 版本。还可以通过nvm alias default 20.11.0设置默认版本这样新开终端时会自动使用指定版本。用 nvm-windows 有一个非常关键的原则不要再用npm config set prefix去改 npm 全局目录。nvm-windows 的全局包是放在每个 Node 版本自己的目录下的你自定义 prefix 之后切换版本时全局命令经常找不到排查起来极其痛苦。以后要装全局工具就在确定版本后npm install -g 包名直接装简单粗暴。4.3 macOS/Linux下的nvm和fnm安装配置macOS/Linux 上最流行的还是 nvm。官方安装方式curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完脚本会自动往~/.zshrc或~/.bashrc里写入加载代码。如果新开终端后nvm命令找不到手动把下面这两行加进去export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh然后source ~/.zshrc或重开终端。安装 Nodenvm install --lts nvm use --lts nvm ls如果你所在网络访问官方下载源很慢可以设置镜像export NVM_NODEJS_ORG_MIRRORhttps://npmmirror.com/mirrors/node/也可以把这一行直接写进 shell 配置文件里让 nvm 每次下载都走镜像。实测下来速度提升明显。如果你喜欢更快、支持自动切换.nvmrc的版本管理器可以试试 fnm。它用 Rust 写的启动速度快但配置稍微复杂一点。安装后需要在 shell 配置里加eval $(fnm env)然后fnm install 20、fnm default 20。个人建议不想折腾就用 nvm想追求速度再考虑 fnm。4.4 配置npm全局目录和国内镜像避免后续踩坑安装完 Node.js 后别急着跑项目先做几个很基础但很关键的配置。第一步查看当前配置npm config get prefix npm config get cache npm config get registry第二步设置镜像。如果你在国内默认的https://registry.npmjs.org/速度可能会很慢可以用 npmmirrornpm config set registry https://registry.npmmirror.com/这个命令会把配置写进~/.npmrc对所有项目生效。当某个包在镜像上同步不及时临时用官方源装一次就好npm install 包名 --registryhttps://registry.npmjs.org/第三步关于全局目录。如果你用的是官方安装包且想把全局包从 C 盘移走可以用npm config set prefix D:\nodejs\node_global但改完之后记得把D:\nodejs\node_global加进系统 Path否则npm install -g安装的命令无法直接执行。如果你用的是 nvm 或 fnm这一步反而不要做理由前面已经说过。全局目录这种设置能不动就不动只靠 npm 默认目录大多数情况下最省心。5. 安装后的第一轮体检版本号、环境变量、全局命令的全链路验证5.1 node -v / npm -v 好使不等于环境就对了很多人在新终端里看到node -v输出了版本号就以为大功告成。其实这只是最基础的一步。完整的体检至少要执行这些命令node -v npm -v npx -v which node # Windows 用 where node which npm # Windows 用 where npm npm config get registry npm root -g以 Windows 为例where node必须只输出当前新装的路径如果出现了多个路径说明环境变量里还有旧残留。npm root -g应该指向一个实际的全局 node_modules 目录而不是不存在的路径。更严谨的做法是写一个测试脚本验证实际执行路径// test.js console.log(process.version); console.log(process.platform); console.log(process.execPath);然后运行node test.js。如果process.execPath显示的是你新装的路径才算真正通过。这一步能提前发现很多环境配置问题尤其是那些“明明node -v对但工具里还是调用旧版”的诡异情况。5.2 经典报错node 不是内部或外部命令也不是可运行的程序这个报错基本可以锁定到环境变量问题。具体分三种情况刚装完还没重开终端。Windows 的终端进程启动时读取环境变量所以请把所有终端、IDE、VS Code 全部关掉再重新打开。Path 里根本没有 Node.js 安装目录。手动把C:\Program Files\nodejs\加到系统 Path 或用户 Path注意路径和反斜杠别写错。安装路径包含中文或空格导致某些脚本解析异常。这种情况只能卸载重装到纯英文路径。还有一个隐藏场景你用了 nvm-windows但当前没有激活任何版本。执行nvm list看看列表里有没有带*的版本如果没有nvm use 版本号再试。如果nvm list提示没有安装任何版本先nvm install 版本号。macOS/Linux 上如果node提示 command not found先执行which node确认路径如果 nvm 输出的node路径是你nvm use之前的老路径检查 shell 配置加载顺序确保 nvm 初始化语句在 PATH 设置之后。5.3 npm install 卡住不动、报错ERESOLVE、node not found的处理思路重装环境后第一件事往往是npm install但这一步最容易暴露问题。如果你发现npm install卡在sill idealTree buildDeps这种阶段很久不动大概率是网络问题或者 npm 缓存损坏。先执行npm cache verify然后把 registry 切回国内镜像删除项目里的node_modules和package-lock.json重新npm install。如果还不行检查一下是不是某个依赖下载地址被卡住了可以单独设置代理或走镜像。如果是ERESOLVE unable to resolve dependency tree这是 npm 7 之后对 peerDependencies 检查变严格导致的依赖冲突。临时解法是先跑npm install --legacy-peer-deps但这个只是临时绕过不是根本解决。长期来看要升级冲突的包或者让依赖版本对齐。如果你看到ERR! Error: not found: python这类消息说明系统缺少原生模块编译工具链需要按操作系统的标准方式安装 Python 和 C 编译工具。还有一种“Node.js not found但node -v明明有输出”的情况。这通常发生在 IDE 内置终端里编辑器是在你重装 Node 之前启动的内部终端也继承了旧的环境变量。解决方式很简单重启编辑器。如果重启后还不行检查编辑器设置里是否指定了某个固定的 Node 路径改成自动检测或指向新路径。6. 从卸载到重装我建议你这样安排工作流给菜鸟的最终建议6.1 记录当前项目依赖和全局工具清单动手卸载之前请先给自己留五分钟把当前环境完整记录下来。不要高估记忆力重装完以后你大概率想不起来自己装过哪些全局包。执行npm ls -g --depth0把输出保存到一个文本文件里或者截图。如果你用 Yarn另外
Node.js 彻底卸载与重装指南：清理残留、修复环境变量
你是不是也遇到过这种场景项目本地跑得好好的突然就报了一行Node.js not found你决定把 Node.js 卸载重装结果控制面板里点了卸载重装完一敲node -v依然提示“找不到命令”。问题几乎不在安装步骤而在卸载没卸干净。Node.js 和普通软件不一样它会在系统里留下安装目录、全局包、缓存、环境变量等多个“分身”任何一个没清掉重装后的环境都是半残状态。这篇把 Node.js 的卸载和安装掰开揉碎地讲清楚不同安装方式分别怎么卸、哪些残留必须手动清、环境变量怎么修、装完该怎么验证、遇到not found这类报错怎么排查。不管你是刚入门的小白还是被 Mac/Linux/Windows 环境折腾过无数次的老手都能在这里找到对应的操作。我的目标很朴素让你能干净卸载并装上一个长期稳定、不折腾的新环境。1. 卸载之前先搞清楚Node.js到底在你机器上装了什么1.1 Node.js、npm、全局包和缓存四件套很多人以为 Node.js 就是一个node.exe卸载就是把那个文件夹删了。实际上一套完整的 Node.js 环境至少包含四类东西Node.js 运行时本体Windows 下默认在C:\Program Files\nodejsmacOS/Linux 下可能是/usr/local/bin/node、/usr/bin/node或者某个版本管理器的专属目录。npm 及 npx、corepack 等命令行工具通常跟随 Node 一起装进系统目录负责管理依赖、执行脚本。全局 npm 包你用npm install -g装过的工具比如yarn、nodemon、typescript、nest都放在全局目录Windows 下一般是C:\Users\你的用户名\AppData\Roaming\npmmacOS/Linux 下一般是/usr/local/lib/node_modules或 nvm 管理的对应目录。缓存和配置文件npm 缓存目录在 Windows 下是C:\Users\你的用户名\AppData\Local\npm-cache在 macOS/Linux 下是~/.npm另外还有.npmrc、.node_repl_history、.node-gyp这类配置文件分散在用户主目录里。这四部分分布在完全不同的位置只删一个地方根本卸不干净。尤其全局包和缓存它们才是重装后各种“奇怪报错”的源头。比如全局包还在但全局目录里的node解释器被卸载了你敲nodemon就会提示脚本无法运行缓存里存了旧依赖快照新装的 npm 可能会继续读取导致npm install依然报过期错误。1.2 为什么要“彻底”卸载而不是直接删文件夹直接删安装目录的后果我见过很多次主要有三个环境变量里的旧路径不会自动消失。新装的 Node.js 装到新路径后系统路径里可能还残留旧路径导致执行node -v时调用的还是旧版或者干脆找不到。全局命令和旧的 node.exe 分离。比如你以前把全局包装在%APPDATA%\npm卸载后这个目录还在里面的.cmd脚本会尝试调用一个已经不在的 node等于留下了一堆坏掉的快捷方式。缓存、配置里的旧状态会干扰新环境。比如.npmrc里残留了老的 registry 地址或 prefix 配置新装的 npm 读到的还是旧配置你怎么改都没用。所以我把“彻底”两个字当成整个流程的底线。动手卸载之前先别急不要想着“赶紧卸完赶紧重装”耐心按下面的分类一步一步来。2. Windows下的完整卸载链路程序卸载、残留清理、环境变量修复2.1 从“卸载程序”和安装器入手Windows 上最不推荐的方式是直接删C:\Program Files\nodejs文件夹。Node.js 的安装包通常是 MSI 格式Windows Installer 在系统里登记了大量信息如果你直接暴力删除注册表里会留下残缺记录之后重装时可能出现“另一个安装程序正在运行”或者“已安装同版本”的提示。正确的第一步是从“设置 - 应用 - 安装的应用”里找到 Node.js点击卸载或者打开旧版“控制面板 - 程序和功能”卸载。卸载过程中如果提示文件被占用先关掉所有终端、VSCode、WebStorm再打开任务管理器把所有node.exe进程结束掉然后重新卸载。如果你当初不是用官方安装包而是用以下方式装的卸载入口也不一样安装方式卸载命令/入口官方 MSI 安装包设置 - 应用 - Node.js - 卸载Chocolateychoco uninstall nodejswingetwinget uninstall OpenJS.NodeJSnvm-windowsnvm uninstall 版本号再卸载 nvm 本身绿色版/zip 手动解压没有卸载程序只能手动删除目录再清理环境变量其中 nvm-windows 的情况比较特殊。如果你用nvm install装过多个版本每个版本其实是放在 nvm 的安装目录下的比如D:\nvm\v20.11.0。卸载时先nvm uninstall 版本号确认版本列表空了以后再从“设置 - 应用”里卸载 nvm 工具本身。但即使这样nvm 的缓存和临时文件仍然可能残留在%APPDATA%\nvm或%LOCALAPPDATA%\nvm需要手动删除。2.2 清理npm缓存、全局安装目录和用户目录残留很多人在程序列表里把 Node.js 卸掉就觉得自己已经卸载完了。其实卸载程序只删除它安装时写入的文件你后来通过 npm 安装的全局模块、缓存它一概不管。这一步必须手动处理。建议打开文件资源管理器把地址栏路径粘贴进去逐一确认C:\Program Files\nodejs如果卸载后还存在直接删除。C:\Users\你的用户名\AppData\Roaming\npm全局模块目录。如果你确认以后不再需要这些全局工具整个删。C:\Users\你的用户名\AppData\Roaming\npm-cache老版本 npm 的缓存目录删。C:\Users\你的用户名\AppData\Local\npm-cache新版 npm 的缓存目录删。C:\Users\你的用户名\.npmrcnpm 配置文件不需要就删。C:\Users\你的用户名\.node_repl_historyNode REPL 历史记录可删。C:\Users\你的用户名\.node-gyp原生模块编译缓存删。删除的时候如果提示文件被占用多半是某些全局命令还在后台运行比如yarn、nodemon、tsc。打开任务管理器搜索名字全部结束进程再来一次。这里我建议你在卸载前先用npm ls -g --depth0把全局包列表导出一份避免后面重装时忘了自己装过什么。2.3 注册表与“已安装同版本”的坑怎么处理卸载步骤走完后还有一个很多人容易忽略的地方注册表残留。某些 MSI 安装的软件卸载后注册表项不一定都清干净。你重装时如果遇到“Node.js is already installed”或者“Another version is already installed”十有八九是注册表里还有旧版本信息。在Win R里输入regedit打开注册表编辑器重点查看HKEY_CURRENT_USER\Software\Node.jsHKEY_LOCAL_MACHINE\SOFTWARE\Node.jsHKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Node.js如果存在先右键导出备份再删除。不要只删一个就跑三个位置都检查一遍。不过手动编辑注册表对新手不友好推荐先装一个 Geek Uninstaller 或者 Revo Uninstaller 这类工具他们能在卸载主程序后扫描文件系统和注册表残留把和 Node.js 相关的项列出来你勾选确认后删除比手动regedit安全得多。说到底这个思路和清理一些“你以为卸载干净、其实后台还在运行”的软件是一样的。很多工具类的软件卸载后还会留下服务、计划任务、配置文件Node.js 虽然没有服务但注册表和环境变量残留一样会闹脾气。2.4 清理系统环境变量别让旧路径残留最后一个重点环境变量。打开“系统属性 - 高级 - 环境变量”检查上下两个Path列表。系统 Path 里常见残留项C:\Program Files\nodejs\。用户 Path 里常见残留项C:\Users\你的用户名\AppData\Roaming\npm。这两个都删掉。另外还要检查有没有NODE_PATH这个系统变量或用户变量如果存在也删掉。很多人重装之后出现“npm 不是内部或外部命令”就是因为只删了旧的C:\Program Files\nodejs忘了用户 Path 里还留着一个旧全局目录新装的 npm 和旧路径对不上。改完环境变量一定要把已经打开的终端窗口、IDE 全部关掉再重新打开。Windows 的环境变量是在进程启动时读取的你不重开终端等于没改。如果重启后还是有问题再检查一下系统变量和用户变量的 Path 顺序不要出现两个 node 路径同时存在的情况。3. macOS和Linux平台的卸载各家有各家的坑3.1 macOS从pkg安装包卸载的官方姿势如果你是从官方下载的.pkg安装包装的 Node.js那它默认写在/usr/local目录下。问题是macOS 的 pkg 安装程序一般不会生成“应用程序”图标所以你在“应用程序”文件夹里找不到卸载入口。只能手动删文件。先确认一下 node 的位置which node ls -l /usr/local/bin/node如果/usr/local/bin/node是真实文件不是符号链接可以执行sudo rm -rf /usr/local/bin/node sudo rm -rf /usr/local/bin/npm sudo rm -rf /usr/local/bin/npx sudo rm -rf /usr/local/lib/node_modules sudo rm -rf /usr/local/include/node sudo rm -rf /usr/local/share/doc/node sudo rm -rf /usr/local/share/man/man1/node.1如果ls -l显示这是一个符号链接指向~/.nvm/versions/node/...那千万不要执行上面的删除命令说明你实际是用 nvm 装的要去 3.4 节看 nvm 的卸载方式。删完系统目录后再清理用户主目录里的缓存和配置rm -rf ~/.npm rm -rf ~/.node-gyp rm -rf ~/.npmrc rm -rf ~/.node_repl_history rm -rf ~/Library/Caches/node还有一点旧版 pkg 安装包可能在/Library/Receipts里写安装记录。如果你希望系统完全忘记旧版本可以在/Library/Receipts里搜索node相关的.pkg文件如果有一并删掉。这个步骤不是必须但会影响后续 pkg 安装时是否提示已安装。3.2 使用Homebrew安装的Node.js如何干净卸载Homebrew 装的 Node.js卸载很简单brew uninstall --ignore-dependencies node brew cleanup注意--ignore-dependencies不要省略。Homebrew 在安装 node 时可能顺带装了icu4c等依赖如果直接brew uninstall nodeHomebrew 会把这种“不再被依赖”的库也删掉万一其他工具也在用就麻烦了。所以先只删 node之后确认系统里没有其他工具需要那些依赖再执行brew autoremove。Homebrew 卸载后/usr/local/Cellar/node和/usr/local/opt/node一般会自动清理但~/.npm和~/.node-gyp仍然要手动删。另外如果你用 Homebrew 安装过nvm建议把它也卸掉换成官方脚本安装方式。Homebrew 版 nvm 在升级和维护上经常出问题很多“nvm 命令找不到”的情况都是 Homebrew 版引起的。3.3 Linux发行版的卸载apt、dnf、源码安装三路并讲Debian/Ubuntu 系用 apt 安装的 Node.jssudo apt-get remove nodejsremove会保留配置文件如果想把配置也删掉sudo apt-get purge nodejs sudo apt-get autoremove如果你之前是通过 NodeSource 的源安装的卸载后建议把/etc/apt/sources.list.d/nodesource.list也删掉否则每次apt update都会访问一个已经没有使用的源。同时可以检查一下/etc/apt/keyrings/nodesource.gpg是否残留一并删除。RedHat/CentOS/Fedora 系sudo dnf remove nodejs老版本用sudo yum remove nodejs。如果你是从源码编译安装的卸载方式是在解压源码的目录里执行sudo make uninstall前提是你还留着当时下载的源码目录并且版本和已安装的版本一致。如果源码目录已经不在了只能手动删除常见路径sudo rm -rf /usr/local/bin/node /usr/local/bin/npm /usr/local/bin/npx sudo rm -rf /usr/local/lib/node_modules sudo rm -rf /usr/local/include/node无论用哪种包管理器安装最后都别忘了清理用户目录rm -rf ~/.npm ~/.node-gyp ~/.npmrc ~/.node_repl_history3.4 nvm或fnm这类版本管理工具管理的Node.js怎么卸如果你用了 nvm 或 fnm 这类版本管理器卸载逻辑就完全不一样了。不要让系统的包管理器去卸载 Node否则 nvm 的符号链接会指向一个不存在的路径天天报错。macOS/Linux 的 nvm卸某个 Node 版本nvm uninstall 18.19.0如果要把 nvm 本身也删掉顺序很重要先nvm deactivate解除当前版本然后删除~/.nvm目录再打开~/.bashrc或~/.zshrc把里面和 nvm 相关的加载语句删干净export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh最后重开终端执行command -v nvm没有输出就说明清理干净了。fnm 也是类似先fnm uninstall 版本号然后删除 shell 配置里的eval $(fnm env)再删除~/.local/share/fnm数据目录。如果你用了n这个轻量版本管理工具卸载方式则是sudo n rm 版本号或手动删除/usr/local/n目录。总而言之先搞清自己是用什么装的再决定动手路线这是卸载阶段最重要的一句话。4. 从零开始安装Node.js官方包、版本管理器和包管理器的选择4.1 官方安装包和LTS/Current到底选哪个全新安装时选对版本比安装本身更重要。官方下载页会给你两个选择LTS长期支持版和Current最新特性版。我的建议非常明确日常开发选 LTS。LTS 版本是 Node.js 官方承诺长期维护的版本稳定性和兼容性都经过大量项目验证。Current版本一般只适合尝鲜或者某个工具明确要求新特性时才用。你在生产环境里、公司项目里、写教程里都优先选 LTS能少踩 90% 的坑。Windows 下载.msimacOS 下载.pkgLinux 可以选择二进制压缩包或者直接用发行版自带的包管理器安装。安装时 Windows 的 MSI 向导会问你是否“自动安装必要的工具”如果你没有装过 Python 和 Visual Studio Build Tools建议勾选。很多原生模块在npm install时需要通过 node-gyp 编译没有本地构建工具链会直接报错。如果你已经装了 VS Code、Git、Python那可以不勾但要注意后续若出现python not found或者MSBuild相关的报错还是要回来补装。4.2 使用nvm-windows实现多版本切换如果你经常同时维护多个项目一个用 Node 14一个用 Node 20那不建议用官方安装包直接用 nvm-windows 管理。下载nvm-setup.exe安装到D:\nvm这种纯英文无空格的目录。装完后打开终端先看可用版本nvm list available然后安装、切换nvm install 20.11.0 nvm install 18.19.0 nvm use 20.11.0nvm list可以看当前已安装的版本带*的是当前使用的版本。如果nvm use之后切换不生效检查一下是不是没有执行nvm onnvm-windows 有nvm on/off两个状态只有on时才接管 Node 版本。还可以通过nvm alias default 20.11.0设置默认版本这样新开终端时会自动使用指定版本。用 nvm-windows 有一个非常关键的原则不要再用npm config set prefix去改 npm 全局目录。nvm-windows 的全局包是放在每个 Node 版本自己的目录下的你自定义 prefix 之后切换版本时全局命令经常找不到排查起来极其痛苦。以后要装全局工具就在确定版本后npm install -g 包名直接装简单粗暴。4.3 macOS/Linux下的nvm和fnm安装配置macOS/Linux 上最流行的还是 nvm。官方安装方式curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完脚本会自动往~/.zshrc或~/.bashrc里写入加载代码。如果新开终端后nvm命令找不到手动把下面这两行加进去export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh然后source ~/.zshrc或重开终端。安装 Nodenvm install --lts nvm use --lts nvm ls如果你所在网络访问官方下载源很慢可以设置镜像export NVM_NODEJS_ORG_MIRRORhttps://npmmirror.com/mirrors/node/也可以把这一行直接写进 shell 配置文件里让 nvm 每次下载都走镜像。实测下来速度提升明显。如果你喜欢更快、支持自动切换.nvmrc的版本管理器可以试试 fnm。它用 Rust 写的启动速度快但配置稍微复杂一点。安装后需要在 shell 配置里加eval $(fnm env)然后fnm install 20、fnm default 20。个人建议不想折腾就用 nvm想追求速度再考虑 fnm。4.4 配置npm全局目录和国内镜像避免后续踩坑安装完 Node.js 后别急着跑项目先做几个很基础但很关键的配置。第一步查看当前配置npm config get prefix npm config get cache npm config get registry第二步设置镜像。如果你在国内默认的https://registry.npmjs.org/速度可能会很慢可以用 npmmirrornpm config set registry https://registry.npmmirror.com/这个命令会把配置写进~/.npmrc对所有项目生效。当某个包在镜像上同步不及时临时用官方源装一次就好npm install 包名 --registryhttps://registry.npmjs.org/第三步关于全局目录。如果你用的是官方安装包且想把全局包从 C 盘移走可以用npm config set prefix D:\nodejs\node_global但改完之后记得把D:\nodejs\node_global加进系统 Path否则npm install -g安装的命令无法直接执行。如果你用的是 nvm 或 fnm这一步反而不要做理由前面已经说过。全局目录这种设置能不动就不动只靠 npm 默认目录大多数情况下最省心。5. 安装后的第一轮体检版本号、环境变量、全局命令的全链路验证5.1 node -v / npm -v 好使不等于环境就对了很多人在新终端里看到node -v输出了版本号就以为大功告成。其实这只是最基础的一步。完整的体检至少要执行这些命令node -v npm -v npx -v which node # Windows 用 where node which npm # Windows 用 where npm npm config get registry npm root -g以 Windows 为例where node必须只输出当前新装的路径如果出现了多个路径说明环境变量里还有旧残留。npm root -g应该指向一个实际的全局 node_modules 目录而不是不存在的路径。更严谨的做法是写一个测试脚本验证实际执行路径// test.js console.log(process.version); console.log(process.platform); console.log(process.execPath);然后运行node test.js。如果process.execPath显示的是你新装的路径才算真正通过。这一步能提前发现很多环境配置问题尤其是那些“明明node -v对但工具里还是调用旧版”的诡异情况。5.2 经典报错node 不是内部或外部命令也不是可运行的程序这个报错基本可以锁定到环境变量问题。具体分三种情况刚装完还没重开终端。Windows 的终端进程启动时读取环境变量所以请把所有终端、IDE、VS Code 全部关掉再重新打开。Path 里根本没有 Node.js 安装目录。手动把C:\Program Files\nodejs\加到系统 Path 或用户 Path注意路径和反斜杠别写错。安装路径包含中文或空格导致某些脚本解析异常。这种情况只能卸载重装到纯英文路径。还有一个隐藏场景你用了 nvm-windows但当前没有激活任何版本。执行nvm list看看列表里有没有带*的版本如果没有nvm use 版本号再试。如果nvm list提示没有安装任何版本先nvm install 版本号。macOS/Linux 上如果node提示 command not found先执行which node确认路径如果 nvm 输出的node路径是你nvm use之前的老路径检查 shell 配置加载顺序确保 nvm 初始化语句在 PATH 设置之后。5.3 npm install 卡住不动、报错ERESOLVE、node not found的处理思路重装环境后第一件事往往是npm install但这一步最容易暴露问题。如果你发现npm install卡在sill idealTree buildDeps这种阶段很久不动大概率是网络问题或者 npm 缓存损坏。先执行npm cache verify然后把 registry 切回国内镜像删除项目里的node_modules和package-lock.json重新npm install。如果还不行检查一下是不是某个依赖下载地址被卡住了可以单独设置代理或走镜像。如果是ERESOLVE unable to resolve dependency tree这是 npm 7 之后对 peerDependencies 检查变严格导致的依赖冲突。临时解法是先跑npm install --legacy-peer-deps但这个只是临时绕过不是根本解决。长期来看要升级冲突的包或者让依赖版本对齐。如果你看到ERR! Error: not found: python这类消息说明系统缺少原生模块编译工具链需要按操作系统的标准方式安装 Python 和 C 编译工具。还有一种“Node.js not found但node -v明明有输出”的情况。这通常发生在 IDE 内置终端里编辑器是在你重装 Node 之前启动的内部终端也继承了旧的环境变量。解决方式很简单重启编辑器。如果重启后还不行检查编辑器设置里是否指定了某个固定的 Node 路径改成自动检测或指向新路径。6. 从卸载到重装我建议你这样安排工作流给菜鸟的最终建议6.1 记录当前项目依赖和全局工具清单动手卸载之前请先给自己留五分钟把当前环境完整记录下来。不要高估记忆力重装完以后你大概率想不起来自己装过哪些全局包。执行npm ls -g --depth0把输出保存到一个文本文件里或者截图。如果你用 Yarn另外 
