以前我在Windows上装Node.js，第一反应都是去官网下载msi安装包，下一步下一步装完收工。后来项目一多，问题就来了：老项目要用Node 14，新项目要用Node 20，某个工程的lock文件版本对不上，每次build都在报错边缘疯狂试探；想升级Node，又怕把另一个正在跑的旧项目搞挂。更烦的是，卸载重装Node.js并不干净，PATH、npm缓存、全局工具链一堆残留，清理起来能把人逼疯。后来我换用nvm管理Node.js，感觉整个人都清爽了。
这篇指南就围绕Windows下用nvm安装与管理Node.js展开，从工具选型、下载配置，到具体切换版本、管理npm全局依赖，再到我踩过的各种报错和排查过程，全流程梳理一遍。适合刚接触Node.js的新手，也适合被多项目版本冲突折腾过好几次、想彻底理顺开发环境的前端和全栈开发者。看完照做，基本能少走一半弯路。
1. 内容整体设计与思路拆解
1.1 痛点：Node.js版本切换到底有多折腾
先聊一个很实际的问题：Node.js版本为什么要来回切？
我遇到过的典型场景有这么几种。第一种，老项目依赖某个原生模块，比如node-sass，它跟Node版本强绑定，Node 16以后编译直接报错，项目只能跑在Node 14上。第二种，公司内部脚手架或者CI环境锁定了Node版本，本地版本不一致，就会出现"我在我电脑上跑得好好的"这种经典甩锅局。第三种，新框架要求Node 18+，但电脑里只有一个旧版Node，升级也不是，不升也不是。
在没有nvm的时候，大家通常的做法是：下载对应版本的msi安装包，卸载旧版，再装新版。这套操作看起来还行，但坑特别多。卸载不干净会导致PATH里残留旧路径，npm全局包全部丢失，全局工具链要重装，而且整个流程至少十分钟起步。最尴尬的是，有时候两个项目并行开发，一个要14，一个要20，这种情况靠安装包根本没法优雅解决。
nvm的作用就是解决这个问题：在一台机器上同时安装多个Node.js版本，用一条命令迅速切换。它不会污染系统环境，也不会让全局包来回失效（虽然切换版本时全局包确实会跟着版本走，这点后面会细说）。一句话总结：nvm就是Node开发环境里的"版本管理开关"。
1.2 lvm、npm、Node.js三兄弟的关系，以及lvm-windows的特殊性
先把几个概念理清楚。
Node.js是JavaScript的运行时，负责让JavaScript在服务端跑起来。npm是Node.js自带的包管理器，用来安装和管理依赖包。nvm英文全称是Node Version Manager，专门管理Node.js版本的工具。
在macOS和Linux上，大家用的nvm是一个基于shell脚本的版本管理工具，它通过修改shell环境变量来切换Node版本。但在Windows上，情况有点不同：官方并没有直接维护Windows版本的nvm，我们常用的nvm-windows是一个第三方开源项目，由Corey Butler维护，用Go语言实现。
很多人第一次用nvm-windows时，会下意识地把它当成Linux版nvm的移植版，命令看着差不多（install、use、list都有），但底层原理完全不同。Linux版的nvm是通过修改当前shell会话的PATH来实现切换，每次开新终端都要重新source。Windows版的nvm-windows则是通过一个符号链接（symlink）来切换版本：安装时它会创建一个指向当前使用版本的"替身目录"，切换版本时重新指向另一个版本的目录。
这个差异直接决定了后面很多问题的排查方向。比如Windows下nvm命令必须在管理员权限下运行，因为创建符号链接需要系统权限；比如无论你安装多少版本，你实际访问的Node路径永远是同一个符号链接目录；再比如如果你之前用msi安装过Node.js，残留的PATH路径会和nvm的符号链接冲突，导致版本切换后node -v还是旧版本。理解这些，后面遇到问题才不会被表象带偏。
2. nvm-windows 安装与基础配置
2.1 下载安装：安装目录别带空格，也别装到C盘根目录
nvm-windows的安装包在GitHub的Release页面里，我会选择nvm-setup.zip这个安装包。解压后运行nvm-setup.exe，安装界面会问你两个路径：一个是nvm本身的安装目录，比如D:\nvm；另一个是Node.js符号链接的存放目录，默认是C:\Program Files\nodejs，我建议改成D:\nvm\nodejs，这样整个Node环境都收拢在一个盘符下，后续清理也方便。
安装时有两个必须避开的坑。
第一，安装目录不要带空格。D:\Program Files\nvm这种路径在后续执行某些脚本时会出莫名其妙的问题，比如settings.txt解析失败、npm命令找不到等。第二，不要直接装到C盘根目录。倒不是说不能装，而是Windows系统盘权限管控严格，会有各种UAC弹窗，而且nvm切换版本时需要频繁读写目录，放在系统盘容易触发权限问题。
安装完成后，系统环境变量里会自动增加两个变量：NVM_HOME（指向nvm安装目录）和NVM_SYMLINK（指向符号链接目录）。这两个变量是nvm正常工作的基础。
如果你喜欢用命令行，也可以通过winget安装：
winget install CoreyButler.NVMforWindows装完之后，打开一个全新的终端窗口，输入下面命令验证：
nvm version如果能输出版本号，说明安装成功。如果提示"不是内部或外部命令"，大概率是环境变量没生效，新开一个终端窗口或者直接重启电脑再看。
2.2 settings.txt：镜像源与版本列表的隐藏入口
安装完nvm后，打开D:\nvm目录，里面有个settings.txt文件。这个文件是nvm-windows的配置文件，默认内容大概是这样的：
root: D:\nvm path: D:\nvm\nodejs arch: 64 proxy: none node_mirror: https://nodejs.org/dist/ npm_mirror: https://github.com/npm/cli/archive/几个关键字段的作用我逐个说一下。
root是nvm自身目录，path是符号链接目录，安装时已经配置好，一般不用动。arch是架构，64位机器保持64即可。proxy是代理设置，国内直连一般不用改。真正需要关注的是最后两个镜像地址。
默认的node_mirror指向Node.js官网，安装新版本时会去官方源下载，在国内网络环境下速度极其感人。我通常会把它换成npmmirror（原淘宝镜像）提供的Node镜像：
node_mirror: https://npmmirror.com/mirrors/node/这样执行nvm install时，下载速度会提升好几个量级。
还有一个容易被忽略的点：node_mirror只影响Node.js二进制的下载地址，不影响npm的下载源。npm源的配置是另一套逻辑，后面我会单独说。
修改settings.txt后，记得新开一个终端窗口再执行nvm命令，因为nvm在启动时会读取这个配置文件，如果你的终端环境有缓存，可能导致修改不生效。
3. Node.js 安装、双版本切换与全局配置
3.1 核心三命令：nvm list、nvm install、nvm use
安装完nvm后，第一步先看看已有的Node版本，执行：
nvm list刚装完时应该只有一个空列表。接着查看当前可安装的版本：
nvm list available这个命令会输出一大串版本号，标记为Latest的表示当前最新版。如果你想装一个指定的LTS版本，比如Node 20，直接执行：
nvm install 20.11.0如果想安装最新稳定版，可以这样：
nvm install latest安装过程会显示下载进度条，完成后会有类似Installation complete的提示。但注意，nvm-windows安装完不会自动切换到新版本，必须手动执行：
nvm use 20.11.0执行后输出Now using node v20.11.0 (64-bit)，再验证一下：
node -v npm -v输出版本号就说明当前环境已经生效。
这里有个细节我一开始也困惑过：为什么nvm install之后还要手动nvm use？因为nvm-windows默认把"安装"和"激活"当成两个独立动作。也许你装了三个版本，但只想用其中一个，所以需要手动指定。如果想让某个版本成为默认，执行：
nvm alias default 20.11.0这样新开终端时会自动加载这个版本。
切换版本的实际效果是：D:\nvm\nodejs这个符号链接目录会指向D:\nvm\v20.11.0或D:\nvm\v18.19.0。你可以运行下面命令验证：
where node输出路径如果指向D:\nvm\nodejs\node.exe，就说明它是通过符号链接访问的。
3.2 npm 全局安装与全局目录配置
Node.js装好了，npm也自带了，但开发中我们经常要装一些全局工具，比如pnpm、yarn、nodemon、http-server等。
在nvm-windows环境下，有个很多人没注意到的特性：你在某个Node版本下安装的npm全局包，只属于那个版本。当你切换到另一个Node版本时，那些全局包并不会跟着过去。
举个例子：
nvm use 20.11.0 npm install -g pnpm然后切换到另一个版本：
nvm use 18.19.0 pnpm -v大概率会提示"pnpm不是内部或外部命令"。这是因为npm的全局安装目录跟在特定Node版本的目录下，路径类似D:\nvm\v20.11.0\node_modules。
解决这个问题有两种思路。
第一种，切换版本后重新安装全局包。简单粗暴，但每次切换都要折腾一遍，很烦。第二种，配置独立的全局目录，让所有版本共享一套全局包。我比较推荐在D:\nvm下单独建一个node_global目录，然后执行：
npm config set prefix "D:\nvm\node_global" npm config set cache "D:\nvm\node_cache"然后修改系统环境变量PATH，把D:\nvm\node_global加进去，这样全局命令就能在任何Node版本下被识别。
不过这么配置也有个隐患：某个全局包如果包含原生模块（需要针对特定Node版本编译），在共享目录下可能无法跨版本使用。好在现在大部分流行工具都是纯JavaScript实现，跨版本问题不大。实际项目中我会优先给pnpm这类高频工具配置共享目录，其余包按需安装。
这里再提一下nvm install pnpm这个不少热词里出现过的场景。严格来说，pnpm不应该用nvm install安装，因为nvm只负责Node版本管理，不负责包管理工具安装。正确方式有两个：
npm install -g pnpm或者更推荐的corepack方式（新版本Node自带）：
corepack enable corepack prepare pnpm@latest --activate用corepack的好处是pnpm版本跟随项目工具链走，不会因为全局共享目录而互相污染。
3.3 搭配 nrm 管理npm源
nvm解决了Node版本问题，但还没解决npm源问题。npm默认源是官方源，国内直连经常超时，所以大多数国内开发者的习惯是换源。
我常用的方案是nrm，它是npm registry manager，一条命令切换各种npm源。安装方式：
npm install -g nrm查看当前源：
nrm ls输出会列出npm、yarn、tencent、taobao等若干源，带*的是当前使用的。切换到淘宝源：
nrm use taobao以后npm install就会走淘宝源，速度明显提升。
也有人不喜欢多装一个工具，更简单的做法是直接设置npm的registry：
npm config set registry https://registry.npmmirror.com两种方式殊途同归。区别在于，nrm可以随时切换、对比各源状态，而npm config set registry是硬改配置，适合长期固定一个源的情况。我一般两种都保留，团队项目要求用私有源时，用nrm一键切回。
注意：换源后对已有项目缓存没有影响，但新装的依赖会走新源。如果某个依赖包在新源上同步不及时，可以临时切回官方源试一下，这个坑我真实遇到过。
第4部分我先讲讲环境变量和PATH的底层原理，因为它直接决定了后面各种踩坑的方向。
4. 环境变量与 PATH 的底层原理
4.1 符号链接机制：nvm-windows 到底做了什么
很多教程只说命令，不说原理。我觉得原理必须讲清楚，否则遇到报错只能瞎猜。
nvm-windows的整个工作逻辑都围绕一个符号链接展开。安装时，它会在D:\nvm\nodejs创建一个符号链接目录；当你执行nvm use 20.11.0时，它会删除这个链接，并重新指向D:\nvm\v20.11.0。目录本身没有变，只是背后指向的"实际目录"变了。
可以这样理解：D:\nvm\nodejs就像一个"快捷方式"，你通过这个快捷方式访问的永远是当前激活的Node版本。node -v、npm -v之所以能工作，是因为系统的PATH环境变量里加入了D:\nvm\nodejs。
这也是为什么nvm切换版本时需要管理员权限：创建和删除符号链接在Windows下需要管理员权限。如果你不是在管理员权限下运行的终端，执行nvm use时会看到权限错误，或者在PowerShell里提示"请求的操作需要提升"。
一个很典型的场景：你用普通模式打开了VS Code，然后在VS Code内置终端里执行nvm use，可能直接失败。解决办法很简单，用管理员身份打开VS Code或Windows Terminal。如果不想每次手动提权，可以设置终端快捷键属性里的"以管理员身份运行"。
4.2 PATH顺序与残留路径的冲突
PATH环境变量是个列表，系统从上到下找到第一个匹配的可执行文件就执行。nvm正常运行的前提是D:\nvm\nodejs在PATH中出现的顺序要足够靠前。
如果之前用msi方式安装过Node.js，系统PATH里会残留C:\Program Files\nodejs\。当这个路径排在nvm之前时，即使nvm use切换成功了，执行node -v也可能还是旧版本，因为系统先找到了旧路径下的node.exe。这个问题极其隐蔽，表面看起来像是nvm没生效，实际是PATH顺序在捣乱。
排查方法很简单，打开命令行，执行：
where node这个命令会输出系统按PATH顺序找到的所有node.exe路径。如果第一行不是你期望的D:\nvm\nodejs\node.exe，那就要调整PATH顺序，或者手动删除旧版Node相关的路径。
另外一个常见问题是：安装nvm之后，如果同时安装了某个非nvm管理的Node版本，也会造成同样的冲突。所以我的建议是：如果你决定使用nvm，那就把之前安装的Node.js彻底卸载干净，包括PATH残留、npm全局目录、AppData下的npm缓存等。混用nvm和独立安装的Node，是很多环境问题的最初来源。
这里有一个细节：Windows的PATH环境变量分为系统变量和用户变量。nvm安装时一般把相关路径写到系统变量里，而用户变量如果含有C:\Users\你的用户名\AppData\Roaming\npm，也可能影响全局命令的解析。如果你发现npm全局命令时好时坏，可以同时检查这两个位置的PATH。
5. 常见问题与排查技巧实录
5.1 切换版本后 node -v 没反应，或者提示"不是内部或外部命令"
这个问题我见过太多次了。先按顺序排查：
第一步，确认nvm是否真的切换成功。执行nvm list，看当前版本前面是否有*。
第二步，检查PATH环境变量。确保NVM_HOME和NVM_SYMLINK对应的目录都在PATH里，且D:\nvm\nodejs在旧版node路径之前。如果发现PATH里没有这两个变量，手动添加后重启终端。
第三步，检查终端是否重新打开过。Windows的环境变量修改后，已经打开的终端不会自动刷新，必须新开窗口。
如果以上三步都没问题，再检查符号链接本身是否存在。打开文件资源管理器，看D:\nvm\nodejs目录是不是一个带有"文件夹快捷方式"图标的链接。如果这个链接被误删，node命令也会失效，可以执行nvm use 当前版本号重新触发一次链接创建。
5.2 PowerShell 禁止运行脚本：claude.exe 一执行就报错
现在AI编程工具很流行，比如Claude Code这类工具，安装后会在全局node_modules下生成一个.exe。有朋友在nvm环境下执行claude命令，遇到了类似这样的报错：
无法将“F:\nvm\nodejs/node_modules/@anthropic-ai/claude-code/bin/claude.exe”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。或者另一个版本：
无法加载文件 ...，因为在此系统上禁止运行脚本。这大概率不是nvm的问题，而是PowerShell的执行策略（ExecutionPolicy）限制。Windows默认对本地脚本和命令执行有安全限制，尤其是PowerShell环境下，很多时候ExecutionPolicy被设置为Restricted。
解决办法是修改当前用户的执行策略：
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned执行后会提示是否确认更改，输入Y回车。然后再跑claude或者nvm use这类涉及脚本或符号链接内exe的命令，就正常了。
这里顺便说一句：如果你用的是CMD而不是PowerShell，大概率不会遇到这个报错，因为CMD没有ExecutionPolicy概念。所以很多人出现"在CMD里能跑，在PowerShell里跑不了"的现象，就是这个原因。
5.3 nvm install 报错 "is not yet released or is not available"
有段时间我执行nvm install 20.11.0时，nvm直接输出：
v20.11.0 is not yet released or is not available.我当时有点懵，明明这个版本已经发布很久了。后来查了nvm-windows的源码逻辑才明白：nvm-windows在安装版本时，会先请求一次Node官方版本列表，然后和你要安装的版本号做比对；如果nvm自身版本太老，它可能拉取不到最新列表，就会误判版本不存在。
解决方法是先升级nvm到最新版本，然后执行一次nvm list available刷新版本列表。如果这一步正常输出了大量版本号，再重新nvm install。如果list available本身就报错或者输出为空，那就是网络问题，检查settings.txt里的node_mirror是否配置正确。
还有一个细节：nvm install后面跟的版本号不要带小版本就省略。比如你想装20.11.0，就得写全20.11.0，不能只写20。当然，20写法在nvm较新版本里也支持，但为了保险，我更推荐写完整版本号。
5.4 Node 18 运行时报错：the requested module 'node:util' does not provide an export named ...
这个报错我是在某个老项目升级Node到18后碰到的，运行测试时直接抛：
the requested module 'node:util' does not provide an export named 'parseEnv'直接原因：某个依赖包里用了node:util的某个方法，但它的版本太旧，在Node 18这个版本上，模块内部的导出结构发生了变化，ESM模块解析时找不到对应的命名导出。
排查思路是先看报错堆栈里指向哪个模块，然后去升级那个模块。比如这类问题常见于dotenv、commander、semver等库的旧版本，升级到新版本就能解决。如果升级后还是不行，再用npm ls 模块名查看依赖树，确认是否有多处嵌套依赖都引用了旧版本，必要时用npm overrides强制覆盖。
这个案例的启发是：Node版本升级后，不要只关心应用代码，还要留意依赖树里隐式的内建模块导出变化。这也是为什么nvm可以做版本切换但不保证所有项目都能无缝切换的原因。
5.5 pnpm 全局命令找不到，安装完失效
在nvm环境下，pnpm这个工具特别容易出问题，因为它的全局安装目录和npm的全局目录不是同一个概念。
我推荐的方式是：如果你用corepack，先执行corepack enable，然后直接用corepack prepare pnpm@latest --activate。如果这样安装后pnpm命令还是找不到，可能是corepack生成的shim目录没有加到PATH里。
如果你用的是传统方式npm install -g pnpm，装完之后可以通过npm root -g看一下全局目录路径。在nvm环境下，这个目录通常绑定在某个具体Node版本下。切换版本后找不到命令，很正常，要么切回原版本，要么配置共享全局目录，要么用corepack重新激活一次。
另一个值得注意的点：有些项目里会用到.npmrc文件来配置shamefully-hoist=true或node-linker，这些配置和pnpm版本有关。如果切了Node版本导致pnpm版本变化，可能会出现安装行为不一致的情况，所以建议在项目里锁定pnpm版本。
下面放一个我实际排查过的错误示例，方便对照：
| 现象 | 原因 | 解决 |
|---|---|---|
nvm use提示需要管理员权限 | Windows创建符号链接需要提权 | 用管理员身份打开终端 |
node -v还是旧版本 | PATH中旧Node路径靠前 | where node排查，调整PATH顺序 |
nvm install提示版本不可用 | nvm版本过旧或镜像拉取失败 | 升级nvm，检查node_mirror |
| PowerShell 禁止运行某全局命令 | ExecutionPolicy限制 | Set-ExecutionPolicy -Scope CurrentUser RemoteSigned |
| 切换版本后全局包丢失 | npm全局包跟随Node版本 | 配置共享全局目录或重新安装 |
| pnpm命令找不到 | corepack shim路径未加到PATH | 检查PATH，用corepack enable重新激活 |
5.6 卸载残留与目录清理
最后说一个很多人忽略的问题：nvm用久了，D:\nvm下会堆积大量已安装的Node版本，每个版本都有完整的node_modules和npm缓存，占空间不说，还容易冲突。
清理方式很直接。先列出所有版本：
nvm list删除不需要的版本：
nvm uninstall 16.14.0这个命令会删除对应版本目录。注意，nvm uninstall不支持删除当前正在使用的版本，需要先nvm use切到其他版本再删。
还有一类残留是npm缓存。npm的缓存目录默认在C:\Users\用户名\AppData\Local\npm-cache，时间久了可能几个G。清缓存用：
npm cache clean --force如果不用nvm了，想彻底卸载，步骤是：先nvm uninstall所有版本，再在安装程序里卸载nvm本体，最后手动删除环境变量里的NVM_HOME、NVM_SYMLINK，以及PATH里的相关路径。不要直接删文件夹，因为符号链接和权限信息会残留，可能影响后续安装。
最后分享一个我自己一直在用的小技巧。
装完nvm后，我会在项目根目录放一个.nvmrc文件，里面写上这个项目需要的Node版本号，比如20.11.0。每次拉新项目或者切分支后，先在终端执行nvm use，nvm会自动读取.nvmrc并切换到对应版本，不需要我再手动查版本号。这个习惯帮我省了无数次"忘了哪个项目用哪个Node"的烦恼。
还有个细节务必要养成：所有涉及nvm的命令，尽量都在管理员身份的终端里跑。你可以给Windows Terminal或者PowerShell设置默认以管理员运行，省得每次右键"以管理员身份运行"。Windows下用nvm，最大的敌人不是命令记不住，而是权限和PATH，把这两个理顺，整个Node开发环境会稳定很多。
