第一次接触Node.js的人，十个里有七个会倒在“装环境”这一步：官网上一堆版本号不知道选哪个，安装包下载完了一路点Next，最后在终端敲node -v却提示“不是内部或外部命令”。这篇文章就是专门解决这个问题的。我会从下载前的版本选择讲起，把Node.js下载安装及环境配置的每一步都拆开揉碎，包括安装向导里每个勾选框是干嘛的、环境变量怎么填、npm全局包路径为什么要改、镜像源加速怎么做，最后再附上我这些年踩过的坑和排查经验。整个过程全是零基础可以照着抄的操作，只要跟着走，基本十分钟内能跑通node -v和npm -v。
1. 下载准备：先把版本和安装包选对
很多新手直接冲到官网点了最大的那个绿色按钮，下载完装完才发现版本不对或者装成了绿色版，后面所有操作全乱套。所以在动手之前，先把这几个概念搞清楚，能省掉后面一大半麻烦。
1.1 LTS版还是Current版
打开Node.js官网，首页会有两个大按钮：一个是LTS（Long Term Support，长期支持版），一个是Current（尝鲜版）。这两个版本的区别非常明确：
- LTS版：官方承诺长期维护，稳定性最高，两年内会持续收到安全补丁和Bug修复。绝大部分第三方包、框架、脚手架都优先兼容它。做实际项目、学习新技术、公司生产环境部署，一律选LTS。
- Current版：包含最新的语法特性和实验性API，版本迭代快，可能每几个月就升一个版本号。但它才发布不久，很多新特性还没有经过大规模验证，第三方依赖也可能没跟上，装了之后很容易在下一步
npm install的时候踩坑。
我用一个生活化的类比：LTS是饭店菜单上的招牌菜，做了一两年，口味稳定，点什么人都不会踩雷；Current是每天的创意新菜，听着新鲜，但有时候配菜不齐或者主厨发挥不稳定。开发这件事最怕不稳定，所以老老实实选LTS。
具体到版本号，当前处于LTS状态的通常是20.x或22.x，以你在官网看到的“LTS”标识为准。新手不需要追求最新，认准写着LTS的那个按钮下载就行。
1.2 安装包格式：.msi还是.zip
官网下载页面通常提供两种格式：Windows Installer（.msi）和 Binary（.zip）。这两者的差别很关键：
- .msi安装包：带图形化安装向导，双击之后一路点下一步就行，安装过程会自动帮你写好系统环境变量，对新手极其友好。这是我最推荐的格式。
- .zip压缩包：属于绿色免安装版，解压出来就能用，不会写系统注册表，也不会自动配置环境变量。要用它就得自己手动去“系统属性 → 环境变量 → Path”里面加一条路径，而且后续升级还得重新替换文件，比较麻烦。
如果不是对系统洁癖有特殊要求，正常选.msi就够了。另外下载前顺手确认一下自己的系统位数：右键“此电脑” → “属性”，在“系统类型”里能看到是64位还是32位。现在绝大多数电脑都是64位的，选x64架构的安装包就行。安装包本身大概30MB左右，如果官网下载速度很慢，可以找国内镜像站点下载，版本校验一下安装包的数字签名或者文件哈希，确认无误再安装。
2. 安装过程：每一步的选择都有它的道理
下载好.msi文件之后双击运行，安装程序的界面看起来很简单，就是几个下一步，但我见过不少人在这几步里藏着地雷，装完就后悔。所以我把安装向导里的每个关键界面都单独拿出来讲一下。
2.1 安装目录：默认路径还是自定义路径
安装向导第一步是Welcome界面，直接Next。然后是License Agreement，勾选同意继续。接着进入Destination Folder（安装目录）选择界面，默认路径是C:\Program Files\nodejs\。
这里有两个选择：
- 保持默认：省心，后续所有教程里涉及的路径都是这个，不容易出错。
- 自定义到D盘：比如
D:\nodejs\，适合系统盘空间紧张、或者公司电脑C盘有权限管控的情况。注意自定义路径必须使用纯英文，不要带中文和空格。虽然Node.js本身支持中文路径，但某些老牌原生的npm原生模块在编译时会对路径做字符串处理，中文路径会触发一些莫名其妙的报错，这个我后面在常见问题里会再提。
安装目录决定完之后，后面还有一屏会问是否安装哪些组件（Custom Setup），这是整个安装过程最需要留意的部分。
2.2 Custom Setup里的组件分别是什么
这一屏是一个树形列表，默认全选。主要条目包括：
- Node.js runtime：核心运行环境，这个必须保留，不用动。
- npm package manager：Node.js的包管理器，装Node的时候会顺带装好。这个也必须保留，没有它就没法下载第三方库。
- Online documentation shortcuts：桌面文档快捷方式，纯粹是入口链接，不占多少空间，但也没太大用处，想界面干净可以取消。
- Add to PATH：这是最重要的一项，务必保持勾选。它负责把Node.js的可执行目录写进系统环境变量PATH里，否则装完你在终端里敲
node -v会直接提示找不到命令。很多人安装完成之后一脸懵，最后发现就是这里被手动取消了勾选。
还有一个组件可能叫“corepack”，它是一套用于管理包管理器版本的实验性工具，默认可以不勾选，普通开发用不到。总之，新手在这一屏里只需要记住一件事：只去掉“Online documentation shortcuts”可以，其他默认的别动。
2.3 “Download additional tools”到底要不要勾
安装向导快结束的界面会有一个复选框，大意是“Download additional tools for Node.js”，说明里写着会帮你安装Python和Visual Studio Build Tools。这个选项坑了不少人，因为勾选之后会弹出一个PowerShell窗口，自动用命令行下载安装一堆编译工具，过程特别长，看着像电脑死机了。
这个选项的本质，是通过包管理器把Python环境和C/C++编译器装到系统里，目的是为了支持node-gyp这类工具。当你安装的某个npm包需要从源代码编译原生模块时，比如常见的sharp、bcrypt、canvas、node-sass等，编译过程会调用Python和C++构建链，缺了就会报node-gyp相关的错误。
所以选择标准很简单：
- 你只写纯JavaScript代码，不打算碰这些需要原生编译的库——不要勾，会省很多时间。
- 你确定之后会用electron、sharp这类依赖原生模块的库——可以先不勾，等真遇到编译报错时再单独装Python和Visual Studio Build Tools，效果一样。
我个人的建议是：新手安装时不勾，保持环境干净。以后某个包安装报错，提示缺Python或C++编译器，再针对性地补装，这样你心里清楚这一步是干嘛用的，而不是稀里糊涂装了一堆东西。
2.4 安装完成后的第一步验证
安装向导跑完闭之后，重启一个终端窗口（这一步很关键，别在旧终端里测试），输入以下命令：
node -v npm -vnode -v会输出类似v22.x.x的版本号，npm -v会输出10.x.x这样的npm版本号。两条命令都能正常输出，说明Node.js和npm已经装好并且PATH环境变量生效了。
如果输出的是“node不是内部或外部命令”，大概率是安装时取消了Add to PATH，或者改过安装路径但PATH没有正确写入。处理办法：打开“系统属性 → 环境变量”，在系统变量里找到Path，确认里面是否包含了Node.js的安装目录，没有就手动加上，然后重新打开终端。
3. 环境配置：把npm全局包从C盘挪走
很多人装完Node.js，验证node -v没问题就觉得万事大吉了。直到某天安装某个全局工具，比如npm install -g nodemon，然后在任意目录敲命令发现报错“nodemon不是内部或外部命令”，这才意识到环境配置还没做完。这一章讲的就是Node.js环境配置里最核心的部分：npm全局路径。
3.1 默认全局路径到底坑在哪
默认情况下，npm的全局包安装目录是C:\Users\你的用户名\AppData\Roaming\npm。这个路径有三个问题：
- 占用C盘空间。全局工具、缓存文件都会写在系统盘，日积月累，C盘越来越满。
- 容易触发权限问题。当全局目录在系统盘深层路径时，某些工具在执行脚本或写入文件时会被Windows的UAC（用户账户控制）或杀毒软件拦一下，表现就是明明安装成功却运行失败。
- 路径太深，难以管理。你想找一个全局工具装到哪里了，还要一层层展开隐藏文件夹，非常麻烦。
所以在安装完Node.js之后，我习惯性的第一件事就是把npm全局目录改到其他盘，比如D:\nodejs\node_global，并把缓存目录改到D:\nodejs\node_cache。这样所有全局包都集中在同一个自定义目录下，方便查看和清理，也不会拖累系统盘。
3.2 修改npm全局路径的具体操作
首先在你想放置的磁盘下新建两个空目录，比如：
D:\nodejs\node_global D:\nodejs\node_cache然后在终端里执行以下两条命令：
npm config set prefix "D:\nodejs\node_global" npm config set cache "D:\nodejs\node_cache"这两条命令的意思是：告诉npm，以后全局安装的包都放到D:\nodejs\node_global里，下载的缓存都放到D:\nodejs\node_cache里。
验证是否生效：
npm config get prefix npm config get cache如果输出的路径是你刚设置的路径，说明配置已经写入。这个配置存储在你的用户配置文件.npmrc中，以后安装新的Node.js版本或者重装系统，只要备份这个文件，配置就能直接迁移，很省事。
3.3 环境变量里要填什么
改完路径之后，还需要让系统能找到这个新目录。打开“系统属性 → 环境变量”，在“系统变量”区域新建一个变量：
变量名：NODE_PATH 变量值：D:\nodejs\node_global\node_modules然后在系统变量Path中新增一条：
D:\nodejs\node_global注意这里的细节：D:\nodejs\node_global加到Path里，是为了让全局安装的某个可执行命令（比如nodemon）能在任意目录直接被终端找到。NODE_PATH则是让Node.js在require()一个没有显式指定路径的模块时，能从全局节点模块目录去查找。两者缺一不可，但也别把Node.js的安装目录和全局包目录搞混了。
修改完环境变量之后，必须把当前所有终端窗口完全关闭再重新打开，因为终端启动时会读取一次环境变量快照，旧窗口不会自动刷新。这也是新手最常踩的坑之一：明明配好了，敲命令却说找不到，急得团团转，其实只是没重开终端。
3.4 PowerShell执行策略报错
改完路径和变量之后，当你第一次使用某个全局工具（比如后面可能会用到的Vue脚手架）时，可能会遇到这样一个报错：
无法加载文件 D:\nodejs\node_global\vue.ps1，因为在此系统上禁止运行脚本。这个报错不是Node.js的问题，而是Windows PowerShell的默认执行策略在限制脚本运行。Windows默认的ExecutionPolicy是Restricted，即禁止运行任何本地脚本文件。.ps1文件正是脚本文件，所以被拦下来了。
解决办法是用管理员身份打开PowerShell，然后执行：
Set-ExecutionPolicy RemoteSigned执行后会提示是否确认更改，输入Y回车。这个策略的含义是：本地创建的脚本可以运行，从远程下载的脚本需要数字签名才能运行。对我们普通开发场景已经够用，也不会造成什么安全风险。
如果实在不想改动系统执行策略，也可以用命令提示符（CMD）代替PowerShell来执行npm命令，CMD不会受ExecutionPolicy限制。但全局工具的脚本最终可能还是会调用Powershell，所以稳妥起见，建议按上面方式设置一次。
4. 镜像源配置：解决npm install 卡死和超时
如果你已经按照前面的步骤把Node.js跑起来了，接下来面临的问题大概率就是npm install很慢或者直接卡住。这一章讲清楚镜像源是怎么回事，以及一条命令就能解决的加速方案。
4.1 什么是registry，为什么慢
npm默认从官方源https://registry.npmjs.org/下载包，这个源服务器在境外。当你执行npm install express时，npm会先去这个地址查找包的元信息，再按照信息去下载对应文件。由于物理距离和网络链路过长，很容易出现两种情况：
- 下载速度极慢：一个只有几百KB的小包，可能要等好几分钟。
- 超时或连接中断：终端卡在
sill idealTree之类的输出上一动不动，最后报ETIMEDOUT或ECONNRESET之类的网络错误。
这种问题跟Node.js的安装本身无关，单纯是网络链路的问题，解决思路是换一个离自己更近的下载源，也就是镜像源。
4.2 一条命令切换npm镜像源
国内比较常用且维护稳定的npm镜像源是https://registry.npmmirror.com/，它是npm官方仓库的一个定期同步镜像，里面的包内容和官方源基本保持一致。
终端里执行：
npm config set registry https://registry.npmmirror.com/验证是否生效：
npm config get registry输出显示https://registry.npmmirror.com/，说明切换成功。之后所有的npm install都会从这个镜像源下载，速度感知会非常明显。
如果你只是临时想用某个源，不想全局改动，也可以在安装时指定：
npm install express --registry=https://registry.npmmirror.com/这种方式不会改变全局配置，适合只在某一次安装时想试试不同源的场景。但日常使用还是建议直接改全局配置，省得每次敲一长串参数。
4.3 镜像源配置的实操心得
配置完镜像源之后，我建议顺手做一次完整验证：随便找一个空目录，执行npm install lodash，观察整个下载过程是否流畅。如果还是在某个阶段卡住，先清掉npm缓存再重试：
npm cache clean --force这里补充一个经常被忽略的点：npm在下载包时会有本地缓存，如果之前用慢源下载了一半的残留数据，可能影响后续安装，清理缓存能让安装过程恢复到干净状态。
还有一个细节：有些团队或公司内部会搭建私有的npm仓库，比如通过内部的管理平台同步镜像。如果未来在某个公司工作，入职时记得问一句“公司内部npm镜像地址是什么”，执行一次npm config set registry切到内部源就行，原理和上面完全一样。
切换镜像源之后，偶尔会遇到某个刚发布不到几个小时的包下载不到，这不用慌，镜像同步存在延迟，一般过一天就正常了。遇到这种情况，临时切换到官方源安装那一次，再切回来就好。
5. 常见问题排查与避坑速查表
这一章汇总我在实操过程中真正遇到过的报错，每一条都是真实可复现的，给出的解决办法也是亲测有效的。做成了速查表，方便遇到问题时直接对号入座。
5.1 命令找不到类报错怎么排查
这是最高频的一类问题，表现形式是终端提示“node不是内部或外部命令”“npm不是内部或外部命令”“xxx不是内部或外部命令”，处理思路分三类：
| 报错内容 | 可能原因 | 排查顺序 |
|---|---|---|
| node不是内部或外部命令 | 安装时未勾选Add to PATH，或Path里Node.js目录被删 | 检查系统变量Path是否有Node.js安装目录，没有则补上 |
| npm不是内部或外部命令 | npm脚本文件缺失或PATH异常 | 先确认node可用，再看npm是否存在于Node.js安装目录，最后重装 |
| 某个全局工具不是内部或外部命令 | npm prefix目录没有加入Path | 在Path中手动添加npm全局目录（如D:\nodejs\node_global） |
排查这类问题有一个通用思路：先确定“这个命令对应哪个可执行文件”，再去检查“这个可执行文件所在的目录是否在PATH环境变量中”。所有命令找不到的问题，最终都能归结到这两件事上。
5.2 版本号和安装残留问题
有时候你明明装了新版Node.js，但node -v输出的还是老版本号，或者npm -v和node -v版本看起来完全不匹配。这种问题大概率是系统里有旧版残留。
具体检查几个位置：
- 控制面板的“程序和功能”里是否还有旧版Node.js。
C:\Program Files\nodejs目录里是否残留旧文件。C:\Users\用户名\AppData\Roaming\npm里是否有旧的全局命令。
处理办法是把旧的彻底卸载干净，重启电脑，再重新安装新版本。安装新版本之前，也别忘备份之前配置的.npmrc文件，里面存着镜像源、prefix、cache等配置，重装完后直接复用，能省不少时间。
另外提一嘴安全软件拦截问题。某些安全软件会把Node.js或npm下载的脚本文件当作可疑程序拦截，导致安装过程中断或全局工具无法运行。这属于误报，遇到时先在安全软件里查看隔离记录，恢复被拦截的文件，把Node.js安装目录加入信任列表即可。别一看到拦截就重装系统，真的多走了很多弯路。
5.3 npm install卡住的实战处理
npm install卡在某个进度提示不动，是最让人焦虑的问题之一。根据我的经验，按下面顺序排查命中率最高：
- 看registry是否为镜像源：执行
npm config get registry，确认不是官方源。 - 清缓存再重试：
npm cache clean --force之后重新安装。 - 删除node_modules和锁文件：在项目目录里把
node_modules文件夹和package-lock.json删除，再执行一次npm install。这个方法能处理很多因为依赖树不一致导致的卡死。 - 看具体卡在哪一步：如果卡在某个具体包上，单独安装那个包试试，确认是不是包源问题。
如果以上步骤都无效，还有一个杀手锏是把npm版本单独升级一次：
npm install -g npm@latestnpm自身的版本也会影响依赖解析的效率，升级到最新版通常会修复一些已知的安装卡顿问题。
6. 进阶方案：用nvm同时管理多个Node版本
如果你的Node.js开发之路打算长期走，那迟早会遇到一个问题：不同项目要求的Node版本不一样。旧项目可能锁定在16.x上跑，新项目却要求20.x以上，这时候手动卸载装一遍，折腾到怀疑人生。这一章讲一个更成熟的方案：nvm多版本管理。
6.1 为什么nvm是“环境配置”的终极方案
nvm（Node Version Manager）是一个能让你在同一台电脑上安装多个Node.js版本，并随时切换当前默认版本的工具。它的作用和虚拟机类似，但更轻量，切换成本几乎为零。配合前面讲的npm镜像源，基本可以做到“一个终端，随意切换”，项目的开发环境不再互相干扰。
Windows平台上有专门的nvm-windows版本，安装方式很简单：从它的GitHub仓库下载安装包，一路安装即可。安装完成后常用命令只有三个：
nvm install 20 nvm use 20 nvm lsnvm install 20会安装Node.js 20.x最新版，nvm use 20会把当前终端的Node版本切换为20.x，nvm ls列出当前系统已安装的所有Node版本，带星号的是当前正在使用的版本。
6.2 已经装了单版本Node.js的迁移思路
如果你已经按照前面步骤装好了单版本Node.js，现在想换成nvm，操作步骤也不复杂：
- 备份
.npmrc文件（记录着镜像源和自定义路径配置）。 - 卸载当前Node.js，卸载前先去“系统属性 → 环境变量”里把手动加的Node相关Path清理掉，避免残留干涉。
- 安装nvm-windows。
- 用
nvm install重新安装你需要的Node版本。 - 用
nvm use切换到你想要的版本。 - 把备份的
.npmrc内容恢复到用户根目录下。
必须提醒的是，nvm和普通安装的Node.js同时存在会互相冲突，所以如果你决定用nvm，就先卸载单独的Node.js再装，别懒得卸，不然切版本时容易出一些诡异问题。如果只是刚开始学Node.js基础语法，直接用单版本就够了，不需要额外增加nvm的学习成本；但如果你确定以后会长期做前端或Node后端开发，尽早切换到nvm是一笔很划算的“基建投资”。
还有一个很实用的小技巧：nvm本身也支持配置全局npm镜像，所以装完nvm之后，记得立刻执行一次npm config set registry https://registry.npmmirror.com/，不然第一次安装包又会踩一遍慢源的坑。
我在实际安装Node.js的过程中，来来回回折腾了几十回，踩过最多的坑基本集中在三个点：版本选错、PATH没生效、镜像没配好。只要把这三件事按顺序确认一遍，剩下的一切都会顺畅很多。这篇教程里所有的路径、命令、顺序，都是我自己验证过的最省事流程，尤其是“改全局路径时先把目录建好”和“配完环境变量后必须完全重开终端”这两个细节，关键时刻真的救过我好多次。如果你安装后还是遇到问题，先回头看环境变量的配置，然后重启终端，大部分问题都能在这步解决。
